Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Telefonija: SIP, LiveKit i G.711

Lekcija 15 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Povezivanje Voice Agent API-ja s telefonskom mrežom
  2. Put 1: izravni SIP s xAI-jem
  3. Put 2: most preko tvog vlastitog poslužitelja
  4. Put 3: okvir za rad u stvarnom vremenu
  5. U proizvodnji
  6. Ključne točke

Ažurirano 3. studenoga 2026., na temelju xAI vodiča SIP Phone Calls, stranice Speech to Speech i primjera iz kuharice Phone Voice Agent. xAI može sam odgovarati na pozive na tvoj broj (izravni SIP, potpisani webhook, prosljeđivanje, prekid veze, DTMF tipke), uz most preko tvog vlastitog poslužitelja. Izvori: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Povezivanje Voice Agent API-ja s telefonskom mrežom

Voice Agent API može primati telefonske pozive: tvoji klijenti biraju običan broj i razgovaraju s tvojim Grok agentom. Tri su puta do toga, od najintegriranijeg do najfleksibilnijeg.

Put 1: izravni SIP s xAI-jem

U ovom načinu rada xAI sam odgovara na poziv. Poziv završava na xAI-jevoj SIP infrastrukturi, koja te obavještava putem webhooka; tvoja aplikacija se pridružuje pozivu preko WebSocketa i upravlja agentom.

  1. Registriraj broj. Prijavi broj „Izravni SIP“ (Direct SIP) kod xAI-ja, zajedno s adresom webhooka koja će primati dolazne pozive. Za broj koji posjeduješ koristi origin: "byo_trunk": xAI ne dodjeljuje brojeve putem API-ja. Odgovor sadrži tajnu za potpisivanje koja se vraća samo jednom, pa je pohrani u svoj trezor tajni.
  2. Usmjeri svog operatera. Konfiguriraj svog operatera ili PBX da šalje pozive na sip:{number}@sip.voice.x.ai. xAI prihvaća SIP signalizaciju preko TLS-a na portu 5061 ili TCP/UDP na portu 5060; preferiraj ;transport=tls kada ga tvoj operater podržava.
  3. Primi webhook. Za svaki poziv xAI šalje potpisani webhook realtime.call.incoming. Potvrdi zaglavlja webhook-id, webhook-timestamp i webhook-signature pomoću tajne za potpisivanje, zatim pročitaj data.call_id.
  4. Pridruži se pozivu. Otvori wss://api.x.ai/v1/realtime?call_id={call_id} sa svojim API ključem (privremeni tokeni nisu prihvaćeni za SIP sesiju), pošalji session.update, a zatim response.create kada agent treba progovoriti.
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

Nakon povezivanja, sesija se ponaša kao bilo koja druga glasovna sesija: xAI prosljeđuje audio pozivatelja i reproducira agenta natrag njemu, bez da tvoj poslužitelj prenosi zvuk.

Prosljeđivanje ili prekid veze

Dva REST poziva upravljaju linijom. POST /v1/realtime/calls/{call_id}/refer, s target_uri u obliku tel: ili sip:, prosljeđuje pozivatelja; zahtjev čeka ishod prosljeđivanja. 200 s praznim tijelom znači da je odredište odgovorilo; 502 nosi SIP kod odbijanja, a 504 signalizira istek vremena. Nakon neuspjeha sesija ostaje otvorena i agent može nastaviti razgovor: na tebi je da pročitaš odgovor i, ako je potrebno, navedeš agenta da objasni problem. POST /v1/realtime/calls/{call_id}/hangup završava poziv.

Unos s tipkovnice (DTMF)

Na SIP sesiji tipke koje pozivatelj pritisne međuspremaju se, a zatim prosljeđuju modelu kao tekst čim pozivatelj pritisne #, nakon 2,5 sekunde bez nove tipke ili čim počne govoriti. Tvoj klijent prima jedan događaj input_audio_buffer.dtmf_event_received po tipki, tako da možeš voditi evidenciju. Da bi agent sam pritiskao tipke, primjerice za navigaciju kroz telefonski izbornik druge usluge, dodaj {"type": "function", "name": "send_dtmf"} u njegove alate, bez parametara: API pruža shemu i šalje tonove, a ti ne smiješ odgovarati na ove pozive funkcija. Ovi događaji postoje samo na SIP sesiji.

Dokumentirani operateri

xAI vodič prolazi kroz postavke za četiri operatera (Twilio, s uključenim Elastic SIP Trunkingom i prosljeđivanjem poziva na trupu ako prosljeđuješ pozive; Bandwidth; Telnyx; i Plivo) te za bilo kojeg operatera, kontakt centar ili PBX koji može otvoriti SIP rutu do adrese tvog broja. Što se tiče kodeka, Telnyx primjer traži da omogućiš barem G.711 μ-law, G.711 A-law ili G.722.

Put 2: most preko tvog vlastitog poslužitelja

Ako želiš zadržati kontrolu nad audio tokom, tvoj poslužitelj prima audio poziva i prosljeđuje ga redovnoj WebSocket sesiji. To je arhitektura xAI-jevog primjera Phone Voice Agent iz kuharice: Twilio strimuje audio poziva u μ-law formatu kroz svoje Media Streams, a poslužitelj ga prosljeđuje API-ju kakav jest, bez konverzije, u oba smjera.

# 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 prihvaća obje varijante G.711, čime se izbjegava transkodiranje: audio/pcmu (μ-law, standard u Sjevernoj Americi i Japanu) i audio/pcma (A-law, standard u Europi i većini drugih zemalja), oba na 8000 Hz.

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

DTMF tipke te REST pozivi za prosljeđivanje i prekid veze pripadaju putu izravnog SIP-a: u mostu ih obrađuje tvoj operater.

Put 3: okvir za rad u stvarnom vremenu

xAI dokumentacija navodi dvije gotove integracije: LiveKit Agents i Pipecat. One rukuju prijenosom u stvarnom vremenu (WebRTC, sobe, usmjeravanje poziva) i uključuju Grok glasovnog agenta na pravom mjestu, što štedi timove koji ne žele graditi telefonski sloj od nule.

U proizvodnji

Rukuj tišinama. Na telefonu, pozivatelj koji utihne ostavlja mrtvu liniju. turn_detection.idle_timeout_ms navodi agenta da se javi pozivatelju nakon tišine trajanja koje odabereš (lekcija 6).

Nastavi razgovor na novom pozivu. Nastavak sesije također radi preko SIP-a: omogući resumption.enabled na prvom pozivu i zadrži njegov call_id. Kada klijent ponovno nazove, otvori wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} i ponovno pošalji isti session.update. Povijest istječe nakon 30 minuta neaktivnosti.

Slijedi pravila. Obavijesti pozivatelje da razgovaraju s AI-jem i, ako snimaš pozive, reci to na početku. Za zdravstvene podatke, xAI navodi da se BAA (Business Associate Agreement) može potpisati nakon upitnika.

Izmjeri svoju latenciju. Kašnjenje koje pozivatelji percipiraju zbraja telefonsku mrežu, tvoj most (ako ga imaš) i generiranje odgovora. Izmjeri ga od kraja do kraja na stvarnim pozivima i osiguraj da funkcije koje agent poziva tijekom razgovora budu brze.

Ključne točke

  • S izravnim SIP-om, xAI odgovara na tvoj broj, obavještava te potpisanim webhookom realtime.call.incoming, a ti se pridružuješ pozivu putem wss://api.x.ai/v1/realtime?call_id=…
  • refer prosljeđuje poziv (ishod se vraća u HTTP odgovoru), a hangup ga završava
  • DTMF tipke stižu do modela i bilježe se kroz input_audio_buffer.dtmf_event_received; alat send_dtmf omogućuje agentu pritiskanje tipki
  • U mostu preko tvog poslužitelja, izvorni G.711 (audio/pcmu, audio/pcma) izbjegava transkodiranje
  • LiveKit Agents i Pipecat integracije su koje xAI navodi