Telefonie: SIP, LiveKit a G.711
Na této stránce
Aktualizováno 3. listopadu 2026 na základě příručky xAI SIP Phone Calls, stránky Speech to Speech a ukázkového projektu Phone Voice Agent. xAI může přijímat hovory přímo na vaše číslo (přímý SIP, podepsaný webhook, přepojení, zavěšení, klávesy DTMF) vedle mostu přes váš vlastní server. Zdroje: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Propojení Voice Agent API s telefonní sítí
Voice Agent API umí přijímat telefonní hovory: vaši zákazníci vytočí běžné číslo a hovoří s vaším agentem Grok. Existují tři cesty, jak toho dosáhnout, od nejvíce integrované po nejflexibilnější.
Cesta 1: Přímý SIP s xAI
V tomto režimu hovor přijímá přímo xAI. Hovor dorazí na SIP infrastrukturu xAI, která vás upozorní prostřednictvím webhooku; vaše aplikace se poté připojí k hovoru přes WebSocket a řídí agenta.
- Registrace čísla. Deklarujte u xAI číslo typu „Direct SIP“ spolu s adresou webhooku, která bude přijímat příchozí hovory. Pro číslo, které již vlastníte, použijte
origin: "byo_trunk": xAI neposkytuje telefonní čísla prostřednictvím API. Odpověď obsahuje podpisový tajný klíč (signing secret), který je vrácen pouze jednou, takže si jej uložte do svého trezoru s tajnými údaji. - Směrování operátora. Nakonfigurujte svého operátora nebo ústřednu (PBX) tak, aby směrovaly hovory na
sip:{number}@sip.voice.x.ai. xAI přijímá SIP signalizaci přes TLS na portu 5061 nebo přes TCP či UDP na portu 5060; pokud to váš operátor podporuje, upřednostněte;transport=tls. - Přijetí webhooku. Pro každý hovor odešle xAI podepsaný webhook
realtime.call.incoming. Ověřte hlavičkywebhook-id,webhook-timestampawebhook-signaturepomocí podpisového tajného klíče a poté si přečtětedata.call_id. - Připojení k hovoru. Otevřete spojení
wss://api.x.ai/v1/realtime?call_id={call_id}pomocí svého API klíče (pro relaci SIP nejsou přijímány krátkodobé tokeny), odešletesession.updatea následněresponse.create, když má agent promluvit.
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
Jakmile je spojení navázáno, relace se chová jako jakákoli jiná hlasová relace: xAI přenáší audio volajícího a přehývá mu odpovědi agenta, aniž by váš server musel přenášet jakýkoli zvuk.
Přepojení nebo zavěšení
Linku ovládají dva požadavky REST. POST /v1/realtime/calls/{call_id}/refer s parametrem target_uri ve formátu tel: nebo sip: přepojí volajícího; požadavek čeká na výsledek přepojení. Kód 200 s prázdným tělem znamená, že cíl hovor přijal; kód 502 nese kód odmítnutí SIP a kód 504 signalizuje vypršení časového limitu. Po selhání zůstává relace otevřená a agent může pokračovat v hovoru: je na vás, abyste přečetli odpověď a v případě potřeby nechali agenta vysvětlit problém. POST /v1/realtime/calls/{call_id}/hangup hovor ukončí.
Vstup z klávesnice (DTMF)
V relaci SIP jsou klávesy, které volající stiskne, bufferovány a předány modelu jako text, jakmile volající stiskne #, po 2,5 sekundách bez stisku nové klávesy, nebo jakmile začne mluvit. Váš klient obdrží jednu událost input_audio_buffer.dtmf_event_received na každou klávesu, takže si můžete vést záznam. Pokud chcete, aby agent sám mačkal klávesy, například pro navigaci v telefonním menu jiné služby, přidejte do jeho nástrojů {"type": "function", "name": "send_dtmf"} bez parametrů: API poskytuje schéma a odešle tóny, vy však na tyto volání funkcí nesmíte odpovídat. Tyto události existují pouze v relaci SIP.
Zdokumentovaní operátoři
Příručka xAI podrobně popisuje nastavení pro čtyři operátory (Twilio s povoleným Elastic SIP Trunkingem a přepojením hovorů na trunku, pokud hovory přepojujete; Bandwidth; Telnyx; a Plivo) a pro jakéhokoli operátora, kontaktní centrum nebo ústřednu (PBX), která dokáže otevřít SIP trasu na adresu vašeho čísla. Co se týče kodeků, příklad s Telnyxem vyžaduje povolení alespoň jednoho z formátů: G.711 μ-law, G.711 A-law nebo G.722.
Cesta 2: Most přes váš vlastní server
Pokud si chcete ponechat kontrolu nad zvukovým streamem, váš server přijme audio z hovoru a předá jej do běžné relace WebSocket. To je architektura ukázkového projektu Phone Voice Agent od xAI: Twilio streamuje audio hovoru ve formátu μ-law prostřednictvím svých Media Streams a server jej předává API tak, jak je, bez konverze, v obou směrech.
# 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(),
}))
API nativně přijímá obě varianty G.711, což eliminuje potřebu překódování: audio/pcmu (μ-law, standard pro Severní Ameriku a Japonsko) a audio/pcma (A-law, standard pro Evropu a většinu ostatních zemí), oba při 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
Klávesy DTMF a volání REST pro přepojení a zavěšení patří k cestě přímého SIP: v případě mostu je zpracovává váš operátor.
Cesta 3: Framework pro práci v reálném čase
Dokumentace xAI uvádí dvě připravená integrovaná řešení: LiveKit Agents a Pipecat. Ta řeší transport v reálném čase (WebRTC, místnosti, směrování hovorů) a zapojují hlasového agenta Grok na správné místo, což šetří týmy, které nechtějí budovat telefonní vrstvu od nuly.
V produkci
Zpracovávejte ticho. Při telefonátu zanechá mlčící volající mrtvou linku. Parametr turn_detection.idle_timeout_ms zajistí, že se agent ozve volajícímu po vámi zvolené době ticha (lekce 6).
Navázání na konverzaci při novém hovoru. Obnovení relace funguje i přes SIP: povolte resumption.enabled při prvním hovoru a uchovejte jeho call_id. Když zákazník zavolá znovu, otevřete wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} a znovu odešlete stejné session.update. Historie vyprší po 30 minutách nečinnosti.
Dodržujte pravidla. Informujte volající, že hovoří s AI, a pokud hovory nahráváte, sdělte jim to na začátku. U zdravotních údajů xAI uvádí, že po vyplnění dotazníku lze podepsat dohodu o zpracování osobních údajů (BAA – Business Associate Agreement).
Měřte latenci. Zpoždění, které volající vnímá, je součtem latence telefonní sítě, vašeho mostu (pokud jej máte) a generování odpovědi. Měřte ji end-to-end na skutečných hovorech a udržujte funkce, které agent během konverzace volá, co nejrychlejší.
Klíčové poznatky
- Při přímém SIP odpovídá xAI na vaše číslo, upozorní vás podepsaným webhookem
realtime.call.incominga vy se připojíte k hovoru přeswss://api.x.ai/v1/realtime?call_id=… referpřepojí hovor (výsledek se vrátí v HTTP odpovědi) ahangupjej ukončí- Klávesy DTMF dorazí k modelu a jsou logovány prostřednictvím
input_audio_buffer.dtmf_event_received; nástrojsend_dtmfumožňuje agentovi mačkat klávesy - V mostu přes váš server eliminuje nativní G.711 (
audio/pcmu,audio/pcma) potřebu překódování - LiveKit Agents a Pipecat jsou integrace, které xAI uvádí