Przejdź do głównej treści
Polski— Wybierz język
Menu

Telefonia: SIP, LiveKit i G.711

Lekcja 15 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Podłącz Voice Agent API do sieci telefonicznej
  2. Ścieżka 1: bezpośredni SIP z xAI
  3. Ścieżka 2: mostkowanie przez własny serwer
  4. Ścieżka 3: framework czasu rzeczywistego
  5. W środowisku produkcyjnym
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie przewodnika xAI SIP Phone Calls, strony Speech to Speech oraz przykładu z książki kucharskiej Phone Voice Agent. xAI może samodzielnie odbierać połączenia na Twój numer (bezpośredni SIP, podpisany webhook, przekazywanie połączeń, rozłączanie, klawisze DTMF), równolegle do mostkowania przez Twój własny serwer. Źródła: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Podłącz Voice Agent API do sieci telefonicznej

Voice Agent API potrafi obsługiwać połączenia telefoniczne: Twoi klienci dzwonią na zwykły numer i rozmawiają z Twoim agentem Grok. Istnieją trzy ścieżki, które Cię tam doprowadzą – od najbardziej zintegrowanej po najbardziej elastyczną.

Ścieżka 1: bezpośredni SIP z xAI

W tym trybie to xAI samodzielnie odbiera połączenie. Rozmowa trafia na infrastrukturę SIP xAI, która powiadamia Cię za pomocą webhooka; Twoja aplikacja dołącza do połączenia przez WebSocket i steruje agentem.

  1. Zarejestruj numer. Zgłoś numer „Direct SIP“ w xAI wraz z adresem webhooka, który ma otrzymywać połączenia przychodzące. W przypadku numeru, który już posiadasz, użyj origin: "byo_trunk": xAI nie udostępnia numerów przez API. Odpowiedź zawiera sekret podpisujący, zwracany tylko raz, więc zapisz go w swoim bezpiecznym magazynie haseł.
  2. Skonfiguruj trasowanie u operatora. Skonfiguruj swojego operatora lub centralę PBX tak, aby wysyłały połączenia na adres sip:{number}@sip.voice.x.ai. xAI akceptuje sygnalizację SIP przez TLS na porcie 5061 lub przez TCP/UDP na porcie 5060; preferuj ;transport=tls, jeśli Twój operator to obsługuje.
  3. Odbierz webhook. Dla każdego połączenia xAI wysyła podpisany webhook realtime.call.incoming. Zweryfikuj nagłówki webhook-id, webhook-timestamp i webhook-signature przy użyciu sekretu podpisującego, a następnie odczytaj data.call_id.
  4. Dołącz do połączenia. Otwórz połączenie wss://api.x.ai/v1/realtime?call_id={call_id} używając swojego klucza API (tokeny jednorazowe nie są akceptowane w sesji SIP), wyślij session.update, a następnie response.create, gdy agent ma zacząć mówić.
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 nawiązaniu połączenia sesja zachowuje się jak każda inna sesja głosowa: xAI przesyła audio rozmówcy i odtwarza odpowiedź agenta, bez konieczności przenoszenia dźwięku przez Twój serwer.

Przekazywanie lub rozłączanie połączenia

Dwa wywołania REST sterują linią. POST /v1/realtime/calls/{call_id}/refer z parametrem target_uri w formacie tel: lub sip: przekazuje rozmówcę; żądanie czeka na wynik przekierowania. Kod 200 z pustym ciałem oznacza, że cel odebrał; 502 zawiera kod odrzucenia SIP, a 504 sygnalizuje przekroczenie czasu oczekiwania. Po niepowodzeniu sesja pozostaje otwarta i agent może kontynuować rozmowę: to do Ciebie należy odczytanie odpowiedzi i, w razie potrzeby, wyjaśnienie przez agenta zaistniałego problemu. POST /v1/realtime/calls/{call_id}/hangup kończy połączenie.

Wprowadzanie z klawiatury (DTMF)

W sesji SIP naciśnięte przez rozmówcę klawisze są buforowane, a następnie przekazywane do modelu jako tekst natychmiast po naciśnięciu #, po 2,5 sekundy bez nowego klawisza lub gdy tylko rozmówca zacznie mówić. Twój klient otrzymuje jedno zdarzenie input_audio_buffer.dtmf_event_received na każdy klawisz, dzięki czemu możesz prowadzić rejestr. Aby umożliwić agentowi samodzielne naciskanie klawiszy (np. w celu nawigacji po menu telefonicznym innej usługi), dodaj do jego narzędzi {"type": "function", "name": "send_dtmf"} bez parametrów: API dostarcza schemat i wysyła tony, a Ty nie musisz odpowiadać na te wywołania funkcji. Zdarzenia te występują wyłącznie w sesji SIP.

Udokumentowani operatorzy

Przewodnik xAI przeprowadza przez konfigurację dla czterech operatorów (Twilio z włączonym Elastic SIP Trunking i przekazywaniem połączeń na poziomie trasy, jeśli planujesz przekazywać rozmowy; Bandwidth; Telnyx; oraz Plivo) oraz dla dowolnego operatora, centrum kontaktowego lub centrali PBX, które mogą otworzyć trasę SIP do adresu Twojego numeru. Jeśli chodzi o kodeki, przykład Telnyx wymaga włączenia co najmniej G.711 μ-law, G.711 A-law lub G.722.

Ścieżka 2: mostkowanie przez własny serwer

Jeśli chcesz zachować kontrolę nad strumieniem audio, Twój serwer odbiera audio z połączenia i przekazuje je do zwykłej sesji WebSocket. Taka jest architektura przykładu Phone Voice Agent z książki kucharskiej xAI: Twilio przesyła audio z rozmowy w formacie μ-law przez swoje Media Streams, a serwer przekazuje je do API dokładnie w tej samej postaci, bez konwersji, w obu kierunkach.

# 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 natywnie akceptuje obie wersje G.711, co eliminuje potrzebę transkodowania: audio/pcmu (μ-law, standard w Ameryce Północnej i Japonii) oraz audio/pcma (A-law, standard w Europie i większości innych krajów), oba przy częstotliwości 8000 Hz.

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

Klawisze DTMF oraz wywołania REST do przekazywania i rozłączania należą do ścieżki bezpośredniego SIP: w przypadku mostkowania obsługuje je Twój operator.

Ścieżka 3: framework czasu rzeczywistego

Dokumentacja xAI wymienia dwa gotowe rozwiązania integracyjne: LiveKit Agents i Pipecat. Zajmują się one transportem w czasie rzeczywistym (WebRTC, pokoje, routowanie połączeń) i podpinają agenta głosowego Grok we właściwym miejscu, co oszczędza zespołom, które nie chcą budować warstwy telefonicznej od zera, konieczności jej tworzenia.

W środowisku produkcyjnym

Obsługuj ciszę. W rozmowie telefonicznej milczący rozmówca oznacza „martwą linię“. Parametr turn_detection.idle_timeout_ms sprawia, że agent zgłasza się do rozmówcy po określonej przez Ciebie przerwie w mówieniu (lekcja 6).

Podjęcie rozmowy przy nowym połączeniu. Wznawianie sesji działa również przez SIP: włącz resumption.enabled podczas pierwszego połączenia i zachowaj jego call_id. Gdy klient oddzwoni, otwórz wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} i wyślij ponownie to samo session.update. Historia wygasa po 30 minutach bezczynności.

Przestrzegaj zasad. Poinformuj rozmówców, że rozmawiają ze sztuczną inteligencją, a jeśli nagrywasz rozmowy, powiedz o tym na początku. W przypadku danych zdrowotnych xAI informuje, że umowa BAA (Business Associate Agreement) może zostać podpisana po wypełnieniu kwestionariusza.

Mierz swoje opóźnienia. Opóźnienie odczuwane przez rozmówców to suma opóźnień sieci telefonicznej, Twojego mostka (jeśli go używasz) oraz generowania odpowiedzi. Mierz je end-to-end na rzeczywistych połączeniach i dbaj o to, by funkcje wywoływane przez agenta podczas rozmowy działały szybko.

Kluczowe wnioski

  • Przy bezpośrednim SIP xAI odbiera połączenie na Twój numer, powiadamia Cię podpisanym webhookiem realtime.call.incoming, a Ty dołączasz do rozmowy przez wss://api.x.ai/v1/realtime?call_id=…
  • refer przekazuje połączenie (wynik wraca w odpowiedzi HTTP), a hangup je kończy
  • Klawisze DTMF docierają do modelu i są logowane przez input_audio_buffer.dtmf_event_received; narzędzie send_dtmf pozwala agentowi naciskać klawisze
  • W mostkowaniu przez Twój serwer natywny G.711 (audio/pcmu, audio/pcma) eliminuje konieczność transkodowania
  • LiveKit Agents i Pipecat to integracje wymieniane przez xAI