# 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       | 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"
}
```