Puhelinliikenne: SIP, LiveKit ja G.711
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n SIP Phone Calls -oppaan, Speech to Speech -sivun ja Phone Voice Agent -keittokirjaesimerkin perusteella. xAI voi vastata puheluihin suoraan omaan numeroosi (suora SIP, allekirjoitettu webhook, siirto, puhelun päättäminen, DTMF-näppäimet) oman palvelimesi kautta kulkevan sillan lisäksi. Lähteet: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Yhdistä Voice Agent API puhelinverkkoon
Voice Agent API pystyy vastaanottamaan puheluja: asiakkaasi soittavat tavalliseen numeroon ja keskustelevat Grok-agenttisi kanssa. Tähän pääset kolmea reittiä pitkin, kaikista integroiduimmasta joustavimpaan.
Reitti 1: suora SIP xAI:n kanssa
Tässä tilassa xAI vastaa puheluun itse. Puhelu saapuu xAI:n SIP-infrastruktuuriin, joka ilmoittaa sinulle webhookilla; sovelluksesi liittyy puheluun WebSocketin kautta ja ohjaa agenttia.
- Rekisteröi numero. Ilmoita xAI:lle “Direct SIP” -numero sekä webhook-osoite, johon saapuvat puhelut lähetetään. Jos käytät omaa numeroasi, määritä
origin: "byo_trunk": xAI ei tarjoa numeroita API:n kautta. Vastaus sisältää allekirjoitussalaisuuden, joka palautetaan vain kerran, joten tallenna se turvalliseen säilöösi. - Ohjaa operaattorisi. Määritä operaattorisi tai puhelinvaihteesi (PBX) lähettämään puhelut osoitteeseen
sip:{number}@sip.voice.x.ai. xAI hyväksyy SIP-signaloinnin TLS:n yli portissa 5061 tai TCP:n/UDP:n yli portissa 5060; käytä ensisijaisesti parametria;transport=tls, jos operaattorisi tukee sitä. - Vastaanota webhook. Jokaista puhelua varten xAI lähettää allekirjoitetun
realtime.call.incoming-webhookin. Varmista otsikotwebhook-id,webhook-timestampjawebhook-signatureallekirjoitussalaisuudella ja lue sen jälkeendata.call_id. - Liity puheluun. Avaa yhteys osoitteeseen
wss://api.x.ai/v1/realtime?call_id={call_id}käyttämällä API-avaintasi (väliaikaisia tunnuksia ei hyväksytä SIP-istunnossa), lähetäsession.updateja sen jälkeenresponse.create, kun agentin tulee puhua.
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
Kun yhteys on muodostettu, istunto toimii kuin mikä tahansa muu ääni-istunto: xAI välittää soittajan äänen ja toistaa agentin vastauksen hänelle ilman, että palvelimesi käsittelee äänidataa.
Siirto tai puhelun päättäminen
Kahta REST-kutsua käytetään linjan hallintaan. POST /v1/realtime/calls/{call_id}/refer siirtää soittajan, kun parametrina on target_uri muodossa tel: tai sip:; pyyntö odottaa siirron lopputulosta. Tyhjä runko sisältävä 200 tarkoittaa, että kohde vastasi; 502 sisältää SIP-hylkäyskoodin ja 504 ilmoittaa aikakatkoksesta. Epäonnistumisen jälkeen istunto pysyy auki ja agentti voi jatkaa puhumista: sinun tehtäväsi on lukea vastaus ja tarvittaessa pyytää agenttia selittämään tilanne. POST /v1/realtime/calls/{call_id}/hangup päättää puhelun.
Näppäinsyöte (DTMF)
SIP-istunnossa soittajan painamat näppäimet puskuroidaan ja välitetään mallille tekstinä heti, kun soittaja painaa #, 2,5 sekunnin kuluttua edellisestä näppäinpainalluksesta tai heti, kun hän alkaa puhua. Klienttisi vastaanottaa yhden input_audio_buffer.dtmf_event_received -tapahtuman kutakin näppäintä kohden, joten voit pitää niistä kirjaa. Jos haluat agentin painavan näppäimiä itse, esimerkiksi navigoidaksesi toisen palvelun puhelinvalikossa, lisää sen työkaluihin {"type": "function", "name": "send_dtmf"} ilman parametreja: API tarjoaa skeeman ja lähettää äänisignaalit, eikä sinun tarvitse vastata näihin funktiokutsuihin. Nämä tapahtumat ovat olemassa vain SIP-istunnossa.
Tuettujen operaattoreiden dokumentaatio
xAI:n opas käy läpi asennuksen neljälle operaattorille (Twilio, jossa Elastic SIP Trunking ja puhelusiirrot on otettava käyttöön trunkissa, jos siirrät puheluja; Bandwidth; Telnyx; ja Plivo) sekä mille tahansa operaattorille, kontaktikeskukselle tai puhelinvaihteelle, joka pystyy avaamaan SIP-reitin numerosi osoitteeseen. Koodekkien osalta Telnyx-esimerkki pyytää ottamaan käyttöön vähintään G.711 μ-law-, G.711 A-law- tai G.722-tuen.
Reitti 2: silta oman palvelimesi kautta
Jos haluat pitää äänivirran hallinnassa, palvelimesi vastaanottaa puheluäänen ja välittää sen tavalliseen WebSocket-istuntoon. Tämä on xAI:n keittokirjan Phone Voice Agent -esimerkin arkkitehtuuri: Twilio streamaa puheluäänen μ-law-muodossa Media Streams -palvelunsa kautta, ja palvelin välittää sen sellaisenaan API:lle molempiin suuntiin ilman muunnosta.
# 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 hyväksyy natiivisti molemmat G.711-muunnokset, mikä vältää transkoodauksen: audio/pcmu (μ-law, Pohjois-Amerikan ja Japanin standardi) ja audio/pcma (A-law, Euroopan ja useimpien muiden maiden standardi), molemmat taajuudella 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF-näppäimet sekä REST-siirto- ja lopetuskutsut kuuluvat suoraan SIP-reittiin: sillassa operaattorisi hoitaa ne.
Reitti 3: reaaliaikainen kehys
xAI:n dokumentaatio listaa kaksi valmista integraatiota: LiveKit Agents ja Pipecat. Ne hoitavat reaaliaikaisen kuljetuksen (WebRTC, huoneet, puhelun reititys) ja kytkevät Grok-ääniagentin oikeaan kohtaan, mikä säästää tiimiä rakentamasta telekommunikaatiokerrosta alusta alkaen.
Tuotantoympäristössä
Käsittele hiljaisuudet. Puhelimessa hiljainen soittaja jättää linjan kuolleeksi. turn_detection.idle_timeout_ms saa agentin tarkistamaan tilanteen soittajalta valitsemasi pituisen hiljaisuuden jälkeen (oppitunti 6).
Jatka keskustelua uudessa puhelussa. Istunnon jatkaminen toimii myös SIP:n yli: ota käyttöön resumption.enabled ensimmäisessä puhelussa ja säilytä sen call_id. Kun asiakas soittaa uudelleen, avaa wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} ja lähetä sama session.update uudelleen. Historia vanhentuu 30 minuutin toimettomuuden jälkeen.
Noudata sääntöjä. Kerro soittajille, että he keskustelevat tekoälyn kanssa, ja jos nauhoitat puheluja, mainitse se heti alussa. Terveystietojen osalta xAI:n mukaan BAA-sopimus (Business Associate Agreement) voidaan allekirjoittaa kyselyn jälkeen.
Mittaa viiveesi. Soittajan havaitsema viive muodostuu puhelinverkon, mahdollisen siltasi ja vastauksen generoinnin summasta. Mittaa se päästä päähän oikeissa puheluissa ja pidä agentin puhelun aikana kutsumat funktiot nopeina.
Keskeiset asiat
- Suoralla SIPillä xAI vastaa numeroosi, ilmoittaa sinulle allekirjoitetulla
realtime.call.incoming-webhookilla, ja liityt puheluun osoitteessawss://api.x.ai/v1/realtime?call_id=… refersiirtää puhelun (lopputulos palautuu HTTP-vastauksessa) jahanguppäättää sen- DTMF-näppäimet saapuvat mallille ja kirjautuvat tapahtuman
input_audio_buffer.dtmf_event_receivedkautta; työkalusend_dtmfantaa agentille mahdollisuuden painaa näppäimiä - Palvelimesi kautta kulkevassa sillassa natiivi G.711 (
audio/pcmu,audio/pcma) välttää transkoodauksen - LiveKit Agents ja Pipecat ovat xAI:n listaamat integraatiot