Issue MQTT Operator Token

Issue a short-lived MQTT operator token for Transparency Mode.

Use this endpoint from a trusted backend or server-side operator agent. Pass the project API key in the license header. The endpoint has no request body.

The returned token allows the operator to subscribe to user messages and publish replies/presence on the project-scoped transparency MQTT topics.

POST /api/open/v1/mqtt/operator-token

Issue MQTT Operator Token

cURL

curl --request POST \
  --url https://api.navtalk.ai/api/open/v1/mqtt/operator-token \
  --header 'license: <api-key>'

200

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "brokerUrl": "mqtts://mqtt.navtalk.ai:8883",
    "projectId": "project_123",
    "prefix": "navtalk/transparent",
    "authType": "mqtt_operator",
    "token": "eyJhbGciOi...",
    "expiresAt": "2026-07-04T10:00:00Z",
    "expiresInSeconds": 604800,
    "args": {
      "broker-url": "mqtts://mqtt.navtalk.ai:8883",
      "token": "eyJhbGciOi...",
      "prefix": "navtalk/transparent"
    },
    "topics": {
      "subscribe": "navtalk/transparent/project_123/+/user",
      "reply": "navtalk/transparent/project_123/{sessionId}/reply",
      "presence": "navtalk/transparent/project_123/agent/presence"
    },
    "scriptCommand": "python transparent_mqtt_agent.py --broker-url mqtts://mqtt.navtalk.ai:8883 --token eyJhbGciOi... --prefix navtalk/transparent"
  }
}

Use this endpoint to issue a short-lived MQTT operator token for Transparency Mode.

The token lets your backend or operator agent subscribe to user messages and publish replies through the NavTalk hosted MQTT broker. The endpoint does not require a request body. Pass your project API key in the license header.

Python agent usage

The sample operator agent fetches this token automatically when you pass --api-key:

python transparent_mqtt_agent.py --api-key YOUR_NAVTALK_PROJECT_API_KEY

Internally, the agent calls:

import requests

response = requests.post(
    "https://api.navtalk.ai/api/open/v1/mqtt/operator-token",
    headers={"license": "YOUR_NAVTALK_PROJECT_API_KEY"},
    timeout=10,
)
token_data = response.json()["data"]

It then uses the returned brokerUrl, projectId, prefix, and token to connect to MQTT.

Topic usage

The response includes ready-to-use topic templates:

• topics.subscribe: subscribe to user messages, for example navtalk/transparent/{projectId}/+/user
• topics.reply: publish operator replies, for example navtalk/transparent/{projectId}/{sessionId}/reply
• topics.presence: publish operator online/offline status, for example navtalk/transparent/{projectId}/agent/presence

When replying, replace {sessionId} with the session ID from the user message topic.

Reply payload

For a final text reply, publish this JSON to the reply topic:

{
  "type": "transparent.reply.text",
  "session_id": "SESSION_ID",
  "roomId": "SESSION_ID",
  "source": "operator",
  "text": "Hello, how can I help you?",
  "messageId": "mqtt_agent_1780000000000"
}

For streaming replies, publish transparent.reply.text.delta messages first, then finish with transparent.reply.text.done.

Do not expose the returned MQTT token in browser code. Fetch it from your backend or run the Python operator agent in a trusted server environment.

Authorizations

license · string · header · required

NavTalk API license key (e.g. sk_navtalk_...)

Response

200

application/json

MQTT operator token issued successfully

code · integer

Example:

200

message · string

Example:

"SUCCESS"

data · object

Show child attributes