Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Telefonija: SIP, LiveKit u G.711

Lezzjoni 15 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Qabbad l-API tal-Aġent Vuwkali man-network tat-telefon
  2. Mogħdija 1: SIP dirett ma’ xAI
  3. Mogħdija 2: Pont permezz tas-server tiegħek stess
  4. Mogħdija 3: Qafas f’ħin reali
  5. Fil-produzzjoni
  6. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026, ibbażat fuq il-gwida SIP Phone Calls ta’ xAI, il-paġna Speech to Speech, u l-eżempju tal-kotba tar-riċetti Phone Voice Agent. xAI jista’ jwieġeb is-sejħiet fuq in-numru tiegħek stess (SIP dirett, webhook iffirmat, trasferiment, qtugħ, ċwievet DTMF), flimkien ma’ pont permezz tas-server tiegħek stess. Sorsi: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Qabbad l-API tal-Aġent Vuwkali man-network tat-telefon

L-API tal-Aġent Vuwkali tista’ tieħu sejħiet telefoniċi: il-klijenti tiegħek iċempelju numru ordinarju u jitkellmu mal-aġent Grok tiegħek. Tliet mogħdijiet iwassluk hemm, mill-aktar integrat għall-aktar flessibbli.

Mogħdija 1: SIP dirett ma’ xAI

F’dan il-mod, xAI jwieġeb is-sejħa nnifsu. Is-sejħa tinżel fuq l-infrastruttura SIP ta’ xAI, li tavżak permezz ta’ webhook; l-app tiegħek tingħaqad mas-sejħa fuq WebSocket u tmexxi l-aġent.

  1. Irreġistra n-numru. Iddikjara numru “Direct SIP” ma’ xAI, flimkien mal-indirizz tal-webhook li se jirċievi s-sejħiet li qed jaslu. Għal numru li għandek int, uża origin: "byo_trunk": xAI ma jipprovdix numri permezz tal-API. Ir-risposta fiha sigriet ta’ firma, li jiġi rritornat darba biss, allura aħżnu fil-vault tas-sigrieti tiegħek.
  2. Irrota l-operatur tiegħek. Ikkonfigura l-operatur jew il-PBX tiegħek biex jibgħat is-sejħiet lejn sip:{number}@sip.voice.x.ai. xAI jaċċetta s-sinjalar SIP fuq TLS fuq il-port 5061, jew TCP jew UDP fuq il-port 5060; ippreferi ;transport=tls meta l-operatur tiegħek jappoġġjah.
  3. Irċievi l-webhook. Għal kull sejħa, xAI jibgħat webhook iffirmat realtime.call.incoming. Ivverifika l-intestaturi webhook-id, webhook-timestamp, u webhook-signature bis-sigriet tal-firma, imbagħad aqra data.call_id.
  4. Ingħaqad mas-sejħa. Iftaħ wss://api.x.ai/v1/realtime?call_id={call_id} bil-key tal-API tiegħek (tokens effimeri ma jiġux aċċettati għal sessjoni SIP), ibgħat session.update, imbagħad response.create meta l-aġent għandu jitkellem.
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

Ladarba tkun konness, is-sessjoni tiġi bħal kwalunkwe sessjoni vokali oħra: xAI jgħaddi l-awdjo ta’ min iċempel u jdoqq lura l-aġent lilu, mingħajr ma s-server tiegħek iġorr kwalunkwe ħoss.

Trasferiment jew qtugħ

Żewġ sejħiet REST jikkontrollaw il-linja. POST /v1/realtime/calls/{call_id}/refer, b’target_uri fil-forma tel: jew sip:, jittrasferixxi lil min iċempel; it-talba tistenna r-riżultat tat-trasferiment. 200 b’korp vojt ifisser li d-destinazzjoni wieġbet; 502 iġorr il-kodiċi ta’ rifjut SIP, u 504 jissinjala time-out. Wara falliment, is-sessjoni tibqa’ miftuħa u l-aġent jista’ jkompli jitkellem: tiddependi fuqek li taqra r-rispons u, jekk ikun meħtieġ, tagħmel lill-aġent jispjega l-intopp. POST /v1/realtime/calls/{call_id}/hangup itemm is-sejħa.

Input tat-tastiera (DTMF)

F’sessjoni SIP, iċ-ċwievet li jħabbat min iċempel jiġu bbuffrjati u mbagħad mgħoddija lill-mudell bħala test hekk kif min iċempel iħabbat #, wara 2.5 sekondi mingħajr ċavetta ġdida, jew hekk kif jibdew jitkellmu. Il-klijent tiegħek jirċievi avveniment wieħed input_audio_buffer.dtmf_event_received għal kull ċavetta, sabiex tkun tista’ żżomm rekord. Biex tħalli lill-aġent iħabbat iċ-ċwievet huwa stess, pereżempju biex jinnaviga menu tat-telefon ta’ servizz ieħor, żid {"type": "function", "name": "send_dtmf"} mal-għodod tiegħu, mingħajr parametri: l-API tipprovdi l-iskema u tibgħat it-toni, u m’intix trid twieġeb dawn is-sejħiet tal-funzjoni. Dawn l-avvenimenti jeżistu biss fuq sessjoni SIP.

Operaturi dokumentati

Il-gwida ta’ xAI tgħaddi mill-installazzjoni għal erba’ operaturi (Twilio, b’Elastic SIP Trunking u t-trasferiment tas-sejħiet attivat fuq it-trunk jekk tittrasferixxi s-sejħiet; Bandwidth; Telnyx; u Plivo) u għal kwalunkwe operatur, ċentru ta’ kuntatt, jew PBX li jista’ jiftaħ rotta SIP lejn l-indirizz tan-numru tiegħek. Fuq in-naħa tal-codec, l-eżempju ta’ Telnyx jitlobek tattivà mill-inqas G.711 μ-law, G.711 A-law, jew G.722.

Mogħdija 2: Pont permezz tas-server tiegħek stess

Jekk trid iżżomm il-kontroll tal-fluss tal-awdjo, is-server tiegħek jirċievi l-awdjo tas-sejħa u jgħaddih lil sessjoni regolari ta’ WebSocket. Dik hija l-arkitettura tal-eżempju Phone Voice Agent tal-kotba tar-riċetti ta’ xAI: Twilio jstreamja l-awdjo tas-sejħa f’μ-law permezz tal-Media Streams tiegħu, u s-server jgħaddih lill-API kif inhu, mingħajr konverżjoni, fiż-żewġ direzzjonijiet.

# 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(),
        }))

L-API taċċetta nattivament iż-żewġ varjanti ta’ G.711, li jevita kwalunkwe transkoding: audio/pcmu (μ-law, l-istandard tal-Amerika ta’ Fuq u l-Ġappun) u audio/pcma (A-law, l-istandard fl-Ewropa u fil-biċċa l-kbira tal-pajjiżi l-oħra), it-tnejn f’8000 Hz.

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

Iċ-ċwiefet DTMF u s-sejħiet REST ta’ trasferiment u qtugħ jappartjenu għall-mogħdija diretta ta’ SIP: f’pont, l-operatur tiegħek jimmaniġġjahom.

Mogħdija 3: Qafas f’ħin reali

Id-dokumentazzjoni ta’ xAI telenka żewġ integrazzjonijiet lesti: LiveKit Agents u Pipecat. Dawn jimmaniġġjaw it-trasport f’ħin reali (WebRTC, kmamar, irrottar tas-sejħiet) u jqabbdu lill-aġent vokali Grok fil-post it-tajjeb, li jiffranka lil tim li ma jridx jibni saff ta’ telefonija milli jagħmel hekk.

Fil-produzzjoni

Immaniġġja s-silenzji. Fit-telefon, min iċempel li jissieket iħalli linja mejta. turn_detection.idle_timeout_ms jagħmel lill-aġent jiċċekkja ma’ min iċempel wara silenzju tat-tul li tagħżel int (lezzjoni 6).

Erġa’ ħu konversazzjoni fuq sejħa ġdida. Ir-ripristinar tas-sessjoni jaħdem ukoll fuq SIP: attiva resumption.enabled fuq l-ewwel sejħa u żomm il-call_id tagħha. Meta l-klijent jerġa’ jċempel, iftaħ wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} u ibgħat l-istess session.update mill-ġdid. L-istorja tiskadi wara 30 minuta ta’ inattività.

Segwi r-regoli. Għid lil min iċempel li qed jitkellem ma’ AI u, jekk tirreġistra s-sejħiet, għid hekk fil-bidu. Għal data dwar is-saħħa, xAI jgħid li BAA (Ftehim ta’ Assoċjat tan-Negozju) jista’ jiġi ffirmat wara kwestjonarju.

Kejjel il-latency tiegħek. Id-dewmien li jħoss min iċempel jgħodd in-network tat-telefon, il-pont tiegħek jekk ikollok wieħed, u l-ġenerazzjoni tar-rispons. Kejjlu minn tarf sa tarf fuq sejħiet reali, u żżomm il-funzjonijiet li jsejjaħ l-aġent matul il-konversazzjoni mgħaġġla.

Punti Ewlenin

  • Bis-SIP dirett, xAI jwieġeb in-numru tiegħek, javżak b’webhook iffirmat realtime.call.incoming, u tingħaqad mas-sejħa permezz ta’ wss://api.x.ai/v1/realtime?call_id=…
  • refer jittrasferixxi s-sejħa (ir-riżultat jerġa’ lura fir-rispons HTTP), u hangup itemmha
  • Iċ-ċwievet DTMF jaslu għand il-mudell u jiġu rreġistrati permezz ta’ input_audio_buffer.dtmf_event_received; l-għodda send_dtmf tħalli lill-aġent iħabbat iċ-ċwievet
  • F’pont permezz tas-server tiegħek, G.711 nattiva (audio/pcmu, audio/pcma) jevita t-transkoding
  • LiveKit Agents u Pipecat huma l-integrazzjonijiet elenkati minn xAI