Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Integração Telefónica (Twilio, etc.)

Aula 15 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Integração Telefónica (Twilio, etc.)
  2. Arquitetura de Telefonia
  3. Implementação com a Twilio
  4. Alternativas à Twilio
  5. Pontos-chave

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 anteriormente g711_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-hd e gpt-4o-mini-tts deixarã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-realtime e 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-transcribe e /v1/audio/translations a 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:

1

Chamada Recebida → Twilio

O utilizador marca um número de telefone. A Twilio recebe a chamada e envia um webhook para o seu servidor.

2

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.

3

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.

4

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