Integração Telefónica (Twilio, etc.)
Nesta página
Atualizado a 3 de novembro de 2026 com base na documentação da Realtime API: o formato G.711 μ-law denomina-se
audio/pcmu(o texto citava anteriormenteg711_ulaw, que era o nome da versão beta). Fonte: Realtime API.
Atualização de 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (a substituição indicada égpt-realtime-2.1-mini, que o guia TTS da OpenAI afirma não ser suportado por/v1/audio/speech: a migração da síntese de fala deve ocorrer através da Realtime API);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz em full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Integração Telefónica (Twilio, etc.)
Um agente de voz torna-se verdadeiramente útil quando está acessível por telefone. Plataformas de telefonia na nuvem como a Twilio, LiveKit e Daily permitem ligar a Realtime API à rede telefónica global. O utilizador marca um número e o seu agente atende em tempo real.
Arquitetura de Telefonia
A integração telefónica adiciona uma camada entre a rede telefónica e a Realtime API:
Chamada Recebida → Twilio
O utilizador marca um número de telefone. A Twilio recebe a chamada e envia um webhook para o seu servidor.
O Seu Servidor → Fluxo de Média
O seu servidor responde com instruções TwiML que abrem um WebSocket de Fluxo de Média bidirecional.
Fluxo de Média ↔ Realtime API
O seu servidor retransmite o áudio entre o Fluxo de Média da Twilio e a Realtime API da OpenAI.
Resposta de Voz → Utilizador
O áudio de resposta da Realtime API é enviado de volta via Twilio para o telefone do utilizador.
Implementação com a Twilio
Webhook de Chamada Recebida
Quando chega uma chamada, a Twilio envia um pedido HTTP para o seu servidor. Você responde com TwiML que abre um Fluxo de Média:
from fastapi import FastAPI, Request
from fastapi.responses import Response
app = FastAPI()
@app.post("/incoming-call")
async def incoming_call(request: Request):
"""Webhook da Twilio para chamadas recebidas."""
twiml = """<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say language="en-US">
Welcome to Corsen AI. Connecting you to your voice assistant.
</Say>
<Connect>
<Stream url="wss://your-server.com/media-stream">
<Parameter name="caller" value="{caller_number}" />
</Stream>
</Connect>
</Response>"""
form_data = await request.form()
caller = form_data.get("From", "unknown")
twiml = twiml.replace("{caller_number}", caller)
return Response(content=twiml, media_type="application/xml")
A Ponte entre o Fluxo de Média e a Realtime API
O servidor WebSocket recebe o áudio da Twilio e retransmite-o para a Realtime API:
from fastapi import WebSocket
import websockets
import json
import base64
import audioop
import asyncio
OPENAI_API_KEY = "sk-..."
REALTIME_URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
@app.websocket("/media-stream")
async def media_stream(twilio_ws: WebSocket):
"""Ponte entre o Fluxo de Média da Twilio e a Realtime API."""
await twilio_ws.accept()
# Ligar à Realtime API
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(REALTIME_URL, additional_headers=headers) as openai_ws:
await openai_ws.recv() # session.created
# Configurar a sessão
await openai_ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a phone assistant. "
"Respond in English, concisely.",
"audio": {
"input": {
"format": {"type": "audio/pcmu"},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 600
}
},
"output": {
"format": {"type": "audio/pcmu"},
"voice": "marin"
}
}
}
}))
await openai_ws.recv()
stream_sid = None
async def twilio_to_openai():
nonlocal stream_sid
async for message in twilio_ws.iter_text():
data = json.loads(message)
if data["event"] == "media":
audio_b64 = data["media"]["payload"]
await openai_ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": audio_b64
}))
elif data["event"] == "start":
stream_sid = data["start"]["streamSid"]
async def openai_to_twilio():
async for message in openai_ws:
event = json.loads(message)
if event["type"] == "response.output_audio.delta":
await twilio_ws.send_json({
"event": "media",
"streamSid": stream_sid,
"media": {
"payload": event["delta"]
}
})
await asyncio.gather(twilio_to_openai(), openai_to_twilio())
Formato de Áudio G.711
A telefonia utiliza o formato G.711 μ-law (8 kHz, um byte por amostra). A Realtime API suporta isto nativamente sob o nome audio/pcmu, que deve declarar tanto para entrada como para saída (audio.input.format e audio.output.format, como no código acima). Isto evita qualquer conversão no lado do servidor. O nome g711_ulaw pertencia à versão beta da API; o equivalente A-law denomina-se audio/pcma.
Alternativas à Twilio
| Plataforma | Ponto Forte | Integração com a Realtime API |
|---|---|---|
| Twilio | Ecossistema completo, números em mais de 100 países | Fluxos de Média WebSocket nativos |
| LiveKit | Código aberto, baixa latência, WebRTC | Plugin oficial da OpenAI |
| Daily | Simples, alojado, ideal para prototipagem | SDK Pipecat com conetor Realtime |
Pontos-chave
- Os Fluxos de Média da Twilio permitem ligar uma chamada telefónica a um WebSocket bidirecional
- O seu servidor atua como uma ponte entre o Fluxo de Média da Twilio e a Realtime API da OpenAI
- O formato G.711 μ-law é nativo da telefonia e suportado diretamente pela Realtime API
- A LiveKit (código aberto, WebRTC) e a Daily (alojada) são alternativas viáveis à Twilio
- A arquitetura é sempre a mesma: telefonia → o seu servidor → Realtime API