Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Telefonie: SIP, LiveKit a G.711

Lekce 15 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Propojení Voice Agent API s telefonní sítí
  2. Cesta 1: Přímý SIP s xAI
  3. Cesta 2: Most přes váš vlastní server
  4. Cesta 3: Framework pro práci v reálném čase
  5. V produkci
  6. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě příručky xAI SIP Phone Calls, stránky Speech to Speech a ukázkového projektu Phone Voice Agent. xAI může přijímat hovory přímo na vaše číslo (přímý SIP, podepsaný webhook, přepojení, zavěšení, klávesy DTMF) vedle mostu přes váš vlastní server. Zdroje: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Propojení Voice Agent API s telefonní sítí

Voice Agent API umí přijímat telefonní hovory: vaši zákazníci vytočí běžné číslo a hovoří s vaším agentem Grok. Existují tři cesty, jak toho dosáhnout, od nejvíce integrované po nejflexibilnější.

Cesta 1: Přímý SIP s xAI

V tomto režimu hovor přijímá přímo xAI. Hovor dorazí na SIP infrastrukturu xAI, která vás upozorní prostřednictvím webhooku; vaše aplikace se poté připojí k hovoru přes WebSocket a řídí agenta.

  1. Registrace čísla. Deklarujte u xAI číslo typu „Direct SIP“ spolu s adresou webhooku, která bude přijímat příchozí hovory. Pro číslo, které již vlastníte, použijte origin: "byo_trunk": xAI neposkytuje telefonní čísla prostřednictvím API. Odpověď obsahuje podpisový tajný klíč (signing secret), který je vrácen pouze jednou, takže si jej uložte do svého trezoru s tajnými údaji.
  2. Směrování operátora. Nakonfigurujte svého operátora nebo ústřednu (PBX) tak, aby směrovaly hovory na sip:{number}@sip.voice.x.ai. xAI přijímá SIP signalizaci přes TLS na portu 5061 nebo přes TCP či UDP na portu 5060; pokud to váš operátor podporuje, upřednostněte ;transport=tls.
  3. Přijetí webhooku. Pro každý hovor odešle xAI podepsaný webhook realtime.call.incoming. Ověřte hlavičky webhook-id, webhook-timestamp a webhook-signature pomocí podpisového tajného klíče a poté si přečtěte data.call_id.
  4. Připojení k hovoru. Otevřete spojení wss://api.x.ai/v1/realtime?call_id={call_id} pomocí svého API klíče (pro relaci SIP nejsou přijímány krátkodobé tokeny), odešlete session.update a následně response.create, když má agent promluvit.
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

Jakmile je spojení navázáno, relace se chová jako jakákoli jiná hlasová relace: xAI přenáší audio volajícího a přehývá mu odpovědi agenta, aniž by váš server musel přenášet jakýkoli zvuk.

Přepojení nebo zavěšení

Linku ovládají dva požadavky REST. POST /v1/realtime/calls/{call_id}/refer s parametrem target_uri ve formátu tel: nebo sip: přepojí volajícího; požadavek čeká na výsledek přepojení. Kód 200 s prázdným tělem znamená, že cíl hovor přijal; kód 502 nese kód odmítnutí SIP a kód 504 signalizuje vypršení časového limitu. Po selhání zůstává relace otevřená a agent může pokračovat v hovoru: je na vás, abyste přečetli odpověď a v případě potřeby nechali agenta vysvětlit problém. POST /v1/realtime/calls/{call_id}/hangup hovor ukončí.

Vstup z klávesnice (DTMF)

V relaci SIP jsou klávesy, které volající stiskne, bufferovány a předány modelu jako text, jakmile volající stiskne #, po 2,5 sekundách bez stisku nové klávesy, nebo jakmile začne mluvit. Váš klient obdrží jednu událost input_audio_buffer.dtmf_event_received na každou klávesu, takže si můžete vést záznam. Pokud chcete, aby agent sám mačkal klávesy, například pro navigaci v telefonním menu jiné služby, přidejte do jeho nástrojů {"type": "function", "name": "send_dtmf"} bez parametrů: API poskytuje schéma a odešle tóny, vy však na tyto volání funkcí nesmíte odpovídat. Tyto události existují pouze v relaci SIP.

Zdokumentovaní operátoři

Příručka xAI podrobně popisuje nastavení pro čtyři operátory (Twilio s povoleným Elastic SIP Trunkingem a přepojením hovorů na trunku, pokud hovory přepojujete; Bandwidth; Telnyx; a Plivo) a pro jakéhokoli operátora, kontaktní centrum nebo ústřednu (PBX), která dokáže otevřít SIP trasu na adresu vašeho čísla. Co se týče kodeků, příklad s Telnyxem vyžaduje povolení alespoň jednoho z formátů: G.711 μ-law, G.711 A-law nebo G.722.

Cesta 2: Most přes váš vlastní server

Pokud si chcete ponechat kontrolu nad zvukovým streamem, váš server přijme audio z hovoru a předá jej do běžné relace WebSocket. To je architektura ukázkového projektu Phone Voice Agent od xAI: Twilio streamuje audio hovoru ve formátu μ-law prostřednictvím svých Media Streams a server jej předává API tak, jak je, bez konverze, v obou směrech.

# 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 nativně přijímá obě varianty G.711, což eliminuje potřebu překódování: audio/pcmu (μ-law, standard pro Severní Ameriku a Japonsko) a audio/pcma (A-law, standard pro Evropu a většinu ostatních zemí), oba při 8000 Hz.

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

Klávesy DTMF a volání REST pro přepojení a zavěšení patří k cestě přímého SIP: v případě mostu je zpracovává váš operátor.

Cesta 3: Framework pro práci v reálném čase

Dokumentace xAI uvádí dvě připravená integrovaná řešení: LiveKit Agents a Pipecat. Ta řeší transport v reálném čase (WebRTC, místnosti, směrování hovorů) a zapojují hlasového agenta Grok na správné místo, což šetří týmy, které nechtějí budovat telefonní vrstvu od nuly.

V produkci

Zpracovávejte ticho. Při telefonátu zanechá mlčící volající mrtvou linku. Parametr turn_detection.idle_timeout_ms zajistí, že se agent ozve volajícímu po vámi zvolené době ticha (lekce 6).

Navázání na konverzaci při novém hovoru. Obnovení relace funguje i přes SIP: povolte resumption.enabled při prvním hovoru a uchovejte jeho call_id. Když zákazník zavolá znovu, otevřete wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} a znovu odešlete stejné session.update. Historie vyprší po 30 minutách nečinnosti.

Dodržujte pravidla. Informujte volající, že hovoří s AI, a pokud hovory nahráváte, sdělte jim to na začátku. U zdravotních údajů xAI uvádí, že po vyplnění dotazníku lze podepsat dohodu o zpracování osobních údajů (BAA – Business Associate Agreement).

Měřte latenci. Zpoždění, které volající vnímá, je součtem latence telefonní sítě, vašeho mostu (pokud jej máte) a generování odpovědi. Měřte ji end-to-end na skutečných hovorech a udržujte funkce, které agent během konverzace volá, co nejrychlejší.

Klíčové poznatky

  • Při přímém SIP odpovídá xAI na vaše číslo, upozorní vás podepsaným webhookem realtime.call.incoming a vy se připojíte k hovoru přes wss://api.x.ai/v1/realtime?call_id=…
  • refer přepojí hovor (výsledek se vrátí v HTTP odpovědi) a hangup jej ukončí
  • Klávesy DTMF dorazí k modelu a jsou logovány prostřednictvím input_audio_buffer.dtmf_event_received; nástroj send_dtmf umožňuje agentovi mačkat klávesy
  • V mostu přes váš server eliminuje nativní G.711 (audio/pcmu, audio/pcma) potřebu překódování
  • LiveKit Agents a Pipecat jsou integrace, které xAI uvádí