Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Puhelinliikenne: SIP, LiveKit ja G.711

Oppitunti 15 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Yhdistä Voice Agent API puhelinverkkoon
  2. Reitti 1: suora SIP xAI:n kanssa
  3. Reitti 2: silta oman palvelimesi kautta
  4. Reitti 3: reaaliaikainen kehys
  5. Tuotantoympäristössä
  6. Keskeiset asiat

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.

  1. 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.
  2. 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ä.
  3. Vastaanota webhook. Jokaista puhelua varten xAI lähettää allekirjoitetun realtime.call.incoming -webhookin. Varmista otsikot webhook-id, webhook-timestamp ja webhook-signature allekirjoitussalaisuudella ja lue sen jälkeen data.call_id.
  4. 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.update ja sen jälkeen response.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 osoitteessa wss://api.x.ai/v1/realtime?call_id=…
  • refer siirtää puhelun (lopputulos palautuu HTTP-vastauksessa) ja hangup päättää sen
  • DTMF-näppäimet saapuvat mallille ja kirjautuvat tapahtuman input_audio_buffer.dtmf_event_received kautta; työkalu send_dtmf antaa 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