CONVERSATIONS

Live Conversation WebSocket (Preview)

The Live Conversation WebSocket provides real-time updates about an active conversation’s state. It is a server-to-client only connection — the client does not send any messages after connecting.

Endpoint

wss://api.phonic.ai/v1/conversations/{conversation_id}/live/ws
ParameterLocationDescription
conversation_idPathThe ID of the conversation to observe

Authentication

This endpoint supports the same authentication methods as the STS WebSocket:

  • API Key: Authorization: Bearer PHONIC_API_KEY header
  • Session Token: ?session_token=ph_session_... query parameter

Connection flow

  1. Connect to the WebSocket with valid credentials
  2. Receive an initial conversation-updated message with the current conversation state
  3. Continue receiving conversation-updated messages as the conversation progresses
  4. Receive a conversation-ended message when the conversation finishes

Server-to-client messages

conversation-updated

Sent whenever the conversation state changes. Contains the full conversation object.

The conversation object has the same shape as the Conversation returned by the REST API, with is_live always set to true.

1{
2  "type": "conversation-updated",
3  "conversation": {
4    "id": "conv_12cf6e88-c254-4d3e-a149-ddf1bdd2254c",
5    "agent": {
6      "id": "agent_12cf6e88-c254-4d3e-a149-a7f1bdd22783",
7      "name": "support-agent",
8      "is_deleted": false
9    },
10    "org_id": "org_01K1WB8NT3EJJ4ZRKJ6BQZPZPS",
11    "project_id": "proj_ad0334f1-2487-4155-9df3-abd8129b29ad",
12    "external_id": "call-123",
13    "origin": "inbound",
14    "generate_welcome_message": false,
15    "is_welcome_message_interruptible": true,
16    "welcome_message": "Hello! How can I help you today?",
17    "template_variables": {},
18    "input_format": "mulaw_8000",
19    "output_format": "mulaw_8000",
20    "background_noise_level": 0,
21    "background_noise": null,
22    "intelligence_level": "default",
23    "text": "Hello! How can I help you today?\nHi, I need help with booking an appointment.\nOf course! I'd be happy to help.",
24    "duration_ms": 12500,
25    "summary": null,
26    "boosted_keywords": [],
27    "pronunciation_dictionary": [{"word": "Phuket", "pronunciation": "Poo-ket"}],
28    "min_words_to_interrupt": 1,
29    "default_language": "en",
30    "additional_languages": [],
31    "multilingual_mode": "request",
32    "push_to_talk": false,
33    "no_input_poke_sec": 30,
34    "generate_no_input_poke_text": false,
35    "no_input_poke_text": "Are you still there?",
36    "no_input_end_conversation_sec": 180,
37    "storage_key": null,
38    "started_at": "2025-07-30T23:45:00.000Z",
39    "ended_at": null,
40    "task_results": null,
41    "timezone": "America/Los_Angeles",
42    "system_prompt": "You are a helpful support assistant.",
43    "is_test": false,
44    "is_live": true,
45    "call_provider": "twilio_inbound_user",
46    "from_phone_number": "+15551234567",
47    "to_phone_number": "+15559876543",
48    "twilio_call_sid": null,
49    "created_by": null,
50    "vad_min_silence_duration_ms": null,
51    "assistant_end_conversation_signal_at": null,
52    "retranscribed_text": null,
53    "end_reason": null,
54    "vad_info": { "events": [] },
55    "annotations": {},
56    "items": [
57      {
58        "id": "conv_12cf6e88-c254-4d3e-a149-ddf1bdd2254c-0",
59        "item_idx": 0,
60        "role": "assistant",
61        "text": "Hello! How can I help you today?",
62        "retranscribed_text": null,
63        "duration_ms": 1800,
64        "audio_speed": 1,
65        "voice": null,
66        "tool_call_ids": [],
67        "transcript_corrections": [],
68        "naturalness_report": null,
69        "hallucination_report": null,
70        "started_at": "2025-07-30T23:45:00.500Z",
71        "assistant_chose_not_to_respond": false,
72        "timings": {
73          "phonic_api_output_to_modal_input": 120,
74          "model_generation_time": 450,
75          "phonic_api_output_to_first_audio_chunk": 570
76        }
77      },
78      {
79        "id": "conv_12cf6e88-c254-4d3e-a149-ddf1bdd2254c-1",
80        "item_idx": 1,
81        "role": "user",
82        "text": "Hi, I need help with booking an appointment.",
83        "retranscribed_text": null,
84        "duration_ms": 2500,
85        "audio_speed": null,
86        "voice": null,
87        "tool_call_ids": [],
88        "transcript_corrections": [],
89        "naturalness_report": null,
90        "hallucination_report": null,
91        "started_at": "2025-07-30T23:45:03.000Z",
92        "assistant_chose_not_to_respond": false
93      },
94      {
95        "id": "conv_12cf6e88-c254-4d3e-a149-ddf1bdd2254c-2",
96        "item_idx": 2,
97        "role": "assistant",
98        "text": "Of course! I'd be happy to help.",
99        "retranscribed_text": null,
100        "duration_ms": 2100,
101        "audio_speed": 1,
102        "voice": null,
103        "tool_call_ids": [],
104        "transcript_corrections": [],
105        "naturalness_report": null,
106        "hallucination_report": null,
107        "started_at": "2025-07-30T23:45:06.200Z",
108        "assistant_chose_not_to_respond": false,
109        "timings": {
110          "phonic_api_output_to_modal_input": 95,
111          "model_generation_time": 380,
112          "phonic_api_output_to_first_audio_chunk": 475
113        }
114      }
115    ]
116  }
117}

conversation-ended

Sent when the conversation has ended. The client should close the WebSocket after receiving this.

1{
2  "type": "conversation-ended"
3}

error

Sent on authentication failure, authorization failure, or other errors. The error may appear in error.message or the top-level message field.

1{
2  "type": "error",
3  "error": {
4    "message": "Invalid token"
5  }
6}
1{
2  "type": "error",
3  "message": "Unauthorized access to conversation"
4}

Close codes

CodeDescription
1000Normal closure (conversation ended)
1008Authentication or authorization error

Example usage

1const apiKey = "ph_...";
2const conversationId = "conv_12cf6e88-c254-4d3e-a149-ddf1bdd2254c";
3
4const ws = new WebSocket(
5  `wss://api.phonic.ai/v1/conversations/${conversationId}/live/ws`,
6  { headers: { Authorization: `Bearer ${apiKey}` } }
7);
8
9ws.onmessage = (event) => {
10  const data = JSON.parse(event.data);
11
12  switch (data.type) {
13    case "conversation-updated":
14      console.log(`Conversation updated. (${data.conversation.items.length} turns)`)
15      break;
16
17    case "conversation-ended":
18      console.log("Conversation ended");
19      ws.close();
20      break;
21
22    case "error":
23      console.error("Error:", data.error?.message ?? data.message);
24      ws.close();
25      break;
26  }
27};