Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech/sip (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Speech to Speech API34# SIP Phone Calls56SIP lets you route PSTN, contact-center, or PBX calls into a Speech to Speech API session.78### 1. Register the phone number910Create a Direct SIP phone number and include the webhook details that should receive incoming-call events. Use `origin: "byo_trunk"` for a customer-owned number. Provisioning xAI phone numbers via API is not supported. xAI returns the webhook signing secret in the response.1112Choose one SIP authentication method.1314The response includes a signing secret after you register the phone number. Store it securely; xAI returns it only once.1516Configure your carrier or PBX to route calls to:17181920If you provide `allowed_addresses`, make sure the list contains your provider's SIP signaling CIDR ranges. If you provide SIP digest credentials, configure your carrier with the same username and password; xAI never returns the password after creation.2122### 2. Handle the incoming-call webhook2324When a caller dials the number, xAI sends a signed `realtime.call.incoming` webhook to the webhook URL. Verify the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers using the signing secret returned after you register the phone number, then read `data.call_id` from the payload.2526The webhook has this shape:2728```json29{30 "object": "event",31 "id": "evt_123",32 "type": "realtime.call.incoming",33 "created_at": 1750000000,34 "data": {35 "call_id": "00000000-0000-0000-0000-000000000000",36 "sip_headers": [37 { "name": "From", "value": "+14155550100" },38 { "name": "To", "value": "+18005550199" }39 ],40 "metadata": {}41 }42}43```4445### 3. Join the call over WebSocket4647Open `wss://api.x.ai/v1/realtime?call_id={call_id}` with your xAI API key. Then send `session.update` to configure the voice agent for this call, followed by `response.create` when the agent should begin speaking.4849After connecting, the WebSocket behaves like any other Speech to Speech API session. The SIP caller's audio is bridged into the session, and assistant audio is played back to the caller.5051```python customLanguage="pythonWithoutSDK"52import asyncio53import json54import os55import websockets5657async def handle_sip_call(call_id: str):58 async with websockets.connect(59 f"wss://api.x.ai/v1/realtime?call_id={call_id}",60 additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},61 ) as ws:62 await ws.send(json.dumps({63 "type": "session.update",64 "session": {65 "voice": "eve",66 "instructions": "You are a helpful phone support agent.",67 "turn_detection": {"type": "server_vad"},68 },69 }))70 await ws.send(json.dumps({"type": "response.create"}))7172 async for msg in ws:73 event = json.loads(msg)74 print(event["type"])7576asyncio.run(handle_sip_call("00000000-0000-0000-0000-000000000000"))77```7879```javascript customLanguage="javascriptWithoutSDK"80import WebSocket from "ws";8182const callId = "00000000-0000-0000-0000-000000000000";83const ws = new WebSocket(`wss://api.x.ai/v1/realtime?call_id=${callId}`, {84 headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },85});8687ws.on("open", () => {88 ws.send(JSON.stringify({89 type: "session.update",90 session: {91 voice: "eve",92 instructions: "You are a helpful phone support agent.",93 turn_detection: { type: "server_vad" },94 },95 }));96 ws.send(JSON.stringify({ type: "response.create" }));97});9899ws.on("message", data => {100 const event = JSON.parse(data.toString());101 console.log(event.type);102});103```104105## Call control106107Use `refer` to transfer the caller to another PSTN or SIP destination. The request blocks until the transfer resolves; the HTTP status reports whether the destination answered. See [FAQ](#faq) for status codes, failed-transfer session behavior, and conversation resumption.108109```bash customLanguage="bash"110curl -X POST "https://api.x.ai/v1/realtime/calls/$CALL_ID/refer" \111 -H "Authorization: Bearer $XAI_API_KEY" \112 -H "Content-Type: application/json" \113 -d '{"target_uri": "sip:agent@example.com"}'114```115116Use `hangup` when your application should end the call:117118```bash customLanguage="bash"119curl -X POST "https://api.x.ai/v1/realtime/calls/$CALL_ID/hangup" \120 -H "Authorization: Bearer $XAI_API_KEY"121```122123## DTMF phone keypresses124125When using the Speech to Speech API over SIP, phone keypresses (DTMF tones) are automatically buffered and flushed to the model as text input. The client receives `input_audio_buffer.dtmf_event_received` events as an audit trail of each keypress.126127### Flush triggers128129Buffered digits are submitted to the model when any of the following occurs:130131* The user presses `#` (submit key)132* 2.5 seconds of idle time after the last keypress133* The user begins speaking (preempts the digit buffer)134135### Audit event136137Each keypress is reported to the client WebSocket:138139```json customLanguage="json"140{141 "type": "input_audio_buffer.dtmf_event_received",142 "event": "5",143 "received_at": 1730000000144}145```146147> [!NOTE]148>149> DTMF is only available on SIP sessions — it is not emitted on direct WebSocket connections.150151## Telephony providers152153In every provider, the destination is the xAI SIP URI for your registered number:154155156157Replace `{number}` with your Direct SIP phone number. If you configured `allowed_addresses` when registering the number, include your provider's SIP signaling CIDR ranges.158159### Twilio1601611. In the Twilio Console, go to **Voice** → **Elastic SIP Trunking** and create a trunk.1622. Open the trunk's **Origination** settings and add this origination URI: `sip:{number}@sip.voice.x.ai;transport=tls`.1633. Assign a Twilio phone number to the trunk, or purchase a new number and attach it.1644. If your application transfers calls mid-session, enable call transfer on the trunk.165166### Telnyx1671681. In the Telnyx Portal, go to **Voice Suite** → **SIP Trunking** and create an FQDN SIP Connection.1692. In **Authentication and Routing**, add `sip.voice.x.ai` as the primary FQDN on port `5060` with record type `A`.1703. In **Inbound settings**, set the destination number format to **E.164**.1714. Enable at least one supported codec: G.711 μ-law, G.711 A-law, or G.722.1725. Assign a phone number to the SIP Connection.173174### Plivo1751761. In the Plivo Console, go to **SIP Trunking** and create a SIP trunk.1772. Choose **Inbound**, then create a new URI with FQDN `sip.voice.x.ai`.1783. Link an existing phone number to the trunk, or buy a new number and attach it.179180### Bring Your Own SIP Provider1811821. In your carrier, contact center, or PBX, create an outbound route or SIP trunk.1832. Set the destination to `sip:{number}@sip.voice.x.ai;transport=tls`.184185## FAQ186187These answers cover the Speech to Speech API SIP path: transfer success and failure with reason codes, what happens when a transfer fails, and how to continue a conversation on a later SIP call.188189### How do I get transfer success or failure with a reason code?190191There is no separate WebSocket transfer event. `POST /v1/realtime/calls/{call_id}/refer` returns the outcome synchronously.192193A `200` with an empty JSON body (`{}`) means the transfer completed: the REFER succeeded and the destination answered, not merely that the REFER was accepted or that the destination started ringing.194195Downstream SIP rejections return `502` with the carrier's SIP status in the body:196197```json customLanguage="json"198{199 "error": "transfer rejected by downstream: SIP 403 Forbidden"200}201```202203Other statuses are also possible:204205| Status | Meaning |206| --- | --- |207| `400` | `target_uri` is not a `tel:` or `sip:` URI |208| `404` | No SIP participant on this call |209| `502` | Transfer rejected by downstream; the body includes the SIP code and reason when available |210| `504` | Transfer timed out |211| `500` | Internal error |212213### Does the session stay usable if a transfer fails?214215Yes. While the REFER is pending, the WebSocket stays open and the caller hears dialtone. After a `502`, that same realtime session stays connected. The failed transfer is a no-op on the xAI side: the caller remains on the call, and the agent can keep talking.216217This path does not automatically start a new session or inject a failure-reason prompt. If the agent should tell the caller why the transfer failed, read the `refer` HTTP response and continue on this session, or resume later as below.218219### Can I reattach a resumed conversation to a new SIP call?220221[Session resumption](/developers/model-capabilities/audio/speech-to-speech#session-resumption) caches transcripts and tool results so a later SIP call can continue the same conversation. You must opt in on both the original session and the resuming session. History expires after 30 minutes of inactivity.2222231. On the first call, open `wss://api.x.ai/v1/realtime?call_id={call_id}` and immediately send `session.update` with `resumption.enabled` set to `true`. Save that `call_id`.2242. On the later call, open `wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={saved_call_id}` and send the same `session.update` again. That restores the prior turns and keeps saving for future reconnects.2253. There is no dedicated resumption-complete event. Restore happens as soon as that `session.update` is processed; replayed turns arrive as `conversation.item.created` events.226227```json customLanguage="json"228{229 "type": "session.update",230 "session": {231 "resumption": { "enabled": true }232 }233}234```235236### Can I transfer to a Twilio SIP Domain?237238Yes. A `sip:` `target_uri` is forwarded as the SIP `Refer-To` value, including URI parameters used to route into a Twilio Programmable Voice SIP Domain or conference. Custom SIP headers are not sent on the REFER.239