Use o ThunderPhone com clientes OpenAI Realtime

Direcione um cliente de servidor compatível com OpenAI Realtime para o ThunderPhone usando um agente salvo ou uma configuração de sessão em linha.

ThunderPhone implementa um subconjunto específico do modelo de eventos OpenAI Realtime. Um cliente existente do lado do servidor pode manter seu fluxo de eventos de WebSocket, áudio, sessão e resposta ao usar um agente de voz ThunderPhone.

Antes de conectar#

Você precisa de uma chave secreta de API da organização ThunderPhone e de um ambiente de execução no servidor que possa abrir WebSockets. Não conecte a partir de código do navegador nem exponha a chave a um navegador. Para usar um agente salvo, primeiro faça a implantação e copie seu ID numérico de agente.

Conecte-se a:

wss://api.thunderphone.com/v1/realtime

Autentique a atualização do WebSocket a partir do seu servidor:

Authorization: Bearer sk_live_YOUR_API_KEY

A autenticação por string de consulta existe para clientes que não conseguem definir cabeçalhos de handshake, mas URLs são mais fáceis de vazar em logs.

Escolha quem controla a configuração#

Agente salvo#

Conecte-se com o ID do agente implantado:

wss://api.thunderphone.com/v1/realtime?agent_id=12

O agente inicia enquanto o socket se conecta. Sua saudação permanece disponível, mas o Realtime desativa suas verificações faladas durante o silêncio e omite transfer_call e send_keypad_input. Outras ferramentas compatíveis são executadas no ThunderPhone. Não envie instruções inline nem ferramentas executadas pelo cliente para este modo.

Defina o áudio da conexão antes de o agente iniciar com os parâmetros de consulta input_audio_format, output_audio_format, input_rate e output_rate. Você não pode alterar a configuração salva nem os formatos de áudio após a conexão.

Sessão inline#

Sem agent_id, aguarde session.created e envie session.update:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}

A primeira atualização aceita provisiona a chamada. session.updated significa que a sessão está ativa. Instruções, voz, produto, ferramentas e formatos de áudio não podem ser alterados após esse ponto.

Sessões inline não têm saudação automática nem verificações faladas durante o silêncio. Para fazer o agente falar primeiro, anexe uma mensagem de sistema ou de usuário e envie response.create. Uma sessão completamente inativa ainda termina no limite de chamadas silenciosas da plataforma, 600 segundos por padrão.

Use o SDK oficial da OpenAI#

Forneça uma URL base de WebSocket terminando em /v1; o SDK adiciona /realtime. O valor de model é um nome de compatibilidade e não seleciona o produto do ThunderPhone. Escolha o produto na configuração da sessão ou no agente salvo.

Esta verificação de conexão cria uma sessão Bolt inline, imprime eventos até o primeiro session.updated e encerra. Use o cliente Python mínimo para transmitir áudio.

import asyncio
import os
 
from openai import AsyncOpenAI
 
 
async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )
 
    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break
 
 
if __name__ == "__main__":
    asyncio.run(main())

Mantenha seu tratamento existente para anexar áudio de entrada, deltas de áudio de resposta, interrupções, chamadas de função, erros e encerramento limpo do socket. Funções personalizadas inline são executadas no seu cliente; retorne os resultados delas pelo protocolo Realtime. Ferramentas de agentes salvos são executadas no ThunderPhone.

Ciclo de vida da sessão e falhas#

Um WebSocket representa uma chamada. Um ID de agente inválido ou uma configuração inline rejeitada gera um evento error. Aguarde por session.updated antes de considerar a sessão ativa. Declare os formatos e as taxas de amostragem reais de entrada e saída: uma incompatibilidade na taxa de PCM reproduz o áudio rápido demais ou lento demais, em vez de gerar um erro de validação.

Após o início da sessão, encerre o socket corretamente quando sua aplicação terminar. Sessões inline podem usar funções executadas pelo cliente. Sessões de agentes salvos usam ferramentas compatíveis executadas pelo ThunderPhone e não oferecem transferência nem entrada por teclado.

Teste a integração#

Comece com o cliente WAV Python mínimo e um WAV PCM16 mono na taxa declarada. Verifique:

1. O servidor aceita a configuração e envia session.updated.
2. A entrada gera eventos de transcrição e de áudio de resposta na velocidade esperada.
3. A interrupção e o cancelamento da resposta interrompem o áudio de saída restante.
4. Os resultados de funções inline ou de ferramentas de agentes salvos retornam ao modelo.
5. Uma entrada inválida gera um evento error tratado pelo seu cliente.
6. Seu cliente encerra o socket e a chamada aparece no Histórico de chamadas.

A referência do WebSocket Realtime lista os eventos aceitos, formatos de áudio, campos de sessão e exemplos completos.

Custo#

Chamadas Realtime usam a tarifa normal por minuto do produto selecionado. Ativar deltas de transcrição ao vivo adiciona uma cobrança por minuto durante toda a sessão; consulte Transcrições ao vivo para saber a tarifa e Preços para as tarifas dos produtos.

POST /v1/realtime/sessions é um caminho LiveKit gerenciado separado. Ele cria uma sala e um token de participante com escopo; não é necessário para uma conexão WebSocket direta.

Para integrações com frameworks, consulte Use o ThunderPhone com o Pipecat e Use o ThunderPhone com o LiveKit Agents.