Telefónia: SIP, LiveKit és G.711
Ezen az oldalon
Frissítve: 2026. november 3., az xAI SIP Phone Calls útmutatója, a Speech to Speech oldal és a Phone Voice Agent szakácskönyv-példa alapján. Az xAI képes közvetlenül fogadni a hívásokat a saját számodon (közvetlen SIP, aláírt webhook, átirányítás, hívásbontás, DTMF-gombok), valamint a saját szervereden keresztül futó híd használatával is. Források: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
A Voice Agent API összekapcsolása a telefonhálózattal
A Voice Agent API képes telefonhívásokat fogadni: az ügyfeleid egy szokványos számot tárcsáznak, és a Grok-ügynököddel beszélgetnek. Három út vezet ide, a leginkább integrálttól a legrugalmasabbig.
1. út: közvetlen SIP az xAI-jal
Ebben az üzemmódban maga az xAI fogadja a hívást. A hívás az xAI SIP-infrastruktúráján landol, amely webhookon keresztül értesít téged; az alkalmazásod WebSocketen keresztül csatlakozik a híváshoz, és vezérli az ügynököt.
- A szám regisztrálása. Regisztrálj egy „Direct SIP“ számot az xAI-nál, megadva azt a webhook-címet is, amely a bejövő hívásokat fogadja. Saját szám esetén használd az
origin: "byo_trunk"értéket: az xAI nem biztosít számokat az API-n keresztül. A válasz tartalmaz egy aláíró titkot, amelyet csak egyszer kapsz meg, ezért tárold el biztonságos titokkezelődben. - A szolgáltató útvonalának beállítása. Konfiguráld a szolgáltatódat vagy PBX-rendszeredet úgy, hogy a hívásokat a
sip:{number}@sip.voice.x.aicímre irányítsa. Az xAI a SIP-jelzéseket TLS-en keresztül fogadja az 5061-es porton, illetve TCP-n vagy UDP-n az 5060-as porton; ha a szolgáltatód támogatja, előnyben részesítsd a;transport=tlsparamétert. - A webhook fogadása. Minden hívás esetén az xAI egy aláírt
realtime.call.incomingwebhookot küld. Ellenőrizd awebhook-id,webhook-timestampéswebhook-signaturefejléceket az aláíró titokkal, majd olvasd ki adata.call_idértéket. - Csatlakozás a híváshoz. Nyisd meg a
wss://api.x.ai/v1/realtime?call_id={call_id}címet az API-kulcsoddal (átmeneti tokenek nem fogadhatók el SIP-munkamenethez), küldd el asession.updateüzenetet, majd aresponse.createparancsot, amikor az ügynöknek beszélnie kell.
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
Csatlakozás után a munkamenet úgy viselkedik, mint bármely más hangalapú munkamenet: az xAI továbbítja a hívó hangját, és lejátsza neki az ügynök válaszát anélkül, hogy a szerverednek hangadatokat kellene szállítania.
Átirányítás vagy hívásbontás
Két REST-hívás vezérli a vonalat. A POST /v1/realtime/calls/{call_id}/refer kérés egy target_uri paraméterrel (tel: vagy sip: formátumban) átirányítja a hívót; a kérés megvárja az átirányítás kimenetelét. Egy üres törzsű 200-as válasz azt jelenti, hogy a célállomás fogadta a hívást; egy 502-es hiba a SIP-elutasítási kódot tartalmazza, míg a 504 időtúllépést jelez. Hiba esetén a munkamenet nyitva marad, és az ügynök folytathatja a beszélgetést: rajtad múlik, hogy kiolvasd a választ, és szükség esetén megkérjed az ügynököt, magyarázza el a fennakadást. A POST /v1/realtime/calls/{call_id}/hangup kérés bontja a hívást.
Billentyűzet-bemenet (DTMF)
SIP-munkamenet esetén a hívó által megnyomott gombok pufferelve lesznek, majd szövegként kerülnek a modellhez, amint a hívó megnyomja a # gombot, 2,5 másodpercnyi új gombnyomás nélküli szünet után, vagy amint beszélni kezd. A kliensed minden egyes gombnyomásról egy input_audio_buffer.dtmf_event_received eseményt kap, így naplózhatod azokat. Ha azt szeretnéd, hogy maga az ügynök nyomjon meg gombokat (például egy másik szolgáltatás telefonmenüjének navigálásához), add hozzá a {"type": "function", "name": "send_dtmf"} eszközt a eszközeihez, paraméterek nélkül: az API biztosítja a sémát és elküldi a hangokat, neked pedig nem szabad kezelned ezeket a függvényhívásokat. Ezek az események kizárólag SIP-munkameneten léteznek.
Dokumentált szolgáltatók
Az xAI útmutató végigvezet négy szolgáltató (Twilio – ahol a trunkon engedélyezni kell az Elastic SIP Trunkingot és a hívásátirányítást, ha átirányítasz hívásokat; Bandwidth; Telnyx; és Plivo) beállításán, valamint bármely más szolgáltató, contact center vagy PBX esetén, amely képes SIP-útvonalat nyitni a számod címére. Kodek-oldalon a Telnyx-példa kéri legalább a G.711 μ-law, a G.711 A-law vagy a G.722 engedélyezését.
2. út: híd a saját szervereden keresztül
Ha szeretnéd megtartani az irányítást a hangfolyam felett, a szervered fogadja a hívás hangját, és továbbítja egy szokványos WebSocket-munkamenetbe. Ez az architektúrája az xAI szakácskönyvében található Phone Voice Agent példának is: a Twilio a hívás hangját μ-law formátumban streameli a Media Streams szolgáltatásán keresztül, a szerver pedig változtatás nélkül, mindkét irányban továbbítja azt az API felé.
# Telefonhívás → szolgáltató → saját szerver → 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 8000 Hz-en, az észak-amerikai telefonhálózat formátuma
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(),
}))
Az API natívan fogadja mindkét G.711-változatot, ami elkerüli az átkódolást: az audio/pcmu (μ-law, az észak-amerikai és japán szabvány) és az audio/pcma (A-law, az európai és a legtöbb egyéb ország szabványa), mindkettő 8000 Hz-en.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
A DTMF-gombok és a REST alapú átirányítási és hívásbontási kérések a közvetlen SIP-úthoz tartoznak: híd esetén ezeket a szolgáltatód kezeli.
3. út: valós idejű keretrendszer
Az xAI dokumentáció két kész integrációt sorol fel: a LiveKit Agentset és a Pipecatot. Ezek kezelik a valós idejű szállítást (WebRTC, szobák, hívásirányítás), és a megfelelő helyen csatlakoztatják a Grok hangügynököt, ami megspórolja egy olyan csapat számára a telefonréteg从零 történő felépítését, amely ezt nem szeretné megtenni.
Éles környezetben
Kezeld a csendet. Telefonon a elhallgató hívó halott vonalat eredményez. A turn_detection.idle_timeout_ms beállítás lehetővé teszi, hogy az ügynök egy általad meghatározott hosszúságú csend után jelentkezzen a hívónál (6. lecke).
Folytasd a beszélgetést egy új hívásban. A munkamenet-folytatás SIP-en keresztül is működik: engedélyezd a resumption.enabled opciót az első hívásnál, és tartsd meg a call_id értékét. Amikor az ügyfél visszahív, nyisd meg a wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} címet, és küldd el újra ugyanazt a session.update üzenetet. Az előzmények 30 perc inaktivitás után elévülnek.
Kövesd a szabályokat. Tájékoztasd a hívókat, hogy AI-val beszélnek, és ha rögzíted a hívásokat, azt a hívás elején közöld. Egészségügyi adatok esetén az xAI szerint egy kérdőív kitöltése után aláírható egy BAA (Business Associate Agreement).
Mérd a késleltetést. A hívók által érzékelt késés összeadódik a telefonhálózat, a híd (ha van ilyen) és a válaszgenerálás idejéből. Mérd ezt végponttól végpontig valós hívásokon, és tartsd gyorsan futónak azokat a függvényeket, amelyeket az ügynök a beszélgetés során meghív.
Főbb megállapítások
- Közvetlen SIP esetén az xAI fogadja a számodat, egy aláírt
realtime.call.incomingwebhookkal értesít, te pedig awss://api.x.ai/v1/realtime?call_id=…címen keresztül csatlakozol a híváshoz - A
referátirányítja a hívást (a kimenetel a HTTP-válaszban érkezik vissza), ahanguppedig bontja azt - A DTMF-gombok eljutnak a modellhez, és az
input_audio_buffer.dtmf_event_receivedeseményen keresztül naplózódnak; asend_dtmfeszköz lehetővé teszi, hogy az ügynök nyomjon meg gombokat - A saját szervereden átívelő hídnál a natív G.711 (
audio/pcmu,audio/pcma) elkerüli az átkódolást - A LiveKit Agents és a Pipecat azok az integrációk, amelyeket az xAI felsorol