For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal
Theme

Sugestões

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Painel da API
Experimente o ChatGPT

Telefonia e SIP

Conecte chamadas telefônicas à OpenAI via SIP.

Escolha a API para ver como estabelecer a conexão e quais eventos a sessão emite.

Conecte chamadas telefônicas de entrada e de saída ao GPT-Live por um tronco SIP. O provedor troca o áudio da chamada com a OpenAI, enquanto seu backend configura a sessão, controla a chamada e executa a lógica de negócio. A sinalização SIP usa TLS, e o GPT-Live exige SRTP para o áudio da chamada.

  • Processar uma chamada recebida: receba o webhook de chamada recebida e, em seguida, aceite ou rejeite a chamada.
  • Fazer uma chamada de saída: crie uma sessão para discar um número de telefone pelo seu provedor. Chamadas de saída dispensam o webhook de chamada recebida e a requisição para aceitar a chamada.

Use uma conexão auxiliar quando o backend precisar receber eventos da sessão ou enviar comandos. Essa conexão se vincula à conversa em andamento enquanto o SIP transporta o áudio. Atribua um único manipulador a cada ação para evitar que entregas duplicadas de webhooks ou eventos observados em mais de uma conexão acionem a mesma ferramenta duas vezes.

Processar uma chamada recebida

Encaminhe as chamadas recebidas pelo provedor SIP para seu projeto da OpenAI. O backend recebe um webhook e decide se aceita cada chamada.

Configurar o número de telefone e o tronco SIP

Use um provedor de tronco SIP, como a Twilio, para conectar um número de telefone ao GPT-Live. Depois de adquirir um número com o provedor, siga estas etapas:

  1. Abra seu projeto nas configurações da OpenAI. Em Webhooks, crie um endpoint de webhook e configure-o para receber o evento live.transport.incoming.
  2. Em Geral, localize o ID do projeto. Ele começa com proj_. Use o projeto ao qual o webhook pertence.
  3. Direcione o tronco SIP do provedor para a URI SIP global sip:$PROJECT_ID@sip.api.openai.com;transport=tls ou use um dos seguintes endpoints regionais:
    • Para residência de dados na Europa, use sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls.
    • Para hosts SIP localizados fisicamente na Índia, use sip:$PROJECT_ID@sip-in.api.openai.com;transport=tls.

Antes de usar este fluxo, confirme que o suporte a SIP do GPT-Live está habilitado no seu projeto e que o tronco SIP do provedor encaminha as chamadas para esse projeto.

Receber a chamada

Quando a OpenAI recebe uma chamada para seu projeto, ela envia um evento live.transport.incoming ao seu endpoint de webhook. Verifique a assinatura do webhook e elimine entregas duplicadas. Em seguida, aceite ou rejeite a chamada.

O webhook identifica uma chamada SIP com data.type: "sip" e fornece data.session_id. Use esse ID de sessão sem alterações em todas as ações de controle da chamada na API Live. Trate data.sip_headers como metadados não confiáveis fornecidos por quem liga. Não os use para autorizar a chamada.

Veja um exemplo do corpo do 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" }
    ]
  }
}

O campo created_at contém um timestamp Unix em segundos. Os cabeçalhos de entrega incluem webhook-id para identificar entregas duplicadas, webhook-timestamp para indicar o horário da tentativa de entrega e webhook-signature para verificar a assinatura. Consulte os exemplos de verificação de webhooks para implementar essa verificação nos manipuladores do servidor.

Integrações existentes ainda podem receber o evento obsoleto live.call.incoming, que não inclui data.type. Durante a migração, processe eventos com ambos os nomes e mantenha a assinatura antiga até que todas as entregas e novas tentativas do fluxo anterior tenham terminado. A mesma chamada pendente também pode gerar um webhook da Realtime API. Atribua a um único manipulador a decisão de aceitar ou rejeitar a chamada para evitar que as duas APIs a aceitem.

Aceitar ou rejeitar a chamada

Aplique as regras de autorização e roteamento do seu aplicativo. Para aceitar a chamada, envie uma requisição autenticada POST /v1/live/sessions/{session_id}/accept com um objeto session no nível superior:

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

Envie as requisições de controle da chamada a partir do seu backend confiável usando Authorization: Bearer $OPENAI_API_KEY. Escolha a voz e o modo de delegação ao aceitar a chamada. O SIP negocia o formato de áudio, portanto omita audio.format. O exemplo seleciona a delegação ao cliente, o que exige que seu backend execute as tarefas delegadas. Consulte Delegação e ferramentas para ver as configurações de delegação ao cliente e à API Responses.

Quando a chamada é aceita, a API retorna 200 OK com o corpo vazio após inicializar a sessão. Trate os erros HTTP antes de considerar a chamada aceita.

Para rejeitar a chamada, envie POST /v1/live/sessions/{session_id}/reject com um código de status SIP, como { "status_code": 486 } para indicar que a linha está ocupada. O código deve ser um número inteiro entre 300 e 699, inclusive. A primeira decisão de aceitar ou rejeitar prevalece. Qualquer tentativa posterior de decidir sobre a mesma chamada retorna decision_already_made.

Conectar o backend à sessão

Depois de aceitar a chamada, abra um WebSocket auxiliar em wss://api.openai.com/v1/live/sessions/{session_id}/attach. Use o ID da sessão aceita, a mesma autenticação do projeto e os mesmos cabeçalhos de conexão. Não envie session.start novamente.

O SIP transporta o áudio da chamada. Use a conexão auxiliar para transcrições, delegação, ferramentas, comandos e áudio espelhado. Defina um único responsável por cada efeito colateral, mesmo que várias conexões recebam o mesmo evento.

Depois de estabelecer a conexão, use os controles da chamada ativa para enviar tons do teclado telefônico, transferir a chamada ou desligar.

Fazer uma chamada de saída

Ligue para um número de telefone pelo seu provedor SIP usando a operação Criar sessão. O provedor estabelece a conexão com a rede telefônica enquanto o GPT-Live conduz a conversa.

Todas as organizações podem fazer chamadas SIP de saída pela API Live. O endpoint de criação de chamadas da Realtime API não oferece esse recurso.

Configurar o tronco SIP

Use um tronco que aceite sinalização TLS e mídia SDES-SRTP. Habilite o SRTP nas configurações do provedor antes de fazer uma chamada.

Inclua a configuração do tronco em cada requisição:

Campo Valor
transport.destination Número de telefone de destino no formato E.164, como +14155550123. Não há suporte a destinos especificados por URI SIP.
transport.trunk.provider_url Endpoint do provedor, como sips:sip.example.com:5061. A porta padrão é 5061, e ;transport=tcp é opcional.
transport.trunk.auth.type digest para autenticação SIP Digest.
transport.trunk.auth.username Nome de usuário SIP fornecido pelo provedor.
transport.trunk.auth.password Senha SIP fornecida pelo provedor.
transport.trunk.caller_number Número de telefone de origem a ser enviado ao provedor, no formato E.164.

O endpoint do provedor deve usar sips: para a sinalização TLS. Não inclua credenciais, caminhos, cabeçalhos de URI nem outros parâmetros de URI na URL. A API rejeita nomes de host locais e endereços IP privados ou locais fornecidos diretamente. Mantenha a chave de API da OpenAI e as credenciais SIP no servidor.

Criar a sessão

Envie POST /v1/live/sessions com a configuração da sessão e transport.type: "sip". Escolha a voz e o modo de delegação ao criar a sessão. Omita audio.format, pois o SIP negocia o formato de áudio.

Este exemplo usa curl e jq. Defina OPENAI_API_KEY, SIP_USERNAME e SIP_PASSWORD no ambiente do servidor e substitua o endpoint do provedor e os números de telefone do exemplo pelos seus. O exemplo seleciona a delegação ao cliente, o que exige que seu backend execute as tarefas delegadas.

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 @-

A API retorna 200 OK após inicializar a sessão:

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

Essa resposta não indica que alguém atendeu à chamada. Ela não contém SDP nem credenciais do tronco. Use session.id sem alterações na conexão auxiliar e nas operações de controle da chamada. Chamadas de saída dispensam o webhook de chamada recebida e a requisição para aceitar a chamada.

Monitorar e encerrar a chamada

Conecte o backend a wss://api.openai.com/v1/live/sessions/{session_id}/attach usando sua chave de API da OpenAI. Não envie session.start novamente. A conexão auxiliar transmite eventos da conversa, tarefas delegadas e informações sobre o andamento da chamada enquanto o SIP transporta o áudio.

Evento Significado
transport.ringing O provedor informa que o telefone está tocando ou que há mídia antes do atendimento.
transport.answered A chamada foi atendida e o fluxo de mídia foi estabelecido.
transport.failed Falha ao estabelecer a chamada após a inicialização da sessão. Verifique error.code e error.message.

Cada evento de andamento da chamada inclui event_id e session_id. Abra a conexão auxiliar imediatamente após criar a sessão. Ela só retransmite eventos dos 3 segundos anteriores. Se você se conectar mais tarde, poderá perder os primeiros eventos da chamada. Os eventos retransmitidos mantêm os IDs originais. Use event_id para eliminar duplicatas.

Depois de estabelecer a conexão, use os controles da chamada ativa para enviar tons do teclado telefônico, transferir a chamada ou desligar. Mantenha a conexão auxiliar aberta para receber session.closed e os dados finais de uso, conforme descrito em Uso e encerramento ordenado.

Lidar com limites e erros

O telefone pode tocar por até 3 minutos, e a chamada pode durar até 2 horas após a conexão. A requisição de criação não permite configurar esses limites.

Se a configuração da sessão for inválida, a API informará o erro na resposta à requisição de criação. Falhas ao configurar o transporte podem retornar 502. Se a inicialização exceder o tempo limite, a API retornará 504. Após criar a sessão, monitore transport.failed para detectar falhas assíncronas ao estabelecer a chamada.

Gerenciar uma chamada ativa

Esses controles se aplicam tanto às chamadas SIP de entrada quanto às de saída.

Enviar e receber eventos do teclado telefônico

A conexão auxiliar recebe transport.dtmf.received quando quem liga pressiona uma tecla. Para enviar um tom DTMF ao tronco SIP, envie um evento de cliente transport.dtmf.send pelo WebSocket auxiliar. Após o envio bem-sucedido do tom, a conexão auxiliar recebe transport.dtmf.sent.

Se você fornecer um event_id, a notificação incluirá esse valor como client_event_id. Em caso de falha, a API retornará um evento error com error.client_event_id.

Transferir ou encerrar a chamada

Para transferir a chamada, envie POST /v1/live/sessions/{session_id}/refer com { "target_uri": "sip:agent@example.com" }, especificando o destino desejado. Para desligar, envie POST /v1/live/sessions/{session_id}/hangup sem corpo na requisição. Em caso de sucesso, ambas as operações retornam 200 OK com o corpo vazio.

O destino da transferência é o valor do cabeçalho SIP Refer-To. Ele pode ser uma URI de telefone, como tel:+14155550123, ou uma URI SIP, como sip:agent@example.com. O provedor cuida das etapas restantes da transferência.

Mantenha a conexão auxiliar aberta até que session.closed forneça os dados finais de uso. Consulte Uso e encerramento ordenado para saber como a API informa o uso e os motivos de encerramento.

Requisitos de rede para SIP

As chamadas SIP do GPT-Live usam caminhos de rede separados para sinalização e mídia. Configure a rede para permitir os dois tipos de tráfego:

  • Sinalização SIP: sip.api.openai.com e sip-eu.api.openai.com são endpoints com roteamento por GeoIP. O endpoint da Índia, sip-in.api.openai.com, encaminha o tráfego para hosts SIP na Índia. Permita tráfego TCP/TLS de saída na porta 5061 para os endereços que o DNS retornar para o endpoint escolhido.
  • Mídia SRTP: No SDP negociado, a API especifica um endereço IP separado para mídia e uma porta UDP. Permita tráfego SRTP via UDP nos dois sentidos entre sua rede e os seguintes blocos 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 passos com o GPT-Live