# Track

The Voice+ Track API allows you to track user progress through multimodal voice journeys. By sending step transitions from your visual interface (web/mobile) to NLX, you can coordinate the state between the voice agent and the user's screen in real-time.

### When to use this API

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-mobile">:mobile:</i></td><td><strong>Multimodal experiences</strong></td><td>Synchronizing a website or mobile app with an active phone call (e.g., a user clicks "Select Seat" on the web, and the voice bot acknowledges it immediately)</td></tr><tr><td><i class="fa-sneaker-running">:sneaker-running:</i></td><td><strong>Step tracking</strong></td><td>Recording granular user progress through a defined script flow for analytics</td></tr><tr><td><i class="fa-truck-fast">:truck-fast:</i></td><td><strong>Context passing</strong></td><td>Sending data (like form selections) from the UI back to the voice application</td></tr></tbody></table>

### Authentication

This endpoint uses a different authentication scheme than the standard Conversation API. It requires two headers:

| Header      | Value                 | Description                    |
| ----------- | --------------------- | ------------------------------ |
| `x-api-key` | `YOUR_VOICE_PLUS_KEY` | Your specific Voice+ API key.  |
| `x-nlx-id`  | `YOUR_WORKSPACE_ID`   | Your NLX Workspace identifier. |

{% hint style="info" %}
These credentials (`apiKey`, `workspaceId`, `scriptId`) are typically provided in your Voice+ journey configuration.
{% endhint %}

#### Track a step (`POST /v1/track`)

Send a signal that a specific step in the journey has been completed or triggered.

**Endpoint:** `https://apps.nlx.ai/v1/track`

**Request body**

| Field            | Type   | Required                                          | Description                                                     |
| ---------------- | ------ | ------------------------------------------------- | --------------------------------------------------------------- |
| `stepId`         | UUID   | Yes                                               | Unique ID of the step being tracked.                            |
| `conversationId` | String | Yes                                               | The active voice session ID (usually passed via URL param).     |
| `journeyId`      | UUID   | Yes                                               | The ID of the script/journey being executed.                    |
| `languageCode`   | String | Yes                                               | Language code (e.g., `en-US`).                                  |
| `context`        | Object | No (may be empty, but cannot be omitted; pass {}) | JSON object containing payload data (e.g., `{ "seat": "1A" }`). |

**Example request**

```bash
curl -X POST "https://mm.nlx.ai/v1/track" \
  -H "x-api-key: YOUR_VOICE+_API_KEY" \
  -H "x-nlx-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "stepId": "550e8400-e29b-41d4-a716-446655440000",
    "conversationId": "79d44cb1-88cd-4533-9908-cb0258c8b2c6",
    "journeyId": "e898f734-c9df-4903-843a-225be880ce1a",
    "languageCode": "en-US",
    "context": {
      "selectedSeat": "4A",
      "flightNumber": "UA1234"
    }
  }'
```

**Example response**

```json
{
  "success": true,
  "stepId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "conversationId": "79d44cb1-88cd-4533-9908-cb0258c8b2c6",
  "journeyId": "e898f734-c9df-4903-843a-225be880ce1a"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nlx.ai/platform/developers/voice+-api/track.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.