Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Telefónia: SIP, LiveKit a G.711

Lekcia 15 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Pripojenie Voice Agent API k telefónnej sieti
  2. Cesta 1: Priame SIP s xAI
  3. Cesta 2: Most cez tvoj vlastný server
  4. Cesta 3: Framework pre prácu v reálnom čase
  5. V produkcii
  6. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe príručky xAI SIP Phone Calls, stránky Speech to Speech a príkladu z kuchárky Phone Voice Agent. xAI dokáže prijímať hovory priamo na tvoje číslo (priame SIP, podpísaný webhook, prepojenie, zavesenie, tlačidlá DTMF) súčasne s mostom cez tvoj vlastný server. Zdroje: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Pripojenie Voice Agent API k telefónnej sieti

Voice Agent API dokáže prijímať telefónne hovory: tvoji zákazníci vytočia bežné číslo a rozprávajú sa s tvojím agentom Grok. Existujú tri cesty, ako to dosiahnuť – od najviac integrovanej po najflexibilnejšiu.

Cesta 1: Priame SIP s xAI

V tomto režime odpovedá na hovor priamo xAI. Hovor dorazí na SIP infraštruktúru xAI, ktorá ťa upozorní prostredníctvom webhooku; tvoja aplikácia sa potom pripojí k hovoru cez WebSocket a riadi agenta.

  1. Registrácia čísla. Nahlás xAI číslo typu „Direct SIP“ spolu s adresou webhooku, ktorá bude prijímať prichádzajúce hovory. Pre číslo, ktoré vlastníš, použi origin: "byo_trunk": xAI neposkytuje čísla priamo cez API. Odpoveď obsahuje podpisový tajný kľúč (signing secret), ktorý je vrátený iba raz, takže si ho ulož do svojho trezoru tajov.
  2. Smerovanie u operátora. Nakonfiguruj svojho operátora alebo ústredňu (PBX), aby smerovala hovory na sip:{number}@sip.voice.x.ai. xAI prijíma SIP signalizáciu cez TLS na porte 5061 alebo cez TCP či UDP na porte 5060; ak to tvoj operátor podporuje, uprednostni ;transport=tls.
  3. Prijatie webhooku. Pre každý hovor odošle xAI podpísaný webhook realtime.call.incoming. Over hlavičky webhook-id, webhook-timestamp a webhook-signature pomocou podpisového tajného kľúča a následne si prečítaj data.call_id.
  4. Pripojenie k hovoru. Otvor spojenie wss://api.x.ai/v1/realtime?call_id={call_id} pomocou svojho API kľúča (pre SIP reláciu nie sú akceptované dočasné tokeny), pošli session.update a následne response.create, keď má agent začať hovoriť.
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

Po pripojení sa relácia správa ako ktorákoľvek iná hlasová relácia: xAI preposiela audio volajúceho a prehráva mu odpovede agenta, pričom tvoj server neprenáša žiadny zvuk.

Prepojenie alebo zavesenie

Linku ovládaš dvoma REST volaniami. POST /v1/realtime/calls/{call_id}/refer s parametrom target_uri vo forme tel: alebo sip: prepojí volajúceho; požiadavka čaká na výsledok prepojenia. Stavový kód 200 s prázdnym telom znamená, že cieľová strana zdvihla; kód 502 obsahuje kód zamietnutia SIP a 504 signalizuje časový limit. Po zlyhaní zostáva relácia otvorená a agent môže pokračovať v rozhovore: je na tebe, aby si spracoval odpoveď a v prípade potreby nechal agenta vysvetliť problém. POST /v1/realtime/calls/{call_id}/hangup hovor ukončí.

Vstup z klávesnice (DTMF)

V SIP relácii sú stlačené klávesy volajúceho bufferované a odovzdané modelu ako text hneď, ako volajúci stlačí #, po 2,5 sekundy bez stlačenia ďalšej klávesy, alebo hneď, ako začne hovoriť. Tvoj klient dostane jednu udalosť input_audio_buffer.dtmf_event_received na každú klávesu, takže si môžeš viesť záznam. Ak chceš, aby agent sám stláčal klávesy (napríklad na navigáciu v telefónnom menu inej služby), pridaj do jeho nástrojov {"type": "function", "name": "send_dtmf"} bez parametrov: API poskytne schému a odošle tóny, pričom ty nesmieš na tieto volania funkcií odpovedať. Tieto udalosti existujú iba v SIP relácii.

Zdokumentovaní operátori

Príručka xAI podrobne popisuje nastavenie pre štyroch operátorov (Twilio s Elastic SIP Trunking a povoleným prepojením hovorov na trunku, ak hovory prepojuješ; Bandwidth; Telnyx; a Plivo) a pre akéhokoľvek operátora, kontaktné centrum alebo ústredňu (PBX), ktorá dokáže otvoriť SIP trasu na adresu tvojho čísla. Čo sa týka kodekov, príklad pre Telnyx vyžaduje povolenie aspoň jedného z formátov: G.711 μ-law, G.711 A-law alebo G.722.

Cesta 2: Most cez tvoj vlastný server

Ak chceš zachovať kontrolu nad audio streamom, tvoj server prijíma audio z hovoru a preposiela ho do bežnej WebSocket relácie. To je architektúra príkladu Phone Voice Agent z kuchárky xAI: Twilio streamuje audio hovoru vo formáte μ-law prostredníctvom svojich Media Streams a server ho obojsmerne preposiela do API tak, ako je, bez konverzie.

# 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 natívne prijíma obe varianty G.711, čo eliminuje potrebu transkódovania: audio/pcmu (μ-law, štandard pre Severnú Ameriku a Japonsko) a audio/pcma (A-law, štandard v Európe a väčšine ostatných krajín), obe pri 8000 Hz.

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

Klávesy DTMF a REST volania pre prepojenie a zavesenie patria k ceste priameho SIP: v prípade mosta ich vybavuje tvoj operátor.

Cesta 3: Framework pre prácu v reálnom čase

Dokumentácia xAI uvádza dve hotové integrácie: LiveKit Agents a Pipecat. Tie riešia transport v reálnom čase (WebRTC, miestnosti, smerovanie hovorov) a zapájajú hlasového agenta Grok na správne miesto, čo šetrí tímom prácu s budovaním vlastnej telefónnej vrstvy.

V produkcii

Ošetrenie ticha. Pri telefónnom hovore znamená ticho volajúceho mŕtvu linku. Nastavenie turn_detection.idle_timeout_ms zabezpečí, že sa agent po zvolenom čase ticha ozve volajúcemu (lekcia 6).

Pokračovanie v konverzácii pri novom hovore. Obnovenie relácie funguje aj cez SIP: pri prvom hovore povoľ resumption.enabled a uchovaj si jeho call_id. Keď zákazník zavolá späť, otvor wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} a znova pošli rovnaké session.update. História vyprší po 30 minútach nečinnosti.

Dodržiavanie pravidiel. Informuj volajúcich, že hovoria s AI, a ak hovory nahrávaš, oznám im to hneď na začiatku. Pri zdravotných údajoch xAI uvádza, že po vyplnení dotazníka je možné podpísať zmluvu BAA (Business Associate Agreement).

Meranie latencie. Oneskorenie, ktoré volajúci vníma, je súčtom oneskorenia telefónnej siete, tvojho mosta (ak ho máš) a generovania odpovede. Meraj ho end-to-end na reálnych hovoroch a zabezpeč, aby funkcie, ktoré agent počas konverzácie volá, boli rýchle.

Kľúčové poznatky

  • Pri priamom SIP odpovedá xAI na tvoje číslo, upozorní ťa podpísaným webhookom realtime.call.incoming a ty sa pripojíš k hovoru cez wss://api.x.ai/v1/realtime?call_id=…
  • refer prepojí hovor (výsledok sa vráti v HTTP odpovedi) a hangup ho ukončí
  • Klávesy DTMF sa dostanú k modelu a sú zaznamenané cez input_audio_buffer.dtmf_event_received; nástroj send_dtmf umožňuje agentovi stláčať klávesy
  • Pri moste cez tvoj server sa vyhneš transkódovaniu vďaka natívnemu G.711 (audio/pcmu, audio/pcma)
  • LiveKit Agents a Pipecat sú integrácie, ktoré xAI odporúča