conversations | Phonic

Real-time speech-to-speech (STS) communication WebSocket API for Phonic’s AI voice conversation platform.

All connections require authentication using one of the following methods:

Option 1: API Key (Server-side)

Use your Phonic API key in the Authorization header: Authorization: Bearer PHONIC_API_KEY

Option 2: Session Token (Client-side)

For client-side applications where you don’t want to expose your API key, first create a short-lived session token via the REST API: POST /v1/auth/session_token

Then connect to the WebSocket with the session token as a query parameter: wss://api.phonic.ai/v1/sts/ws?session_token=ph_session_abc123...

Real-time speech-to-speech (STS) communication WebSocket API for Phonic's AI voice conversation platform. All connections require authentication using one of the following methods: #### Option 1: API Key (Server-side) Use your Phonic API key in the Authorization header: `Authorization: Bearer PHONIC_API_KEY` #### Option 2: Session Token (Client-side) For client-side applications where you don't want to expose your API key, first create a short-lived session token via the REST API: `POST /v1/auth/session_token` Then connect to the WebSocket with the session token as a query parameter: `wss://api.phonic.ai/v1/sts/ws?session_token=ph_session_abc123...`

Handshake

WSS

wss://api.phonic.ai/v1/sts/ws

Authentication

AuthorizationBearer

Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).

Headers

AuthorizationstringRequired

API key for authentication. Format: “Bearer PHONIC_API_KEY”

Send

configobjectRequired

Initialize conversation with configuration parameters

audio_chunkobjectRequired

Send audio chunk for real-time voice input

update_system_promptobjectRequiredDeprecated

Update system prompt mid-conversation. This message is deprecated. Using add_system_message is recommended instead.

add_system_messageobjectRequired

Add system message mid-conversation

update_tools_subsetobjectRequired

Update the subset of tools available to the assistant mid-conversation

set_external_idobjectRequired

Set external ID for conversation tracking

tool_call_outputobjectRequired

Respond to WebSocket tool call with output

unmuteobjectRequired

Only for push to talk. Interrupts the assistant and turns on listening

muteobjectRequired

Only for push to talk. Turns off listening and starts assistant reply

generate_replyobjectRequired

Trigger the assistant to generate a reply, optionally with a system message

sayobjectRequired

Trigger the assistant to say some text, optionally can be configured to make the turn uninterruptible

resetobjectRequired

Soft-reset the conversation mid-stream, clearing the agent’s conversation memory and allowing for a new system prompt, tools, etc.

Receive

ready_to_start_conversationobjectRequired

Server indicates readiness to start conversation

conversation_createdobjectRequired

Conversation has been created in database

input_textobjectRequired

Transcribed user speech text

input_cancelledobjectRequired

User input was cancelled (no speech detected)

audio_chunk objectRequired

AI-generated audio chunk with text

user_started_speakingobjectRequired

User started speaking

user_finished_speakingobjectRequired

User finished speaking

assistant_started_speakingobjectRequired

Assistant started speaking

assistant_finished_speakingobjectRequired

Assistant finished speaking (Not sent if interrupted by user_started_speaking)

dtmfobjectRequired

DTMF tone for phone calls

tool_callobjectRequired

WebSocket tool call requiring client-side execution

tool_call_output_processedobjectRequired

Tool call has been processed and completed

tool_call_interruptedobjectRequired

Tool call was interrupted before completion

assistant_chose_not_to_respondobjectRequired

AI chose not to respond to user input

assistant_ended_conversationobjectRequired

AI ended the conversation

errorobjectRequired

Error occurred during conversation

warningobjectRequired

Non-fatal warning about conversation configuration or state

URL	wss://api.phonic.ai/v1/sts/ws
Method	GET
Status	101 Switching Protocols

Option 1: API Key (Server-side)

Option 2: Session Token (Client-side)

HandshakeTry it

Authentication

Headers

Send

Receive

Option 1: API Key (Server-side)

Option 2: Session Token (Client-side)

HandshakeTry it

Authentication

Headers

Send

Receive

Handshake

Handshake