Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Integrazione telefonica (Twilio, ecc.)

Lezione 15 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Integrazione telefonica (Twilio, ecc.)
  2. Architettura telefonica
  3. Implementazione con Twilio
  4. Alternative a Twilio
  5. Punti chiave

Aggiornato il 3 novembre 2026 in base alla documentazione della Realtime API: il formato G.711 μ-law è denominato audio/pcmu (il testo citava in precedenza g711_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-hd e gpt-4o-mini-tts smetteranno 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-realtime e 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-transcribe e /v1/audio/translations il 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:

1

Chiamata in arrivo → Twilio

L'utente compone un numero di telefono. Twilio riceve la chiamata e invia un webhook al tuo server.

2

Il tuo server → Flusso multimediale

Il tuo server risponde con istruzioni TwiML che aprono un WebSocket Media Stream bidirezionale.

3

Flusso multimediale ↔ Realtime API

Il tuo server inoltra l'audio tra il Twilio Media Stream e la Realtime API di OpenAI.

4

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