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

• Multimodal Experiences: 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).

• Step Tracking: Recording granular user progress through a defined script flow for analytics.

• Context Passing: Sending data (like form selections) from the UI back to the voice application.

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.

Note: These credentials (apiKey, workspaceId, scriptId) are typically provided in your Voice+ journey configuration.

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

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

{
  "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"
}