Telefonia: SIP, LiveKit e G.711
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della guida xAI SIP Phone Calls, della pagina Speech to Speech e dell’esempio di cookbook Phone Voice Agent. xAI può rispondere alle chiamate sul tuo numero direttamente (SIP diretto, webhook firmato, trasferimento, riaggancio, tasti DTMF), oltre a un ponte attraverso il tuo server. Fonti: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Collega l’API Voice Agent alla rete telefonica
L’API Voice Agent può gestire chiamate telefoniche: i tuoi clienti compongono un numero ordinario e parlano con il tuo agente Grok. Tre percorsi ti portano a questo risultato, dal più integrato al più flessibile.
Percorso 1: SIP diretto con xAI
In questa modalità, xAI risponde alla chiamata direttamente. La chiamata arriva sull’infrastruttura SIP di xAI, che ti notifica tramite webhook; la tua app si unisce alla chiamata via WebSocket e pilota l’agente.
- Registra il numero. Dichiarare un numero “Direct SIP” con xAI, insieme all’indirizzo del webhook che riceverà le chiamate in arrivo. Per un numero di tua proprietà, usa
origin: "byo_trunk": xAI non fornisce numeri tramite l’API. La risposta contiene un segreto di firma, restituito una sola volta, quindi salvalo nel tuo vault dei segreti. - Instrada il tuo operatore. Configura il tuo operatore o il PBX per inviare le chiamate a
sip:{number}@sip.voice.x.ai. xAI accetta la segnalazione SIP su TLS sulla porta 5061, oppure su TCP o UDP sulla porta 5060; preferisci;transport=tlsquando il tuo operatore lo supporta. - Ricevi il webhook. Per ogni chiamata, xAI invia un webhook firmato
realtime.call.incoming. Verifica gli headerwebhook-id,webhook-timestampewebhook-signaturecon il segreto di firma, quindi leggidata.call_id. - Unisciti alla chiamata. Apri
wss://api.x.ai/v1/realtime?call_id={call_id}con la tua chiave API (i token effimeri non sono accettati per una sessione SIP), inviasession.update, quindiresponse.createquando l’agente deve parlare.
import json
import os
import websockets
async def join_call(call_id):
async with websockets.connect(
f"wss://api.x.ai/v1/realtime?call_id={call_id}",
additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "rex",
"instructions": "You are the customer service agent. Answer in English, briefly.",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({"type": "response.create"})) # the agent greets the caller
async for message in ws:
event = json.loads(message)
# same handling as for a regular WebSocket session
Una volta connesso, la sessione si comporta come qualsiasi altra sessione vocale: xAI inoltra l’audio del chiamante e riproduce quello dell’agente, senza che il tuo server trasporti alcun suono.
Trasferimento o riaggancio
Due chiamate REST controllano la linea. POST /v1/realtime/calls/{call_id}/refer, con un target_uri in formato tel: o sip:, trasferisce il chiamante; la richiesta attende l’esito del trasferimento. Un 200 con corpo vuoto significa che la destinazione ha risposto; un 502 riporta il codice di rifiuto SIP e un 504 segnala un timeout. Dopo un fallimento, la sessione rimane aperta e l’agente può continuare a parlare: spetta a te leggere la risposta e, se necessario, far spiegare l’intoppo all’agente. POST /v1/realtime/calls/{call_id}/hangup termina la chiamata.
Input da tastiera (DTMF)
In una sessione SIP, i tasti premuti dal chiamante vengono memorizzati nella buffer e poi passati al modello come testo non appena il chiamante preme #, dopo 2,5 secondi senza nuovi tasti, o non appena inizia a parlare. Il tuo client riceve un evento input_audio_buffer.dtmf_event_received per ogni tasto, così puoi tenerne traccia. Per permettere all’agente di premere i tasti da solo, ad esempio per navigare nel menu telefonico di un altro servizio, aggiungi {"type": "function", "name": "send_dtmf"} ai suoi strumenti, senza parametri: l’API fornisce lo schema e invia i toni, e tu non devi rispondere a queste chiamate di funzione. Questi eventi esistono solo in una sessione SIP.
Operatori documentati
La guida xAI illustra la configurazione per quattro operatori (Twilio, con Elastic SIP Trunking e trasferimento di chiamata abilitato sul trunk se trasferisci le chiamate; Bandwidth; Telnyx; e Plivo) e per qualsiasi operatore, contact center o PBX in grado di aprire una rotta SIP verso l’indirizzo del tuo numero. Per quanto riguarda il codec, l’esempio Telnyx chiede di abilitare almeno G.711 μ-law, G.711 A-law o G.722.
Percorso 2: un ponte attraverso il tuo server
Se vuoi mantenere il controllo del flusso audio, il tuo server riceve l’audio della chiamata e lo inoltra a una sessione WebSocket regolare. Questa è l’architettura dell’esempio Phone Voice Agent del cookbook xAI: Twilio trasmette l’audio della chiamata in μ-law tramite i suoi Media Streams, e il server lo passa all’API così com’è, senza conversione, in entrambe le direzioni.
# Phone call → carrier → your server → xAI WebSocket
import base64
import json
import os
import websockets
async def relay_call(call_audio_stream):
ws = await websockets.connect(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)
# G.711 μ-law at 8000 Hz, the North American phone network format
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "rex",
"instructions": "Customer service agent.",
"turn_detection": {"type": "server_vad"},
"audio": {
"input": {"format": {"type": "audio/pcmu", "rate": 8000}},
"output": {"format": {"type": "audio/pcmu", "rate": 8000}},
},
},
}))
async for chunk in call_audio_stream:
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(chunk).decode(),
}))
L’API accetta nativamente entrambe le varianti G.711, evitando qualsiasi transcodifica: audio/pcmu (μ-law, lo standard nordamericano e giapponese) e audio/pcma (A-law, lo standard in Europa e nella maggior parte degli altri paesi), entrambi a 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
I tasti DTMF e le chiamate REST di trasferimento e riaggancio appartengono al percorso SIP diretto: in un ponte, se ne occupa il tuo operatore.
Percorso 3: un framework real-time
La documentazione xAI elenca due integrazioni pronte all’uso: LiveKit Agents e Pipecat. Gestiscono il trasporto in tempo reale (WebRTC, stanze, instradamento delle chiamate) e collegano l’agente vocale Grok nel punto giusto, risparmiando a un team che non vuole costruire un livello di telefonia da zero il compito di farlo.
In produzione
Gestisci i silenzi. Al telefono, un chiamante che tace lascia una linea morta. turn_detection.idle_timeout_ms fa sì che l’agente verifichi la presenza del chiamante dopo un silenzio della durata che scegli (lezione 6).
Riprendi una conversazione in una nuova chiamata. La ripresa della sessione funziona anche via SIP: abilita resumption.enabled alla prima chiamata e mantieni il suo call_id. Quando il cliente richiama, apri wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} e invia di nuovo lo stesso session.update. La cronologia scade dopo 30 minuti di inattività.
Segui le regole. Informa i chiamanti che stanno parlando con un’IA e, se registri le chiamate, dillo all’inizio. Per i dati sanitari, xAI indica che un BAA (Business Associate Agreement) può essere firmato dopo un questionario.
Misura la tua latenza. Il ritardo percepito dai chiamanti somma la rete telefonica, il tuo ponte se ne hai uno, e la generazione della risposta. Misuralo end-to-end su chiamate reali e mantieni veloci le funzioni che l’agente chiama durante la conversazione.
Punti chiave
- Con il SIP diretto, xAI risponde al tuo numero, ti notifica con un webhook firmato
realtime.call.incominge ti unisci alla chiamata tramitewss://api.x.ai/v1/realtime?call_id=… refertrasferisce la chiamata (l’esito torna nella risposta HTTP) ehangupla termina- I tasti DTMF raggiungono il modello e vengono registrati tramite
input_audio_buffer.dtmf_event_received; lo strumentosend_dtmfpermette all’agente di premere i tasti - In un ponte attraverso il tuo server, il G.711 nativo (
audio/pcmu,audio/pcma) evita la transcodifica - LiveKit Agents e Pipecat sono le integrazioni elencate da xAI