> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # WebSocket > Stream audio and events between an application and a Managed Agent. Server applications authenticate with `X-API-Key`; browser and mobile applications pass an `access_token` query parameter. See the [WebSocket guide](/line/integrations/websocket-api) for setup, limits, and audio handling. ## AsyncAPI ````yaml asyncapi.yml /v1/agents/websocket/{agent_id} id: /v1/agents/websocket/{agent_id} title: /v1/agents/websocket/{agent_id} description: > Stream audio and events between an application and a Managed Agent. Server applications authenticate with `X-API-Key`; browser and mobile applications pass an `access_token` query parameter. See the [WebSocket guide](/line/integrations/websocket-api) for setup, limits, and audio handling. servers: - id: production protocol: wss host: api.cartesia.ai bindings: [] variables: [] address: /v1/agents/websocket/{agent_id} parameters: - id: agent_id jsonSchema: type: string description: | ID of the managed agent to connect to. description: | ID of the managed agent to connect to. type: string required: true deprecated: false - id: cartesia_version jsonSchema: type: string description: API version, e.g. `2026-08-14` description: API version, e.g. `2026-08-14` type: string required: true deprecated: false bindings: [] operations: - &ref_1 id: sendAgentWebSocketEvents title: Send agent web socket events description: Events your client sends to the agent. type: receive messages: - &ref_3 id: agentSessionCreateEvent payload: - name: Session Create description: > Configures the session's audio. **This must be the first message sent.** The server closes the connection if any other event arrives first, or if no event arrives within 10 seconds. Unknown fields are rejected. type: object properties: - name: type type: string description: Event type identifier. enumValues: - session_create required: true - name: audio type: object required: true properties: - name: input_format type: string description: >- Format of the audio your client sends. Agent audio is returned in the same format. Required, because a sample rate that mismatches your capture format fails silently as garbled audio. enumValues: - mulaw_8000 - pcm_16000 - pcm_24000 - pcm_44100 required: true - name: output_delivery type: string description: >- How the server delivers agent audio. `speaking_pace` paces audio to playback speed. `as_available` sends it as fast as the model produces it, so a client that buffers locally can play it back on its own clock for lower latency. Not supported when the agent uses a background sound. enumValues: - speaking_pace - as_available required: false headers: [] jsonPayloadSchema: type: object additionalProperties: false required: - type - audio properties: type: type: string enum: - session_create description: Event type identifier. x-parser-schema-id: audio: type: object additionalProperties: false required: - input_format properties: input_format: type: string enum: - mulaw_8000 - pcm_16000 - pcm_24000 - pcm_44100 description: >- Format of the audio your client sends. Agent audio is returned in the same format. Required, because a sample rate that mismatches your capture format fails silently as garbled audio. x-parser-schema-id: output_delivery: type: string enum: - speaking_pace - as_available default: speaking_pace description: >- How the server delivers agent audio. `speaking_pace` paces audio to playback speed. `as_available` sends it as fast as the model produces it, so a client that buffers locally can play it back on its own clock for lower latency. Not supported when the agent uses a background sound. x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: AgentSessionCreateEvent title: Session Create description: > Configures the session's audio. **This must be the first message sent.** The server closes the connection if any other event arrives first, or if no event arrives within 10 seconds. Unknown fields are rejected. example: |- { "type": "session_create", "audio": { "input_format": "pcm_44100", "output_delivery": "speaking_pace" } } bindings: [] extensions: - id: x-parser-unique-object-id value: agentSessionCreateEvent - &ref_4 id: agentAudioInputEvent payload: - name: Audio Input description: > Streams user audio to the agent. Send chunks continuously (for example every 20–100 ms) for the best latency. `audio` must be base64-encoded audio in the format declared in `session_create.audio.input_format`. Wait for `session_ready` before sending audio; audio sent earlier is dropped. type: object properties: - name: type type: string description: Event type identifier. enumValues: - audio_input required: true - name: audio type: string description: >- Base64-encoded audio in the format declared in `session_create.audio.input_format`. required: true headers: [] jsonPayloadSchema: type: object required: - type - audio properties: type: type: string enum: - audio_input description: Event type identifier. x-parser-schema-id: audio: type: string description: >- Base64-encoded audio in the format declared in `session_create.audio.input_format`. x-parser-schema-id: x-parser-schema-id: AgentAudioInputEvent title: Audio Input description: > Streams user audio to the agent. Send chunks continuously (for example every 20–100 ms) for the best latency. `audio` must be base64-encoded audio in the format declared in `session_create.audio.input_format`. Wait for `session_ready` before sending audio; audio sent earlier is dropped. example: |- { "type": "audio_input", "audio": "base64_encoded_audio_data" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentAudioInputEvent - &ref_5 id: agentDtmfInputEvent payload: - name: DTMF Input description: | Sends a DTMF (dual-tone multi-frequency) digit to the agent. type: object properties: - name: type type: string description: Event type identifier. enumValues: - dtmf_input required: true - name: digit type: string description: A single DTMF digit, one of `0`-`9`, `*`, or `#`. required: true headers: [] jsonPayloadSchema: type: object required: - type - digit properties: type: type: string enum: - dtmf_input description: Event type identifier. x-parser-schema-id: digit: type: string description: A single DTMF digit, one of `0`-`9`, `*`, or `#`. pattern: ^[0-9*#]$ minLength: 1 maxLength: 1 x-parser-schema-id: x-parser-schema-id: AgentDtmfInputEvent title: DTMF Input description: | Sends a DTMF (dual-tone multi-frequency) digit to the agent. example: |- { "type": "dtmf_input", "digit": "5" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentDtmfInputEvent - &ref_6 id: agentClientToolResultEvent payload: - name: Client Tool Result description: > Answers a `client_tool_call` whose `expects_response` is `true`. `tool_call_id` must match the call being answered. The decoded `result` may be at most 4 KiB; larger results are replaced with a `result_too_large` error result. Late, duplicate, or mismatched results are ignored. type: object properties: - name: type type: string description: Event type identifier. enumValues: - client_tool_result required: true - name: tool_call_id type: string description: The `tool_call_id` from the `client_tool_call` being answered. required: true - name: result type: string description: >- The tool's result, as a string the model can read. At most 4 KiB decoded. required: true - name: is_error type: boolean description: >- Set to `true` when the tool failed. The agent sees the result as an error. required: false - name: error_type type: string description: >- Optional machine-readable category for a failure, such as `timeout`. required: false headers: [] jsonPayloadSchema: type: object required: - type - tool_call_id - result properties: type: type: string enum: - client_tool_result description: Event type identifier. x-parser-schema-id: tool_call_id: type: string maxLength: 256 description: The `tool_call_id` from the `client_tool_call` being answered. x-parser-schema-id: result: type: string description: >- The tool's result, as a string the model can read. At most 4 KiB decoded. x-parser-schema-id: is_error: type: boolean default: false description: >- Set to `true` when the tool failed. The agent sees the result as an error. x-parser-schema-id: error_type: type: string maxLength: 256 description: >- Optional machine-readable category for a failure, such as `timeout`. x-parser-schema-id: x-parser-schema-id: AgentClientToolResultEvent title: Client Tool Result description: > Answers a `client_tool_call` whose `expects_response` is `true`. `tool_call_id` must match the call being answered. The decoded `result` may be at most 4 KiB; larger results are replaced with a `result_too_large` error result. Late, duplicate, or mismatched results are ignored. example: |- { "type": "client_tool_result", "tool_call_id": "call_2b7e4f9a1c0d", "result": "2 items in cart", "is_error": false } bindings: [] extensions: - id: x-parser-unique-object-id value: agentClientToolResultEvent bindings: [] extensions: &ref_0 - id: x-parser-unique-object-id value: /v1/agents/websocket/{agent_id} - &ref_2 id: receiveAgentWebSocketEvents title: Receive agent web socket events description: > Events the server sends to your client. `session_ready`, `audio_output`, `audio_output_clear`, `dtmf_output`, `client_tool_call`, and `error` require client behavior. The turn events are telemetry: use them to build transcripts and speaking indicators, but ignoring them must not break a call. New event types may be added over time, so ignore any event you do not recognize instead of treating it as an error. type: send messages: - &ref_7 id: agentSessionReadyEvent payload: - name: Session Ready description: > Sent once after `session_create`, when the agent pipeline can accept audio. Reports the call record created for this session and the agent version the session is pinned to. Use `call_id` with the [calls API](/api-reference/agents/calls/get-call) to fetch the recording and transcript after the call. type: object properties: - name: type type: string description: Event type identifier. enumValues: - session_ready required: true - name: call_id type: string description: >- Identifier of the call record created for this session. Use it with the calls API to fetch the recording and transcript after the call. required: true - name: agent_id type: string description: The connected agent. required: true - name: agent_version_id type: string description: >- The agent version this session is pinned to, which is the version published when the connection opened. required: true - name: audio type: object required: true properties: - name: input_format type: string description: The accepted input format, echoed from `session_create`. required: false - name: output_delivery type: string description: The resolved output delivery mode. required: false headers: [] jsonPayloadSchema: type: object required: - type - call_id - agent_id - agent_version_id - audio properties: type: type: string enum: - session_ready description: Event type identifier. x-parser-schema-id: call_id: type: string description: >- Identifier of the call record created for this session. Use it with the calls API to fetch the recording and transcript after the call. x-parser-schema-id: agent_id: type: string description: The connected agent. x-parser-schema-id: agent_version_id: type: string description: >- The agent version this session is pinned to, which is the version published when the connection opened. x-parser-schema-id: audio: type: object properties: input_format: type: string description: The accepted input format, echoed from `session_create`. x-parser-schema-id: output_delivery: type: string description: The resolved output delivery mode. x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: AgentSessionReadyEvent title: Session Ready description: > Sent once after `session_create`, when the agent pipeline can accept audio. Reports the call record created for this session and the agent version the session is pinned to. Use `call_id` with the [calls API](/api-reference/agents/calls/get-call) to fetch the recording and transcript after the call. example: |- { "type": "session_ready", "call_id": "ac_gqkgRWUz2u64qFUjA1mZyr", "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE", "agent_version_id": "av_7Hq2mXbK9cLdNfPzR3tWvE", "audio": { "input_format": "pcm_44100", "output_delivery": "speaking_pace" } } bindings: [] extensions: - id: x-parser-unique-object-id value: agentSessionReadyEvent - &ref_8 id: agentAudioOutputEvent payload: - name: Audio Output description: > The agent's speech. `audio` is base64-encoded audio in the format declared in `session_create.audio.input_format`. type: object properties: - name: type type: string description: Event type identifier. enumValues: - audio_output required: true - name: audio type: string description: >- Base64-encoded agent audio in the format declared in `session_create.audio.input_format`. required: true headers: [] jsonPayloadSchema: type: object required: - type - audio properties: type: type: string enum: - audio_output description: Event type identifier. x-parser-schema-id: audio: type: string description: >- Base64-encoded agent audio in the format declared in `session_create.audio.input_format`. x-parser-schema-id: x-parser-schema-id: AgentAudioOutputEvent title: Audio Output description: > The agent's speech. `audio` is base64-encoded audio in the format declared in `session_create.audio.input_format`. example: |- { "type": "audio_output", "audio": "base64_encoded_audio_data" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentAudioOutputEvent - &ref_9 id: agentAudioOutputClearEvent payload: - name: Audio Output Clear description: > Sent when the user starts speaking. Discard buffered agent audio and stop playback. The event can arrive while no agent audio is playing, in which case there is nothing to clear. type: object properties: - name: type type: string description: Event type identifier. enumValues: - audio_output_clear required: true headers: [] jsonPayloadSchema: type: object required: - type properties: type: type: string enum: - audio_output_clear description: Event type identifier. x-parser-schema-id: x-parser-schema-id: AgentAudioOutputClearEvent title: Audio Output Clear description: > Sent when the user starts speaking. Discard buffered agent audio and stop playback. The event can arrive while no agent audio is playing, in which case there is nothing to clear. example: |- { "type": "audio_output_clear" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentAudioOutputClearEvent - &ref_10 id: agentDtmfOutputEvent payload: - name: DTMF Output description: > A DTMF digit the agent sends, for clients bridging a telephony system. type: object properties: - name: type type: string description: Event type identifier. enumValues: - dtmf_output required: true - name: digit type: string description: A single DTMF digit, one of `0`-`9`, `*`, or `#`. required: true headers: [] jsonPayloadSchema: type: object required: - type - digit properties: type: type: string enum: - dtmf_output description: Event type identifier. x-parser-schema-id: digit: type: string description: A single DTMF digit, one of `0`-`9`, `*`, or `#`. pattern: ^[0-9*#]$ minLength: 1 maxLength: 1 x-parser-schema-id: x-parser-schema-id: AgentDtmfOutputEvent title: DTMF Output description: | A DTMF digit the agent sends, for clients bridging a telephony system. example: |- { "type": "dtmf_output", "digit": "5" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentDtmfOutputEvent - &ref_11 id: agentClientToolCallEvent payload: - name: Client Tool Call description: > The agent asks this client to run a client tool. When `expects_response` is `true`, answer with a `client_tool_result` carrying the same `tool_call_id`; the invocation stays open until a result, error, or timeout. When `false`, dispatching the action completes the invocation. type: object properties: - name: type type: string description: Event type identifier. enumValues: - client_tool_call required: true - name: tool_call_id type: string description: Identifies this invocation. Echo it in `client_tool_result`. required: true - name: tool_name type: string description: Name of the client tool to run. required: true - name: parameters type: object description: Arguments for the tool, matching the tool's parameter schema. required: true - name: expects_response type: boolean description: >- Whether the agent waits for a `client_tool_result`. Comes from the tool's definition. required: true headers: [] jsonPayloadSchema: type: object required: - type - tool_call_id - tool_name - parameters - expects_response properties: type: type: string enum: - client_tool_call description: Event type identifier. x-parser-schema-id: tool_call_id: type: string description: Identifies this invocation. Echo it in `client_tool_result`. x-parser-schema-id: tool_name: type: string description: Name of the client tool to run. x-parser-schema-id: parameters: type: object description: Arguments for the tool, matching the tool's parameter schema. x-parser-schema-id: expects_response: type: boolean description: >- Whether the agent waits for a `client_tool_result`. Comes from the tool's definition. x-parser-schema-id: x-parser-schema-id: AgentClientToolCallEvent title: Client Tool Call description: > The agent asks this client to run a client tool. When `expects_response` is `true`, answer with a `client_tool_result` carrying the same `tool_call_id`; the invocation stays open until a result, error, or timeout. When `false`, dispatching the action completes the invocation. example: |- { "type": "client_tool_call", "tool_call_id": "call_2b7e4f9a1c0d", "tool_name": "open_cart", "parameters": { "cart_id": "cart_456" }, "expects_response": true } bindings: [] extensions: - id: x-parser-unique-object-id value: agentClientToolCallEvent - &ref_12 id: agentTurnStartedEvent payload: - name: Turn Started description: > Sent when the user starts speaking or the agent starts responding. `turn` comes from a single counter shared by both roles, starting at 1 and strictly increasing over the call, so `turn` alone identifies a turn. type: object properties: - name: type type: string description: Event type identifier. enumValues: - turn_started required: true - name: turn type: integer description: Turn index, unique across the call. required: true - name: role type: string description: Who is speaking. enumValues: - user - assistant required: true - name: start_time type: number description: Seconds since the start of the session. required: true headers: [] jsonPayloadSchema: type: object required: - type - turn - role - start_time properties: type: type: string enum: - turn_started description: Event type identifier. x-parser-schema-id: turn: type: integer description: Turn index, unique across the call. x-parser-schema-id: role: type: string enum: - user - assistant description: Who is speaking. x-parser-schema-id: start_time: type: number description: Seconds since the start of the session. x-parser-schema-id: x-parser-schema-id: AgentTurnStartedEvent title: Turn Started description: > Sent when the user starts speaking or the agent starts responding. `turn` comes from a single counter shared by both roles, starting at 1 and strictly increasing over the call, so `turn` alone identifies a turn. example: |- { "type": "turn_started", "turn": 3, "role": "user", "start_time": 12.48 } bindings: [] extensions: - id: x-parser-unique-object-id value: agentTurnStartedEvent - &ref_13 id: agentTurnOutputTextDeltaEvent payload: - name: Turn Text Delta description: > Sent as the agent speaks, carrying the text spoken since the previous delta, typically one word at a time. Deltas include separator spaces, so build the running text by appending `text` verbatim. The user's speech is not streamed incrementally. It arrives as finalized text in `turn_ended`. type: object properties: - name: type type: string description: Event type identifier. enumValues: - turn_output_text_delta required: true - name: turn type: integer description: Matches the `turn` of the turn the text belongs to. required: true - name: role type: string description: Always `assistant`. enumValues: - assistant required: true - name: text type: string description: >- The exact substring to append. Separator spaces are included, so build the running text with `buffer[turn] += text`. required: true headers: [] jsonPayloadSchema: type: object required: - type - turn - role - text properties: type: type: string enum: - turn_output_text_delta description: Event type identifier. x-parser-schema-id: turn: type: integer description: Matches the `turn` of the turn the text belongs to. x-parser-schema-id: role: type: string enum: - assistant description: Always `assistant`. x-parser-schema-id: text: type: string description: >- The exact substring to append. Separator spaces are included, so build the running text with `buffer[turn] += text`. x-parser-schema-id: x-parser-schema-id: AgentTurnOutputTextDeltaEvent title: Turn Text Delta description: > Sent as the agent speaks, carrying the text spoken since the previous delta, typically one word at a time. Deltas include separator spaces, so build the running text by appending `text` verbatim. The user's speech is not streamed incrementally. It arrives as finalized text in `turn_ended`. example: |- { "type": "turn_output_text_delta", "turn": 4, "role": "assistant", "text": " world" } bindings: [] extensions: - id: x-parser-unique-object-id value: agentTurnOutputTextDeltaEvent - &ref_14 id: agentTurnEndedEvent payload: - name: Turn Ended description: > Sent when a turn finishes, with the complete final text for the turn. This is the version to store and display. The events for a single turn always arrive in order: `turn_started`, then any `turn_output_text_delta` events, then `turn_ended`. If the agent hangs up mid-turn, the connection closes without a final `turn_ended`; treat the close as ending any open turn. type: object properties: - name: type type: string description: Event type identifier. enumValues: - turn_ended required: true - name: turn type: integer description: Matches the `turn` of the corresponding `turn_started` event. required: true - name: role type: string description: Who spoke. enumValues: - user - assistant required: true - name: text type: string description: >- The finalized text of the turn. For a user turn, the transcribed speech. For an assistant turn, the text the agent actually spoke. required: true - name: interrupted type: boolean description: >- For assistant turns, `true` when the user interrupted the turn. For user turns, `true` only when the call ended mid-turn. required: true - name: start_time type: number description: Seconds since the start of the session. required: true - name: end_time type: number description: Seconds since the start of the session. required: true - name: tool_calls type: array description: >- Tool calls made during the turn. Each entry has `name`, `arguments`, and optionally `result` and `id`. required: true properties: - name: name type: string description: Name of the tool. required: true - name: arguments type: object description: Arguments the model supplied. required: true - name: result type: string description: The tool's result, when one was recorded. required: false - name: id type: string description: Identifier of the invocation. required: false headers: [] jsonPayloadSchema: type: object required: - type - turn - role - text - interrupted - start_time - end_time - tool_calls properties: type: type: string enum: - turn_ended description: Event type identifier. x-parser-schema-id: turn: type: integer description: Matches the `turn` of the corresponding `turn_started` event. x-parser-schema-id: role: type: string enum: - user - assistant description: Who spoke. x-parser-schema-id: text: type: string description: >- The finalized text of the turn. For a user turn, the transcribed speech. For an assistant turn, the text the agent actually spoke. x-parser-schema-id: interrupted: type: boolean description: >- For assistant turns, `true` when the user interrupted the turn. For user turns, `true` only when the call ended mid-turn. x-parser-schema-id: start_time: type: number description: Seconds since the start of the session. x-parser-schema-id: end_time: type: number description: Seconds since the start of the session. x-parser-schema-id: tool_calls: type: array description: >- Tool calls made during the turn. Each entry has `name`, `arguments`, and optionally `result` and `id`. items: type: object required: - name - arguments properties: name: type: string description: Name of the tool. x-parser-schema-id: arguments: type: object description: Arguments the model supplied. x-parser-schema-id: result: type: string description: The tool's result, when one was recorded. x-parser-schema-id: id: type: string description: Identifier of the invocation. x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: x-parser-schema-id: AgentTurnEndedEvent title: Turn Ended description: > Sent when a turn finishes, with the complete final text for the turn. This is the version to store and display. The events for a single turn always arrive in order: `turn_started`, then any `turn_output_text_delta` events, then `turn_ended`. If the agent hangs up mid-turn, the connection closes without a final `turn_ended`; treat the close as ending any open turn. example: |- { "type": "turn_ended", "turn": 3, "role": "user", "text": "I'd like to check my order status.", "interrupted": false, "start_time": 12.48, "end_time": 15.02, "tool_calls": [] } bindings: [] extensions: - id: x-parser-unique-object-id value: agentTurnEndedEvent - &ref_15 id: agentErrorEvent payload: - name: Error description: > Reports a problem with the session or an event you sent. When `fatal` is `false`, the offending event was dropped and the stream stays open. When `fatal` is `true`, the server closes the connection: code 1008 for client and protocol errors, 1011 for agent pipeline failures. type: object properties: - name: type type: string description: Event type identifier. enumValues: - error required: true - name: code type: string description: >- `invalid_event` for a rejected client event, `agent_failed` for an agent pipeline failure. enumValues: - invalid_event - agent_failed required: true - name: message type: string description: Human-readable explanation. required: true - name: fatal type: boolean description: Whether the server closes the connection after this error. required: true headers: [] jsonPayloadSchema: type: object required: - type - code - message - fatal properties: type: type: string enum: - error description: Event type identifier. x-parser-schema-id: code: type: string enum: - invalid_event - agent_failed description: >- `invalid_event` for a rejected client event, `agent_failed` for an agent pipeline failure. x-parser-schema-id: message: type: string description: Human-readable explanation. x-parser-schema-id: fatal: type: boolean description: Whether the server closes the connection after this error. x-parser-schema-id: x-parser-schema-id: AgentErrorEvent title: Error description: > Reports a problem with the session or an event you sent. When `fatal` is `false`, the offending event was dropped and the stream stays open. When `fatal` is `true`, the server closes the connection: code 1008 for client and protocol errors, 1011 for agent pipeline failures. example: |- { "type": "error", "code": "invalid_event", "message": "dtmf_input must be one of 0-9, * or", "fatal": false } bindings: [] extensions: - id: x-parser-unique-object-id value: agentErrorEvent bindings: [] extensions: *ref_0 sendOperations: - *ref_1 receiveOperations: - *ref_2 sendMessages: - *ref_3 - *ref_4 - *ref_5 - *ref_6 receiveMessages: - *ref_7 - *ref_8 - *ref_9 - *ref_10 - *ref_11 - *ref_12 - *ref_13 - *ref_14 - *ref_15 extensions: - id: x-parser-unique-object-id value: /v1/agents/websocket/{agent_id} securitySchemes: - id: apiKey name: X-API-Key type: httpApiKey description: Use an API key when you're calling from a trusted server. in: header extensions: [] - id: accessTokenQuery name: access_token type: httpApiKey description: >- Use a short-lived access token when calling from a browser or client app. [Learn more here](/get-started/authenticate-your-client-applications). in: query extensions: [] ````