Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Telefonija: SIP, LiveKit in G.711

Lekcija 15 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Poveži Voice Agent API s telefonskim omrežjem
  2. Pot 1: neposredni SIP z xAI
  3. Pot 2: most prek tvojega strežnika
  4. Pot 3: okvir za delo v realnem času
  5. V proizvodnji
  6. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi vodnika xAI SIP Phone Calls, strani Speech to Speech in primera iz kuharice Phone Voice Agent. xAI lahko samodejno odgovarja na klice na tvojo številko (neposredni SIP, podpisani webhook, preusmeritev, prekinitev, tipke DTMF) vzporedno z mostom prek tvojega strežnika. Viri: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Poveži Voice Agent API s telefonskim omrežjem

Voice Agent API lahko sprejema telefonske klice: tvoje stranke pokličejo običajno številko in govorijo s tvojim agentom Grok. Do tega cilja vodiš po treh poteh, od najbolj integrirane do najbolj prilagodljive.

Pot 1: neposredni SIP z xAI

V tem načinu klic sprejme sam xAI. Klic pristane na infrastrukturi SIP podjetja xAI, ki te obvesti prek webhooka; tvoja aplikacija se pridruži klicu prek WebSocketa in upravlja agenta.

  1. Registriraj številko. Prijavi številko „Direct SIP” pri xAI skupaj z naslovom webhooka, ki bo prejemal dohodne klice. Za številko, ki jo že imaš, uporabi origin: "byo_trunk": xAI prek API-ja ne zagotavlja številk. Odziv vsebuje skrivnost za podpisovanje, ki je vrnjena le enkrat, zato jo shrani v svoje trezorje skrivnosti.
  2. Usmeri svojega operaterja. Konfiguriraj svojega operaterja ali PBX, da klice pošilja na sip:{number}@sip.voice.x.ai. xAI sprejema signalizacijo SIP prek TLS na vratih 5061 ali prek TCP/UDP na vratih 5060; kadar tvoj operater to podpira, raje uporabi ;transport=tls.
  3. Prejmi webhook. Za vsak klic xAI pošlje podpisan webhook realtime.call.incoming. Preveri glave webhook-id, webhook-timestamp in webhook-signature s skrivnostjo za podpisovanje, nato preberi data.call_id.
  4. Pridruži se klicu. Odpri wss://api.x.ai/v1/realtime?call_id={call_id} s svojim ključem API (prehodni žetoni za sejo SIP niso sprejeti), pošlji session.update, nato pa response.create, ko naj agent spregovori.
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

Ko je povezava vzpostavljena, se seja obnaša kot katera koli druga glasovna seja: xAI posreduje zvok klicatelja in mu predvaja odziv agenta, tvoj strežnik pa ne prenaša nobenega zvoka.

Preusmeritev ali prekinitev

Linijo nadziraš z dvema klicema REST. POST /v1/realtime/calls/{call_id}/refer s parametrom target_uri v obliki tel: ali sip: preusmeri klicatelja; zahtevek čaka na izid preusmeritve. Koda 200 s praznim telesom pomeni, da je destinacija odgovorila; 502 prinaša kodo zavrnitve SIP, 504 pa signalizira časovni potek. Po napaki seja ostane odprta in agent lahko nadaljuje pogovor: tvoja naloga je, da prebereš odziv in po potrebi agentu naročiš, naj pojasni težavo. POST /v1/realtime/calls/{call_id}/hangup klic konča.

Vnos s tipkovnico (DTMF)

V seji SIP so pritisnjene tipke klicatelja medpomnjene in nato posredovane modelu kot besedilo, takoj ko klicatelj pritisne #, po 2,5 sekunde brez novega pritiska ali takoj, ko začne govoriti. Tvoj odjemalec prejme en dogodek input_audio_buffer.dtmf_event_received na tipko, tako da lahko vodiš evidenco. Če želiš, da agent sam pritisne tipke (npr. za navigacijo po telefonskem meniju druge storitve), dodaj {"type": "function", "name": "send_dtmf"} med njegova orodja brez parametrov: API zagotovi shemo in pošlje tone, ti pa na te klice funkcij ne smeš odgovarjati. Ti dogodki obstajajo le v seji SIP.

Dokumentirani operaterji

Vodnik xAI podrobno opisuje nastavitev za štiri operaterje (Twilio z omogočenim Elastic SIP Trunking in preusmeritvijo klicev na trupu, če klice preusmerjaš; Bandwidth; Telnyx; in Plivo) ter za katerega koli operaterja, kontaktni center ali PBX, ki lahko odpre pot SIP do naslova tvoje številke. Pri kodeku primer Telnyx zahteva, da omogočiš vsaj G.711 μ-law, G.711 A-law ali G.722.

Pot 2: most prek tvojega strežnika

Če želiš obdržati nadzor nad zvočnim tokom, tvoj strežnik prejme zvok klica in ga posreduje v običajno sejo WebSocket. To je arhitektura primera Phone Voice Agent iz kuharice xAI: Twilio pretaka zvok klica v μ-law prek svojih Media Streams, strežnik pa ga v obeh smereh brez pretvorbe posreduje API-ju.

# 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 izvorno sprejema obe različici G.711, kar preprečuje kakršno koli transkodiranje: audio/pcmu (μ-law, standard v Severni Ameriki in na Japonskem) ter audio/pcma (A-law, standard v Evropi in večini drugih držav), obe pri 8000 Hz.

{
  "audio": {
    "input": {"format": {"type": "audio/pcma", "rate": 8000}},
    "output": {"format": {"type": "audio/pcma", "rate": 8000}}
  }
}

Tipke DTMF ter klica REST za preusmeritev in prekinitev spadata k poti neposrednega SIP: pri mostu jih obravnava tvoj operater.

Pot 3: okvir za delo v realnem času

Dokumentacija xAI navaja dve vnaprej pripravljeni integraciji: LiveKit Agents in Pipecat. Obravnavata prenos v realnem času (WebRTC, sobe, usmerjanje klicev) in vstavita glasovnega agenta Grok na pravo mesto, kar ekipam, ki ne želijo graditi telefonske plasti od nič, prihrani veliko dela.

V proizvodnji

Obdeluj tišino. Pri telefonskih klicih klicatelj, ki utihne, pusti mrtvo linijo. turn_detection.idle_timeout_ms poskrbi, da se agent oglasi klicatelju po izbrani dolžini tišine (lekcija 6).

Nadaljuj pogovor ob novem klicu. Obnovitev seje deluje tudi prek SIP: ob prvem klicu omogoči resumption.enabled in ohrani njegov call_id. Ko stranka ponovno pokliče, odpri wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} in znova pošlji isti session.update. Zgodovina poteče po 30 minutah nedejavnosti.

Upoštevaj pravila. Obvesti klicatelje, da govorijo z umetno inteligenco, in če klice snemaš, to povej že na začetku. Za zdravstvene podatke xAI navaja, da je mogoče po izpolnjenem vprašalniku podpisati sporazum BAA (Business Associate Agreement).

Izmeri svojo latenco. Zamuda, ki jo zazna klicatelj, je vsota zamud telefonskega omrežja, tvojega mostu (če ga imaš) in generiranja odziva. Izmeri jo od konca do konca pri realnih klicih in poskrbi, da bodo funkcije, ki jih agent kliče med pogovorom, hitre.

Ključne ugotovitve

  • Pri neposrednem SIP xAI odgovori na tvojo številko, te obvesti s podpisanim webhookom realtime.call.incoming, ti pa se klicu pridružiš prek wss://api.x.ai/v1/realtime?call_id=…
  • refer preusmeri klic (izid se vrne v odzivu HTTP), hangup pa ga konča
  • Tipke DTMF prispejo do modela in se beležijo prek input_audio_buffer.dtmf_event_received; orodje send_dtmf omogoča agentu, da pritisne tipke
  • Pri mostu prek tvojega strežnika izvorni G.711 (audio/pcmu, audio/pcma) prepreči transkodiranje
  • LiveKit Agents in Pipecat sta integraciji, ki ju navaja xAI