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

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.co/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};