Create Conversation | SpeechifyAI 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": {
    "account_metadata": {
      "plan": "enterprise",
      "seats": 50
    },
    "product_name": "Acme Pro",
    "support_tier": 2
  }
}'

{
  "conversation": {
    "id": "conv_01kr410dd3yrst4chn5kn0t78f",
    "agent_id": "agent_01HS...",
    "status": "pending",
    "transport": "web",
    "created_at": "2024-01-15T09:30:00Z",
    "metadata": {},
    "message_count": 0
  },
  "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

agent_idstringRequired

Agent id (prefixed external id, agent_...).

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

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 headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

RateLimit-Limit-Callsinteger

Active-call concurrency budget: the per-workspace cap on simultaneously-active voice calls (the voice analog of a token axis). Sent on successful call-start responses (web session, outbound call).

RateLimit-Remaining-Callsinteger

Active-call concurrency budget: free active-call slots after this call reserved one. 0 on a 429 that rejected for concurrency exhaustion (concurrency_limit_reached).

Response

The created conversation with its realtime session token.

conversationobject

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

409

Conflict Error