Mint shadow-call token | Speechify API

Mint a listen-only realtime access token so an authorized observer can join an ongoing voice-agent conversation as a hidden participant. Any member, admin, or owner of the workspace the conversation belongs to may listen in — it is read-only observation. The token cannot publish audio or data; the observer is invisible to the caller and the agent. Speechify support engineers reach this endpoint the same way as any other observer — by being granted a role on the customer’s workspace (typically under an NDA-backed support arrangement).

Mint a listen-only realtime access token so an authorized observer can join an ongoing voice-agent conversation as a hidden participant. Any `member`, `admin`, or `owner` of the workspace the conversation belongs to may listen in — it is read-only observation. The token cannot publish audio or data; the observer is invisible to the caller and the agent. Speechify support engineers reach this endpoint the same way as any other observer — by being granted a role on the customer's workspace (typically under an NDA-backed support arrangement).

Authentication

AuthorizationBearer

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

Path parameters

conversation_idstringRequired

Conversation id (prefixed external id, conv_...).

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.

Response

Shadow-call connection details.

conversation_idstringformat: "^conv_[0-9a-hjkmnp-tv-z]{26}$"

signaling_urlstring

wss://… signaling URL the realtime client connects to.

tokenstring

Short-lived realtime access token. The grant is listen-only (cannot publish audio or data) and hidden, so the observer can hear the call but cannot speak and is invisible to the caller and the agent.

identitystring

Opaque participant identity tag (e.g. shadow_<hex>). Visible only to admin tooling.

expires_atdatetime

When the token stops being accepted by the realtime provider. Re-mint past this point.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

1	{
2	"conversation_id": "conv_01jqr8x9zg5k2m3n4p5q6r7s8t",
3	"signaling_url": "https://example.com/webhook",
4	"token": "tok_01jqr8x9zg5k2m3n4p5q6r7s8t",
5	"identity": "example",
6	"expires_at": "2026-06-24T18:03:11Z"
7	}