Ir al contenido principal
Español— Elegir un idioma
Menú

Telefonía: SIP, LiveKit y G.711

Lección 15 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Conecta la API de Voice Agent a la red telefónica
  2. Ruta 1: SIP directo con xAI
  3. Ruta 2: un puente a través de tu propio servidor
  4. Ruta 3: un framework en tiempo real
  5. En producción
  6. Puntos clave

Actualizado el 3 de noviembre de 2026, basándose en la guía SIP Phone Calls de xAI, la página Speech to Speech y el ejemplo de recetario Phone Voice Agent. xAI puede atender llamadas en tu propio número directamente (SIP directo, webhook firmado, transferencia, colgado, teclas DTMF), además de mediante un puente a través de tu propio servidor. Fuentes: SIP Phone Calls · Speech to Speech · Phone Voice Agent.

Conecta la API de Voice Agent a la red telefónica

La API de Voice Agent puede recibir llamadas telefónicas: tus clientes marcan un número ordinario y hablan con tu agente Grok. Existen tres rutas para lograrlo, desde la más integrada hasta la más flexible.

Ruta 1: SIP directo con xAI

En este modo, xAI atiende la llamada directamente. La llamada llega a la infraestructura SIP de xAI, que te notifica mediante un webhook; tu aplicación se une a la llamada a través de WebSocket y controla al agente.

  1. Registra el número. Declara un número de “SIP directo” (Direct SIP) con xAI, junto con la dirección del webhook que recibirá las llamadas entrantes. Para un número que ya posees, usa origin: "byo_trunk": xAI no proporciona números a través de la API. La respuesta contiene un secreto de firma, que se devuelve una sola vez, así que guárdalo en tu bóveda de secretos.
  2. Configura el enrutamiento de tu operador. Configura tu operador o centralita (PBX) para enviar las llamadas a sip:{number}@sip.voice.x.ai. xAI acepta señalización SIP sobre TLS en el puerto 5061, o TCP/UDP en el puerto 5060; prefiere ;transport=tls cuando tu operador lo admita.
  3. Recibe el webhook. Por cada llamada, xAI envía un webhook firmado realtime.call.incoming. Verifica las cabeceras webhook-id, webhook-timestamp y webhook-signature con el secreto de firma y, a continuación, lee data.call_id.
  4. Únete a la llamada. Abre wss://api.x.ai/v1/realtime?call_id={call_id} con tu clave de API (los tokens efímeros no se aceptan para una sesión SIP), envía session.update y, después, response.create cuando el agente deba hablar.
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": "Eres el agente de atención al cliente. Responde en inglés, brevemente.",
                "turn_detection": {"type": "server_vad"},
            },
        }))
        await ws.send(json.dumps({"type": "response.create"}))  # el agente saluda al llamante

        async for message in ws:
            event = json.loads(message)
            # misma gestión que para una sesión WebSocket ordinaria

Una vez conectada, la sesión se comporta como cualquier otra sesión de voz: xAI retransmite el audio del llamante y reproduce la respuesta del agente, sin que tu servidor tenga que transportar ningún sonido.

Transferir o colgar

Dos llamadas REST controlan la línea. POST /v1/realtime/calls/{call_id}/refer, con un target_uri en formato tel: o sip:, transfiere al llamante; la solicitud espera el resultado de la transferencia. Un código 200 con un cuerpo vacío significa que el destino ha contestado; un 502 lleva el código de rechazo SIP y un 504 indica un tiempo de espera agotado. Tras un fallo, la sesión permanece abierta y el agente puede seguir hablando: corresponde a tu aplicación leer la respuesta y, si es necesario, hacer que el agente explique el contratiempo. POST /v1/realtime/calls/{call_id}/hangup finaliza la llamada.

Entrada por teclado (DTMF)

En una sesión SIP, las teclas que pulsa el llamante se almacenan en búfer y se pasan al modelo como texto tan pronto como el usuario pulsa #, tras 2,5 segundos sin pulsar ninguna tecla nueva o en cuanto empieza a hablar. Tu cliente recibe un evento input_audio_buffer.dtmf_event_received por cada tecla, lo que te permite llevar un registro. Para permitir que el agente pulse teclas él mismo, por ejemplo para navegar por el menú telefónico de otro servicio, añade {"type": "function", "name": "send_dtmf"} a sus herramientas, sin parámetros: la API proporciona el esquema y envía los tonos, y tú no debes responder a estas llamadas a funciones. Estos eventos solo existen en una sesión SIP.

Operadores documentados

La guía de xAI detalla la configuración para cuatro operadores (Twilio, con Elastic SIP Trunking y transferencia de llamadas activada en el troncal si realizas transferencias; Bandwidth; Telnyx; y Plivo) y para cualquier operador, centro de contacto o centralita capaz de abrir una ruta SIP hacia la dirección de tu número. En cuanto al códec, el ejemplo de Telnyx solicita activar al menos G.711 μ-law, G.711 A-law o G.722.

Ruta 2: un puente a través de tu propio servidor

Si deseas mantener el control del flujo de audio, tu servidor recibe el audio de la llamada y lo retransmite a una sesión WebSocket ordinaria. Esa es la arquitectura del ejemplo Phone Voice Agent del recetario de xAI: Twilio transmite el audio de la llamada en μ-law a través de sus Media Streams, y el servidor lo pasa a la API tal cual, sin conversión, en ambas direcciones.

# Llamada telefónica → operador → tu servidor → WebSocket de xAI
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 a 8000 Hz, el formato de la red telefónica norteamericana
    await ws.send(json.dumps({
        "type": "session.update",
        "session": {
            "voice": "rex",
            "instructions": "Agente de atención al cliente.",
            "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(),
        }))

La API acepta nativamente ambas variantes de G.711, lo que evita cualquier transcodificación: audio/pcmu (μ-law, el estándar en Norteamérica y Japón) y audio/pcma (A-law, el estándar en Europa y la mayoría de los demás países), ambos a 8000 Hz.

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

Las teclas DTMF y las llamadas REST de transferencia y colgado pertenecen a la ruta de SIP directo: en un puente, tu operador se encarga de ellas.

Ruta 3: un framework en tiempo real

La documentación de xAI enumera dos integraciones listas para usar: LiveKit Agents y Pipecat. Estas gestionan el transporte en tiempo real (WebRTC, salas, enrutamiento de llamadas) e integran al agente de voz Grok en el punto adecuado, lo que ahorra a un equipo que no quiera construir una capa de telefonía desde cero el tener que hacerlo.

En producción

Gestiona los silencios. En el teléfono, un llamante que guarda silencio deja la línea muerta. turn_detection.idle_timeout_ms hace que el agente se ponga en contacto con el llamante tras un silencio de la duración que elijas (lección 6).

Retoma una conversación en una nueva llamada. La reanudación de sesión también funciona mediante SIP: activa resumption.enabled en la primera llamada y conserva su call_id. Cuando el cliente vuelva a llamar, abre wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} y envía de nuevo el mismo session.update. El historial caduca tras 30 minutos de inactividad.

Cumple la normativa. Informa a los llamantes de que están hablando con una IA y, si grabas las llamadas, dilo al principio. Para datos de salud, xAI indica que se puede firmar un BAA (Acuerdo de Socio Comercial) tras completar un cuestionario.

Mide tu latencia. El retraso que perciben los llamantes es la suma del de la red telefónica, el de tu puente (si tienes uno) y el de la generación de la respuesta. Mídelo de extremo a extremo en llamadas reales y mantén rápidas las funciones que el agente llama durante la conversación.

Puntos clave

  • Con SIP directo, xAI atiende tu número, te notifica con un webhook firmado realtime.call.incoming y tú te unes a la llamada mediante wss://api.x.ai/v1/realtime?call_id=…
  • refer transfiere la llamada (el resultado se devuelve en la respuesta HTTP) y hangup la finaliza
  • Las teclas DTMF llegan al modelo y se registran mediante input_audio_buffer.dtmf_event_received; la herramienta send_dtmf permite al agente pulsar teclas
  • En un puente a través de tu servidor, el uso nativo de G.711 (audio/pcmu, audio/pcma) evita la transcodificación
  • LiveKit Agents y Pipecat son las integraciones que lista xAI