Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Telefoni: SIP, LiveKit og G.711

Lektion 15 af 16 Opdateret 3. november 2026 Udvikler
På denne side
  1. Forbind Voice Agent API’et til telefonnettet
  2. Vej 1: Direkte SIP med xAI
  3. Vej 2: En bro gennem din egen server
  4. Vej 3: Et realtidsframework
  5. I produktion
  6. Vigtige pointer

Opdateret 3. november 2026, baseret på xAI-guiden SIP Phone Calls, siden Speech to Speech og kogebogseksemplet Phone Voice Agent. xAI kan selv besvare opkald på dit nummer (direkte SIP, signeret webhook, overførsel, læg på, DTMF-taster) sideløbes med en bro gennem din egen server. Kilder: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Forbind Voice Agent API’et til telefonnettet

Voice Agent API’et kan modtage telefonopkald: Dine kunder ringer til et almindeligt nummer og taler med din Grok-agent. Tre veje fører dig dertil, fra den mest integrerede til den mest fleksible.

Vej 1: Direkte SIP med xAI

I denne tilstand besvarer xAI selv opkaldet. Opkaldet lander på xAI’s SIP-infrastruktur, som underretter dig via en webhook; din app forbinder sig til opkaldet over WebSocket og styrer agenten.

  1. Registrer nummeret. Deklar et „Direct SIP”-nummer hos xAI sammen med webhook-adressen, der skal modtage indgående opkald. Brug origin: "byo_trunk" for et nummer, du selv ejer: xAI leverer ikke numre via API’et. Svaret indeholder en signeringsnøgle, der kun returneres én gang, så gem den i dit hemmelighedslager.
  2. Diriger din operatør. Konfigurer din operatør eller PBX til at sende opkald til sip:{number}@sip.voice.x.ai. xAI accepterer SIP-signalering over TLS på port 5061 eller TCP/UDP på port 5060; foretræk ;transport=tls, når din operatør understøtter det.
  3. Modtag webhooken. For hvert opkald sender xAI en signeret realtime.call.incoming-webhook. Verificér headereene webhook-id, webhook-timestamp og webhook-signature med signeringsnøglen, og læs derefter data.call_id.
  4. Deltag i opkaldet. Åbn wss://api.x.ai/v1/realtime?call_id={call_id} med din API-nøgle (ephemeral tokens accepteres ikke til en SIP-session), send session.update, og derefter response.create, når agenten skal tale.
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

Når forbindelsen er etableret, opfører sessionen sig som enhver anden talesession: xAI videresender opkalderens lyd og afspiller agenten tilbage til dem, uden at din server behøver at håndtere selve lyden.

Overførsel eller læg på

To REST-kald styrer linjen. POST /v1/realtime/calls/{call_id}/refer med en target_uri i formatet tel: eller sip: overfører opkalderen; forespørgslen venter på resultatet af overførslen. En 200 med en tom body betyder, at destinationen svarede; en 502 indeholder SIP-afvisningskoden, og en 504 signalerer et timeout. Efter en fejl forbliver sessionen åben, og agenten kan fortsætte med at tale: Det er op til dig at læse svaret og om nødvendigt få agenten til at forklare problemet. POST /v1/realtime/calls/{call_id}/hangup afslutter opkaldet.

Tastaturinput (DTMF)

I en SIP-session bufferes de taster, opkalderen trykker på, og sendes derefter til modellen som tekst, så snart opkalderen trykker på #, efter 2,5 sekunder uden nyt tastetryk, eller så snart de begynder at tale. Din klient modtager én input_audio_buffer.dtmf_event_received-begivenhed pr. tast, så du kan føre en log. For at lade agenten selv trykke på taster, f.eks. for at navigere i en anden tjenestes telefonmenu, skal du tilføje {"type": "function", "name": "send_dtmf"} til dens værktøjer uden parametre: API’et leverer skemaet og sender tonerne, og du må ikke besvare disse funktionskald. Disse begivenheder eksisterer kun i en SIP-session.

Dokumenterede operatører

xAI-guiden gennemgår opsætningen for fire operatører (Twilio med Elastic SIP Trunking og aktiveret opkaldsoverførsel på trunken, hvis du overfører opkald; Bandwidth; Telnyx; og Plivo) samt for enhver operatør, kontaktcenter eller PBX, der kan åbne en SIP-rute til dit nummers adresse. På codec-siden beder Telnyx-eksemplet dig om at aktivere mindst G.711 μ-law, G.711 A-law eller G.722.

Vej 2: En bro gennem din egen server

Hvis du vil beholde kontrollen over lydstrømmen, modtager din server opkaldslyden og videresender den til en almindelig WebSocket-session. Det er arkitekturen i xAI-kogebogens eksempel Phone Voice Agent: Twilio streamer opkaldslyden i μ-law gennem sine Media Streams, og serveren sender den videre til API’et, som den er, uden konvertering i begge retninger.

# 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’et accepterer nativt begge G.711-varianter, hvilket undgår enhver transkodning: audio/pcmu (μ-law, standarden i Nordamerika og Japan) og audio/pcma (A-law, standarden i Europa og de fleste andre lande), begge ved 8000 Hz.

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

DTMF-taster samt REST-kald til overførsel og afslutning hører til den direkte SIP-vej: I en bro-håndtering håndterer din operatør disse.

Vej 3: Et realtidsframework

xAI-dokumentationen lister to færdige integrationer: LiveKit Agents og Pipecat. De håndterer realtidstransport (WebRTC, rum, opkaldsrouting) og kobler Grok-voice-agenten ind på det rette sted, hvilket sparer et team, der ikke ønsker at bygge et telefonilag fra bunden, for arbejdet.

I produktion

Håndter stilhed. På telefonen efterlader en opkalder, der tier, en død linje. turn_detection.idle_timeout_ms får agenten til at tjekke ind hos opkalderen efter en stilhed af den længde, du vælger (lektion 6).

Genoptag en samtale ved et nyt opkald. Sessionsgenoptagelse fungerer også over SIP: Aktivér resumption.enabled ved det første opkald, og behold dets call_id. Når kunden ringer tilbage, åbnes wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id}, og du sender den samme session.update igen. Historikken udløber efter 30 minutters inaktivitet.

Følg reglerne. Fortæl opkaldere, at de taler med en AI, og sig det også i starten, hvis du optager opkald. For sundhedsdata oplyser xAI, at en BAA (Business Associate Agreement) kan underskrives efter et spørgeskema.

Mål din latency. Forsinkelsen, som opkaldere oplever, er summen af telefonnettet, din bro (hvis du har en) og svar-genereringen. Mål den ende-til-ende på rigtige opkald, og sørg for, at de funktioner, agenten kalder under samtalen, er hurtige.

Vigtige pointer

  • Med direkte SIP besvarer xAI dit nummer, underretter dig med en signeret realtime.call.incoming-webhook, og du deltager i opkaldet via wss://api.x.ai/v1/realtime?call_id=…
  • refer overfører opkaldet (resultatet returneres i HTTP-svaret), og hangup afslutter det
  • DTMF-taster når modellen og logges via input_audio_buffer.dtmf_event_received; værktøjet send_dtmf lader agenten trykke på taster
  • I en bro gennem din server undgår native G.711 (audio/pcmu, audio/pcma) transkodning
  • LiveKit Agents og Pipecat er de integrationer, xAI lister