Create Conversation | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/agent_01HS.../conversations \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "dynamic_variables": {
    "product_name": "Acme Pro",
    "support_tier": 2,
    "account_metadata": {
      "plan": "enterprise",
      "seats": 50
    }
  }
}'

{
  "conversation": {
    "id": "conv_01kr410dd3yrst4chn5kn0t78f",
    "agent_id": "agent_01HS...",
    "room_name": "conv_01kr410dd3yrst4chn5kn0t78f",
    "status": "pending",
    "transport": "web",
    "created_at": "2024-01-15T09:30:00Z",
    "metadata": {},
    "message_count": 0
  },
  "room": "conv_01kr410dd3yrst4chn5kn0t78f",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjb252In0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "url": "wss://realtime.speechify.ai/conv_01kr410dd3yrst4chn5kn0t78f"
}

Pass dynamic_variables to supply per-session values that override the agent’s stored variable defaults for this one conversation. Keys in the system__ namespace are rejected at this boundary.

Start a new voice conversation with the agent. Returns a realtime voice session + short-lived client token so the caller can connect the audio pipeline directly. The agent is dispatched server-side; no additional client action required. Pass `dynamic_variables` to supply per-session values that override the agent's stored variable defaults for this one conversation. Keys in the `system__` namespace are rejected at this boundary.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

idstringRequired

Request

This endpoint expects an object.

transportstring or nullOptional

Transport hint. Omit to use the agent's default.

dynamic_variablesmap from strings to anyOptional

Per-session variable overrides that merge on top of the agent’s stored variable defaults for this one conversation. Keys in the reserved system__ namespace are rejected. Values must match the declared type of the corresponding variable definition on the agent.

Response

The created conversation with its realtime session token.

conversationobject

roomstring

tokenstring

Short-lived realtime session access token (JWT).

urlstring

Realtime session wss:// URL to connect to.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error