Премини към основното съдържание
Български— Изберете език
Меню

Телефония: SIP, LiveKit и G.711

Урок 15 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Свързване на Voice Agent API с телефонната мрежа
  2. Път 1: Директен SIP с xAI
  3. Път 2: Мост през Вашия собствен сървър
  4. Път 3: Framework за работа в реално време
  5. В продукционна среда
  6. Ключови изводи

Обновено на 3 ноември 2026 г., въз основа на ръководството на xAI SIP Phone Calls, страницата Speech to Speech и примера от готварската книга Phone Voice Agent. xAI може да отговаря на обаждания към Вашия номер директно (директен SIP, подписан уебхук, прехвърляне, затваряне, клавиши DTMF), успоредно с мост през Вашия собствен сървър. Източници: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Свързване на Voice Agent API с телефонната мрежа

Voice Agent API може да приема телефонни обаждания: Вашите клиенти набират обикновен номер и разговарят с Вашия агент Grok. Три пътя Ви водят дотам – от най-интегрирания до най-гъвкавия.

Път 1: Директен SIP с xAI

В този режим xAI самото отговаря на обаждането. Обаждането постъпва в SIP инфраструктурата на xAI, която Ви уведомява чрез уебхук; Вашето приложение се присъединява към разговора през WebSocket и управлява агента.

  1. Регистрирайте номера. Декларирайте номер за „Директен SIP“ пред xAI, заедно с адреса на уебхука, който ще получава входящи обаждания. За номер, който притежавате, използвайте origin: "byo_trunk": xAI не предоставя номера чрез API. Отговорът съдържа таен ключ за подписване, който се връща само веднъж, така че го съхранете в хранилището си за тайни.
  2. Насочете Вашия оператор. Конфигурирайте Вашия телеком оператор или PBX да изпраща обажданията към sip:{number}@sip.voice.x.ai. xAI приема SIP сигнализиране през TLS на порт 5061 или през TCP/UDP на порт 5060; предпочитайте ;transport=tls, когато Вашият оператор го поддържа.
  3. Получете уебхука. За всяко обаждане xAI изпраща подписан уебхук realtime.call.incoming. Проверете хедърите webhook-id, webhook-timestamp и webhook-signature с тайния ключ за подписване, след което прочетете data.call_id.
  4. Свържете се с обаждането. Отворете връзка към wss://api.x.ai/v1/realtime?call_id={call_id} с Вашия API ключ (ефемерните токени не се приемат за SIP сесия), изпратете session.update, а след това response.create, когато агентът трябва да заговори.
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

След свързването сесията се държи като всяка друга гласова сесия: xAI препредава аудиото на обаждащия се и възпроизвежда агента обратно към него, без Вашият сървър да пренася звук.

Прехвърляне или затваряне

Два REST повиквания контролират линията. POST /v1/realtime/calls/{call_id}/refer, с target_uri във формат tel: или sip:, прехвърля обаждащия се; заявката изчаква резултата от прехвърлянето. Код 200 с празно тяло означава, че дестинацията е отговорила; 502 носи SIP кода за отказ, а 504 сигнализира изтичане на времето за изчакване. След неуспех сесията остава отворена и агентът може да продължи да говори: Вашата задача е да прочетете отговора и при необходимост агентът да обясни проблема. POST /v1/realtime/calls/{call_id}/hangup прекратява обаждането.

Въвеждане от клавиатура (DTMF)

При SIP сесия натиснатите от обаждащия се клавиши се буферират и се предават на модела като текст веднага щом обаждащият се натисне #, след 2,5 секунди без нов натиск или веднага щом започне да говори. Вашият клиент получава по едно събитие input_audio_buffer.dtmf_event_received за всеки клавиш, така че можете да водите запис. За да позволите на агента сам да натиска клавиши, например за навигация в телефонното меню на друга услуга, добавете {"type": "function", "name": "send_dtmf"} към неговите инструменти, без параметри: API предоставя схемата и изпраща тоновете, а Вие не трябва да отговаряте на тези функционални повиквания. Тези събития съществуват само при SIP сесия.

Документирани оператори

Ръководството на xAI описва настройката за четири оператора (Twilio, с активирано Elastic SIP Trunking и прехвърляне на обаждания в трънката, ако прехвърляте обаждания; Bandwidth; Telnyx; и Plivo), както и за всеки оператор, контакт център или PBX, който може да отвори SIP маршрут към адреса на Вашия номер. Що се отнася до кодека, примерът с Telnyx изисква да активирате поне G.711 μ-law, G.711 A-law или G.722.

Път 2: Мост през Вашия собствен сървър

Ако искате да запазите контрол над аудиопотока, Вашият сървър получава аудиото от обаждането и го препредава към обикновена WebSocket сесия. Това е архитектурата на примера Phone Voice Agent от готварската книга на xAI: Twilio стриймва аудиото на обаждането в μ-law чрез своите Media Streams, а сървърът го предава на API така, както си е, без конвертиране, и в двете посоки.

# 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 приема нативно и двата варианта на G.711, което избягва всякакво транскодиране: audio/pcmu (μ-law, стандартът в Северна Америка и Япония) и audio/pcma (A-law, стандартът в Европа и повечето други страни), и двата при 8000 Hz.

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

Клавишите DTMF и REST повикванията за прехвърляне и затваряне принадлежат към пътя с директен SIP: при мост Вашият оператор се справя с тях.

Път 3: Framework за работа в реално време

Документацията на xAI изброява две готови интеграции: LiveKit Agents и Pipecat. Те обработват транспорта в реално време (WebRTC, стаи, насочване на обаждания) и включват гласовия агент Grok на правилното място, което спестява на екипи, които не искат да изграждат телефонен слой от нулата, необходимостта да го правят.

В продукционна среда

Обработвайте тишината. По телефона обаждащ се, който замълчи, оставя линията мъртва. turn_detection.idle_timeout_ms кара агента да провери дали обаждащият се е все още там след тишина с продължителност по Ваш избор (урок 6).

Подхванете разговор при ново обаждане. Възобновяването на сесията работи и през SIP: активирайте resumption.enabled при първото обаждане и запазете неговия call_id. Когато клиентът се обади отново, отворете wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} и изпратете отново същото session.update. Историята изтича след 30 минути неактивност.

Следвайте правилата. Информирайте обаждащите се, че разговарят с изкуствен интелект, и ако записвате обажданията, го кажете в началото. За здравни данни xAI посочва, че може да се подпише BAA (Споразумение за бизнес партньор) след попълване на въпросник.

Измервайте латентността си. Забавянето, което обаждащите се възприемат, се сумира от телефонната мрежа, Вашия мост (ако имате такъв) и генерирането на отговора. Измервайте го от край до край при реални обаждания и поддържайте функциите, които агентът извиква по време на разговора, бързи.

Ключови изводи

  • При директен SIP xAI отговаря на Вашия номер, Ви уведомява с подписан уебхук realtime.call.incoming, а Вие се свързвате с обаждането чрез wss://api.x.ai/v1/realtime?call_id=…
  • refer прехвърля обаждането (резултатът се връща в HTTP отговора), а hangup го прекратява
  • Клавишите DTMF достигат до модела и се регистрират чрез input_audio_buffer.dtmf_event_received; инструментът send_dtmf позволява на агента да натиска клавиши
  • При мост през Вашия сървър нативният G.711 (audio/pcmu, audio/pcma) избягва транскодирането
  • LiveKit Agents и Pipecat са интеграциите, изброени от xAI