For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal
Theme

Sugerencias

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Panel de la API
Prueba ChatGPT

Telefonía y SIP

Conecta llamadas telefónicas a OpenAI mediante SIP.

Elige la API para ver los pasos de conexión y los eventos de sesión correspondientes.

Conecta las llamadas telefónicas entrantes y salientes a GPT-Live mediante una troncal SIP. Tu proveedor intercambia el audio de las llamadas con OpenAI, mientras que tu backend gestiona la configuración de la sesión, los controles de llamada y la lógica de negocio. La señalización SIP usa TLS y GPT-Live requiere SRTP para el audio de las llamadas.

  • Gestionar una llamada entrante: recibe un webhook de llamada entrante y luego acepta o rechaza la llamada.
  • Hacer una llamada saliente: crea una sesión para marcar un número telefónico a través de tu proveedor. No necesitas un webhook de llamada entrante ni una solicitud de aceptación.

Usa una conexión de banda lateral cuando tu backend necesite recibir eventos de sesión o enviar comandos. Esta conexión se vincula a la conversación existente mientras SIP transporta el audio. Asigna un solo controlador a cada acción para evitar que las herramientas se ejecuten dos veces si se duplica la entrega de un webhook o si varias conexiones reciben el mismo evento.

Gestionar una llamada entrante

Dirige las llamadas telefónicas entrantes de tu proveedor SIP a tu proyecto de OpenAI. Tu backend recibe un webhook y decide si acepta cada llamada.

Configurar el número telefónico y la troncal

Usa un proveedor de troncales SIP, como Twilio, para conectar un número telefónico a GPT-Live. Después de comprarle un número a tu proveedor, sigue estos pasos:

  1. Abre tu proyecto en la configuración de OpenAI. En Webhooks, crea un punto de acceso de webhooks y suscríbelo al evento live.transport.incoming.
  2. Busca el ID de tu proyecto en General. Comienza con proj_. Usa el ID del proyecto al que pertenece el webhook.
  3. Dirige la troncal SIP de tu proveedor al URI SIP global, sip:$PROJECT_ID@sip.api.openai.com;transport=tls, o usa uno de estos puntos de acceso regionales:
    • Para la residencia de datos en Europa, usa sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls.
    • Para usar hosts SIP ubicados físicamente en la India, usa sip:$PROJECT_ID@sip-in.api.openai.com;transport=tls.

Antes de seguir estos pasos, confirma que tu proyecto tenga habilitada la compatibilidad con SIP de GPT-Live y que la troncal SIP de tu proveedor dirija las llamadas a ese proyecto.

Recibir la llamada entrante

Cuando OpenAI recibe una llamada para tu proyecto, envía un evento live.transport.incoming a tu punto de acceso de webhooks. Verifica la firma del webhook y descarta las entregas duplicadas. Luego, acepta o rechaza la llamada.

El webhook identifica la llamada SIP mediante data.type: "sip" y proporciona data.session_id. Usa ese ID de sesión sin modificarlo en todas las acciones de control de llamadas de Live. Trata data.sip_headers como metadatos no confiables de quien llama. No los uses para autorizar la llamada.

Este es un ejemplo del cuerpo del webhook:

{
  "object": "event",
  "id": "evt_abc123",
  "type": "live.transport.incoming",
  "created_at": 1750287018,
  "data": {
    "type": "sip",
    "session_id": "live_123",
    "sip_headers": [
      { "name": "From", "value": "sip:+14155550123@sip.example.com" },
      { "name": "To", "value": "sip:+18005550100@sip.example.com" },
      { "name": "Call-ID", "value": "call-123@example.com" }
    ]
  }
}

El campo created_at contiene una marca de tiempo Unix en segundos. Los encabezados de entrega incluyen webhook-id para identificar entregas duplicadas, webhook-timestamp para indicar cuándo se intentó la entrega y webhook-signature para verificar la firma. Consulta los ejemplos de verificación de webhooks para ver cómo implementar la verificación en los controladores del servidor.

Las integraciones existentes aún pueden recibir el evento obsoleto live.call.incoming, que no incluye data.type. Durante la migración, procesa ambos nombres de evento y conserva la suscripción anterior hasta que terminen todas las entregas y los reintentos pendientes de esa suscripción. La misma llamada pendiente también puede generar un webhook de Realtime. Asigna a un solo controlador la decisión de aceptar o rechazar la llamada para evitar aceptarla mediante ambas API.

Aceptar o rechazar la llamada

Aplica las reglas de autorización y enrutamiento de tu aplicación. Para aceptar la llamada, envía una solicitud autenticada POST /v1/live/sessions/{session_id}/accept con un objeto session en el nivel superior:

{
  "session": {
    "type": "live",
    "model": "gpt-live-1",
    "instructions": "You are answering an inbound support call.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

Usa Authorization: Bearer $OPENAI_API_KEY en las solicitudes de control de llamadas que envíes desde tu backend de confianza. Elige la voz y el modo de delegación al aceptar la llamada. SIP negocia el formato de audio, así que omite audio.format. El ejemplo selecciona la delegación al cliente, por lo que tu backend debe encargarse del trabajo delegado. Consulta Delegación y herramientas para ver las configuraciones del cliente y de Responses.

Si la llamada se acepta correctamente, la solicitud devuelve 200 OK con el cuerpo vacío después de que se inicializa la sesión. Gestiona los errores HTTP antes de dar la llamada por aceptada.

Para rechazar la llamada, envía POST /v1/live/sessions/{session_id}/reject con un código de estado SIP, como { "status_code": 486 } para indicar que la línea está ocupada. El código de estado debe ser un entero entre 300 y 699, ambos inclusive. Prevalece la primera decisión de aceptar o rechazar la llamada. Si después se intenta tomar otra decisión sobre la misma llamada, la solicitud devuelve decision_already_made.

Conectar tu backend

Después de aceptar la llamada, abre una conexión WebSocket de banda lateral en wss://api.openai.com/v1/live/sessions/{session_id}/attach. Usa el ID de la sesión aceptada, la misma autenticación del proyecto y los mismos encabezados de conexión. No vuelvas a enviar session.start.

SIP transporta el audio de la llamada. Usa la conexión de banda lateral para las transcripciones, la delegación, las herramientas, los comandos y el audio reflejado. Asigna un único responsable a cada efecto secundario, incluso si varias conexiones reciben el mismo evento.

Una vez establecida la conexión, usa los controles de la llamada activa para enviar tonos del teclado telefónico, transferir la llamada o colgar.

Hacer una llamada saliente

Llama a un número telefónico a través de tu proveedor SIP con Crear sesión. Tu proveedor gestiona la conexión con la red telefónica mientras GPT-Live mantiene la conversación.

Todas las organizaciones pueden hacer llamadas SIP salientes mediante la API de Live. El punto de acceso de la Realtime API para crear llamadas no admite esta función.

Configurar la troncal

Usa una troncal que admita señalización TLS y transmisión de medios con SDES-SRTP. Habilita SRTP en la configuración de tu proveedor antes de hacer una llamada.

Incluye la configuración de la troncal en cada solicitud:

Campo Valor
transport.destination El número telefónico al que quieres llamar, en formato E.164, por ejemplo, +14155550123. No se admiten URI SIP como destino.
transport.trunk.provider_url Un punto de acceso del proveedor, como sips:sip.example.com:5061. El puerto predeterminado es 5061. El parámetro ;transport=tcp es opcional.
transport.trunk.auth.type digest para la autenticación SIP Digest.
transport.trunk.auth.username Tu nombre de usuario SIP asignado por el proveedor.
transport.trunk.auth.password Tu contraseña SIP del proveedor.
transport.trunk.caller_number El número telefónico de origen que se envía a tu proveedor, en formato E.164.

El punto de acceso del proveedor debe usar sips: para la señalización TLS. No incluyas credenciales, rutas, encabezados de URI ni otros parámetros de URI en la URL. Se rechazan los nombres de host locales y las direcciones IP privadas o locales escritas de forma literal. Guarda tu clave de API de OpenAI y tus credenciales SIP en tu servidor.

Crear la sesión

Envía POST /v1/live/sessions con la configuración de tu sesión y transport.type: "sip". Elige la voz y el modo de delegación al crear la sesión. Omite audio.format porque SIP negocia el formato de audio.

Este ejemplo usa curl y jq. Define OPENAI_API_KEY, SIP_USERNAME y SIP_PASSWORD en el entorno de tu servidor y sustituye el punto de acceso del proveedor y los números telefónicos del ejemplo por tus propios valores. El ejemplo selecciona la delegación al cliente, por lo que tu backend debe encargarse del trabajo delegado.

jq -n \
  --arg username "$SIP_USERNAME" \
  --arg password "$SIP_PASSWORD" \
  '{
    "session": {
      "model": "gpt-live-1",
      "instructions": "Help the user schedule an appointment.",
      "audio": { "output": { "voice": "marin" } },
      "delegation": { "type": "client" }
    },
    "transport": {
      "type": "sip",
      "destination": "+14155550123",
      "trunk": {
        "provider_url": "sips:sip.example.com:5061",
        "auth": {
          "type": "digest",
          "username": $username,
          "password": $password
        },
        "caller_number": "+14155550100"
      }
    }
  }' | curl https://api.openai.com/v1/live/sessions \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-

La solicitud devuelve 200 OK una vez que se inicializa la sesión:

{
  "session": { "id": "live_123" },
  "transport": { "type": "sip" }
}

Esta respuesta no indica que alguien haya contestado la llamada. No contiene SDP ni credenciales de la troncal. Conserva session.id sin modificarlo para la conexión de banda lateral y los controles de llamada. Para una llamada saliente no necesitas un webhook de llamadas entrantes ni una solicitud de aceptación.

Monitorear y finalizar la llamada

Conecta tu backend a wss://api.openai.com/v1/live/sessions/{session_id}/attach con tu clave de API de OpenAI. No vuelvas a enviar session.start. La conexión de banda lateral transmite los eventos de la conversación, el trabajo delegado y las actualizaciones sobre el progreso de la llamada mientras SIP transporta el audio.

Evento Significado
transport.ringing El proveedor indica que el teléfono está sonando o que ya se transmiten medios antes de que se conteste la llamada.
transport.answered Se contestó la llamada y se estableció la transmisión de medios.
transport.failed No se pudo establecer la llamada después de inicializar la sesión. Revisa error.code y error.message.

Cada evento de progreso de la llamada incluye event_id y session_id. Conecta tu backend en cuanto se cree la sesión. La conexión de banda lateral solo retransmite los eventos de los últimos 3 segundos, por lo que, si te conectas más tarde, puedes perder eventos anteriores de la llamada. Los eventos retransmitidos conservan sus ID originales. Usa event_id para descartar eventos duplicados.

Una vez establecida la conexión, usa los controles de la llamada activa para enviar tonos del teclado telefónico, transferir la llamada o colgar. Mantén abierta la conexión de banda lateral para recibir session.closed y los datos finales de uso, tal como se describe en Uso y cierre ordenado.

Gestionar límites y errores

El teléfono puede sonar hasta 3 minutos y, una vez conectada, la llamada puede durar hasta 2 horas. Estos límites no se pueden configurar en la solicitud de creación.

Si la configuración de la sesión no es válida, el error se devuelve en la respuesta a la solicitud de creación. Si falla el establecimiento del transporte, la solicitud puede devolver 502. Si se agota el tiempo de espera de inicialización, devuelve 504. Una vez creada la sesión, monitorea transport.failed para detectar fallas asíncronas al establecer la llamada.

Gestionar una llamada activa

Estos controles se aplican tanto a las llamadas SIP entrantes como a las salientes.

Enviar y recibir eventos del teclado telefónico

La conexión de banda lateral recibe transport.dtmf.received cuando quien llama presiona una tecla. Para enviar un tono DTMF a la troncal SIP, envía un evento de cliente transport.dtmf.send mediante el WebSocket de banda lateral. Una vez que el tono se envía correctamente, la conexión de banda lateral recibe transport.dtmf.sent.

Si proporcionas un event_id, la notificación lo incluye como client_event_id. Si ocurre un error, se devuelve un evento error con error.client_event_id.

Transferir o finalizar la llamada

Para transferir la llamada, envía POST /v1/live/sessions/{session_id}/refer con { "target_uri": "sip:agent@example.com" } para indicar el destino. Para colgar, envía POST /v1/live/sessions/{session_id}/hangup sin cuerpo en la solicitud. Ambas solicitudes devuelven 200 OK con el cuerpo vacío si se completan correctamente.

El destino de la transferencia se usa como valor del encabezado SIP Refer-To. Puede ser un URI telefónico, como tel:+14155550123, o un URI SIP, como sip:agent@example.com. Tu proveedor se encarga del resto de la transferencia.

Mantén abierta la conexión de banda lateral hasta que session.closed proporcione los datos finales de uso. Consulta Uso y cierre ordenado para saber cómo se informa el uso y conocer los motivos de cierre.

Requisitos de red para SIP

Las llamadas SIP de GPT-Live usan rutas de red distintas para la señalización y los medios. Configura tu red para permitir ambos tipos de tráfico:

  • Señalización SIP: sip.api.openai.com y sip-eu.api.openai.com son puntos de acceso con enrutamiento basado en GeoIP. El punto de acceso de la India, sip-in.api.openai.com, dirige el tráfico a hosts SIP ubicados en ese país. Permite el tráfico TCP/TLS saliente hacia el puerto 5061 de las direcciones que devuelve el DNS para el punto de acceso que elegiste.
  • Medios SRTP: en el SDP negociado, la API especifica una dirección IP independiente para los medios y un puerto UDP. Permite el tráfico SRTP por UDP en ambas direcciones entre tu red y los siguientes bloques CIDR:
    • 13.79.45.80/28
    • 20.204.17.112/28
    • 23.98.140.64/28
    • 40.67.149.176/28
    • 40.83.204.240/28

Próximos pasos con GPT-Live