---
title: "Use o ThunderPhone com clientes OpenAI Realtime"
description: "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:

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

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

```http
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

| Modo | Conectar com | Fonte da configuração |
| --- | --- | --- |
| Agente salvo | `?agent_id=12` | Prompt, voz, produto, idiomas, conhecimento e ferramentas compatíveis executadas no servidor implantados |
| Inline | Sem `agent_id` | O primeiro `session.update` aceito do seu cliente |

### Agente salvo

Conecte-se com o ID do agente implantado:

```text
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`:

```json
{
  "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](/api-reference/realtime#minimal-python-client) para transmitir áudio.

```python
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](/api-reference/realtime#minimal-python-client)
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](/pt/guides/review-calls).

A [referência do WebSocket Realtime](/api-reference/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](/api-reference/realtime#live-transcripts)
para saber a tarifa e [Preços](/pt/guides/pricing) 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](/pt/guides/use-with-pipecat)
e [Use o ThunderPhone com o LiveKit Agents](/pt/guides/use-with-livekit).