Telefonia: SIP, LiveKit e G.711
Nesta página
Atualizado em 3 de novembro de 2026, com base no guia SIP Phone Calls da xAI, na página Speech to Speech e no exemplo de livro de receitas Phone Voice Agent. A xAI pode atender chamadas no seu próprio número (SIP direto, webhook assinado, transferência, desligamento, teclas DTMF), paralelamente a uma ponte através do seu próprio servidor. Fontes: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Ligar a Voice Agent API à rede telefónica
A Voice Agent API pode receber chamadas telefónicas: os seus clientes marcam um número comum e conversam com o seu agente Grok. Existem três caminhos para chegar lá, do mais integrado ao mais flexível.
Caminho 1: SIP direto com a xAI
Neste modo, a xAI atende a chamada diretamente. A chamada chega à infraestrutura SIP da xAI, que o notifica via webhook; a sua aplicação junta-se à chamada através de WebSocket e gere o agente.
- Registar o número. Declare um número “Direct SIP” junto da xAI, juntamente com o endereço do webhook que receberá as chamadas entrantes. Para um número que já possua, utilize
origin: "byo_trunk": a xAI não fornece números através da API. A resposta contém um segredo de assinatura, devolvido apenas uma vez, pelo que o deve guardar no seu cofre de segredos. - Encaminhar a sua operadora. Configure a sua operadora ou PBX para enviar chamadas para
sip:{number}@sip.voice.x.ai. A xAI aceita sinalização SIP sobre TLS na porta 5061, ou TCP/UDP na porta 5060; prefira;transport=tlsquando a sua operadora o suportar. - Receber o webhook. Para cada chamada, a xAI envia um webhook assinado
realtime.call.incoming. Verifique os cabeçalhoswebhook-id,webhook-timestampewebhook-signaturecom o segredo de assinatura e, em seguida, leiadata.call_id. - Juntar-se à chamada. Abra
wss://api.x.ai/v1/realtime?call_id={call_id}com a sua chave de API (tokens efémeros não são aceites numa sessão SIP), enviesession.updatee, depois,response.createquando o agente dever falar.
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
Uma vez estabelecida a ligação, a sessão comporta-se como qualquer outra sessão de voz: a xAI retransmite o áudio do chamador e reproduz a resposta do agente, sem que o seu servidor tenha de transportar qualquer som.
Transferir ou desligar
Duas chamadas REST controlam a linha. POST /v1/realtime/calls/{call_id}/refer, com um target_uri no formato tel: ou sip:, transfere o chamador; o pedido aguarda o resultado da transferência. Um código 200 com corpo vazio significa que o destino atendeu; um 502 transporta o código de rejeição SIP e um 504 sinaliza um tempo limite esgotado. Após uma falha, a sessão mantém-se aberta e o agente pode continuar a falar: cabe-lhe a si ler a resposta e, se necessário, fazer o agente explicar o contratempo. POST /v1/realtime/calls/{call_id}/hangup termina a chamada.
Entrada por teclado (DTMF)
Numa sessão SIP, as teclas pressionadas pelo chamador são colocadas em buffer e depois passadas ao modelo como texto assim que o chamador pressionar #, após 2,5 segundos sem nova tecla, ou assim que começar a falar. O seu cliente recebe um evento input_audio_buffer.dtmf_event_received por tecla, permitindo-lhe manter um registo. Para permitir que o próprio agente pressione teclas, por exemplo para navegar num menu telefónico de outro serviço, adicione {"type": "function", "name": "send_dtmf"} às suas ferramentas, sem parâmetros: a API fornece o esquema e envia os tons, e não deve responder a estas chamadas de função. Estes eventos existem apenas numa sessão SIP.
Operadoras documentadas
O guia da xAI detalha a configuração para quatro operadoras (Twilio, com Elastic SIP Trunking e transferência de chamadas ativada no tronco se transferir chamadas; Bandwidth; Telnyx; e Plivo) e para qualquer operadora, centro de contacto ou PBX capaz de abrir uma rota SIP para o endereço do seu número. No que toca aos codecs, o exemplo da Telnyx solicita a ativação de, pelo menos, G.711 μ-law, G.711 A-law ou G.722.
Caminho 2: uma ponte através do seu próprio servidor
Se desejar manter o controlo do fluxo de áudio, o seu servidor recebe o áudio da chamada e retransmite-o para uma sessão WebSocket normal. Esta é a arquitetura do exemplo Phone Voice Agent do livro de receitas da xAI: a Twilio transmite o áudio da chamada em μ-law através dos seus Media Streams, e o servidor passa-o para a API tal como está, sem conversão, em ambas as direções.
# 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(),
}))
A API aceita nativamente ambas as variantes G.711, o que evita qualquer transcodificação: audio/pcmu (μ-law, o padrão na América do Norte e Japão) e audio/pcma (A-law, o padrão na Europa e na maioria dos outros países), ambos a 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
As teclas DTMF e as chamadas REST de transferência e desligamento pertencem ao caminho SIP direto: numa ponte, é a sua operadora que as gere.
Caminho 3: uma estrutura em tempo real
A documentação da xAI lista duas integrações prontas a usar: LiveKit Agents e Pipecat. Estas gerem o transporte em tempo real (WebRTC, salas, encaminhamento de chamadas) e integram o agente de voz Grok no local adequado, poupando às equipas que não desejam construir uma camada de telefonia desde zero esse esforço.
Em produção
Gerir os silêncios. No telefone, um chamador que fica em silêncio deixa a linha morta. turn_detection.idle_timeout_ms faz com que o agente verifique a situação com o chamador após um silêncio da duração que escolher (lição 6).
Retomar uma conversa numa nova chamada. A retoma de sessão também funciona via SIP: ative resumption.enabled na primeira chamada e guarde o seu call_id. Quando o cliente voltar a ligar, abra wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} e envie novamente o mesmo session.update. O histórico expira após 30 minutos de inatividade.
Seguir as regras. Informe os chamadores de que estão a falar com uma IA e, se gravar as chamadas, mencione-o no início. Para dados de saúde, a xAI indica que um BAA (Business Associate Agreement) pode ser assinado após um questionário.
Medir a sua latência. O atraso percecionado pelos chamadores soma a rede telefónica, a sua ponte (se existir) e a geração da resposta. Meça-o de ponta a ponta em chamadas reais e mantenha rápidas as funções que o agente chama durante a conversa.
Pontos-chave
- Com SIP direto, a xAI atende o seu número, notifica-o com um webhook assinado
realtime.call.incominge junta-se à chamada através dewss://api.x.ai/v1/realtime?call_id=… refertransfere a chamada (o resultado retorna na resposta HTTP) ehanguptermina-a- As teclas DTMF chegam ao modelo e são registadas através de
input_audio_buffer.dtmf_event_received; a ferramentasend_dtmfpermite ao agente pressionar teclas - Numa ponte através do seu servidor, o G.711 nativo (
audio/pcmu,audio/pcma) evita a transcodificação - LiveKit Agents e Pipecat são as integrações listadas pela xAI