Integrazione telefonica (Twilio, ecc.)
In questa pagina
Aggiornato il 3 novembre 2026 in base alla documentazione della Realtime API: il formato G.711 μ-law è denominato
audio/pcmu(il testo citava in precedenzag711_ulaw, che era il nome della versione beta). Fonte: Realtime API.
Aggiornamento del 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno di funzionare il 6 gennaio 2027 (il sostituto indicato ègpt-realtime-2.1-mini, che la guida TTS di OpenAI specifica non essere supportato da/v1/audio/speech: la migrazione della sintesi vocale deve avvenire tramite la Realtime API);gpt-realtime,gpt-4o-realtimee i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsil 26 febbraio 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.
Integrazione telefonica (Twilio, ecc.)
Un agente vocale diventa davvero utile quando è accessibile tramite telefono. Piattaforme di telefonia cloud come Twilio, LiveKit e Daily ti permettono di collegare la Realtime API alla rete telefonica globale. Un utente compone un numero e il tuo agente risponde in tempo reale.
Architettura telefonica
L’integrazione telefonica aggiunge un livello tra la rete telefonica e la Realtime API:
Chiamata in arrivo → Twilio
L'utente compone un numero di telefono. Twilio riceve la chiamata e invia un webhook al tuo server.
Il tuo server → Flusso multimediale
Il tuo server risponde con istruzioni TwiML che aprono un WebSocket Media Stream bidirezionale.
Flusso multimediale ↔ Realtime API
Il tuo server inoltra l'audio tra il Twilio Media Stream e la Realtime API di OpenAI.
Risposta vocale → Utente
L'audio di risposta dalla Realtime API viene inviato nuovamente tramite Twilio al telefono dell'utente.
Implementazione con Twilio
Webhook per chiamate in arrivo
Quando arriva una chiamata, Twilio invia una richiesta HTTP al tuo server. Tu rispondi con del TwiML che apre un Media Stream:
from fastapi import FastAPI, Request
from fastapi.responses import Response
app = FastAPI()
@app.post("/incoming-call")
async def incoming_call(request: Request):
"""Webhook Twilio per le chiamate in arrivo."""
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")
Il ponte Flusso multimediale ↔ Realtime API
Il server WebSocket riceve l’audio da Twilio e lo inoltra alla 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 tra Twilio Media Stream e la Realtime API."""
await twilio_ws.accept()
# Connessione alla 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
# Configurazione della sessione
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 audio G.711
La telefonia utilizza il formato G.711 μ-law (8 kHz, un byte per campione). La Realtime API lo supporta nativamente con il nome audio/pcmu, che devi dichiarare sia per l’input che per l’output (audio.input.format e audio.output.format, come nel codice sopra). Questo evita qualsiasi conversione lato server. Il nome g711_ulaw apparteneva alla beta delle API; l’equivalente A-law è denominato audio/pcma.
Alternative a Twilio
| Piattaforma | Punto di forza | Integrazione Realtime API |
|---|---|---|
| Twilio | Ecosistema completo, numeri in oltre 100 paesi | Media Stream WebSocket nativi |
| LiveKit | Open source, bassa latenza, WebRTC | Plugin ufficiale OpenAI |
| Daily | Semplice, ospitato, ideale per il prototyping | SDK Pipecat con connettore Realtime |
Punti chiave
- Twilio Media Streams ti permette di collegare una telefonata a un WebSocket bidirezionale
- Il tuo server funge da ponte tra il Twilio Media Stream e la Realtime API di OpenAI
- Il formato G.711 μ-law è nativo della telefonia e supportato direttamente dalla Realtime API
- LiveKit (open source, WebRTC) e Daily (ospitato) sono alternative valide a Twilio
- L’architettura è sempre la stessa: telefonia → tuo server → Realtime API