Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Integrace telefonie (Twilio atd.)

Lekce 15 z 18 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Integrace telefonie (Twilio atd.)
  2. Architektura telefonie
  3. Implementace s Twilio
  4. Alternativy k Twilio
  5. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě dokumentace Realtime API: formát G.711 μ-law se nazývá audio/pcmu (dříve uváděný název g711_ulaw byl pouze beta označení). Zdroj: Realtime API.

Aktualizace z 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých: tts-1, tts-1-hd a gpt-4o-mini-tts přestanou fungovat 6. ledna 2027 (uvedenou náhradou je gpt-realtime-2.1-mini, který však podle průvodce OpenAI TTS nepodporuje /v1/audio/speech: migrace syntézy řeči musí proběhnout přes Realtime API); modely gpt-realtime, gpt-4o-realtime a starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations skončí 26. února 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pro plně duplexní hlas je GPT-Live 1 dostupné v API od 10. září 2026.

Integrace telefonie (Twilio atd.)

Hlasový agent je skutečně užitečný až tehdy, když je dostupný po telefonu. Cloudové telefonní platformy jako Twilio, LiveKit a Daily ti umožňují propojit Realtime API s globální telefonní sítí. Uživatel vytočí číslo a tvůj agent odpoví v reálném čase.

Architektura telefonie

Integrace telefonie přidává vrstvu mezi telefonní síť a Realtime API:

1

Příchozí hovor → Twilio

Uživatel vytočí telefonní číslo. Twilio hovor přijme a odešle webhook na tvůj server.

2

Tvůj server → Datový proud médií

Tvůj server odpoví instrukcemi TwiML, které otevřou obousměrný WebSocket pro datový proud médií (Media Stream).

3

Datový proud médií ↔ Realtime API

Tvůj server přeposílá zvuk mezi datovým proudem Twilio Media Stream a OpenAI Realtime API.

4

Hlasová odpověď → Uživatel

Zvuková odpověď z Realtime API je odeslána zpět přes Twilio na uživatelův telefon.

Implementace s Twilio

Webhook pro příchozí hovory

Když dorazí hovor, Twilio odešle na tvůj server požadavek HTTP. Ty odpovíš pomocí TwiML, které otevře datový proud médií (Media Stream):

from fastapi import FastAPI, Request
from fastapi.responses import Response

app = FastAPI()

@app.post("/incoming-call")
async def incoming_call(request: Request):
    """Twilio webhook for incoming calls."""
    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")

Most mezi datovým proudem médií a Realtime API

WebSocket server přijímá zvuk od Twilia a přeposílá jej do 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):
    """Bridge between Twilio Media Stream and the Realtime API."""
    await twilio_ws.accept()

    # Connect to the 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

        # Configure the session
        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())

Zvukový formát G.711

Telefonie využívá formát G.711 μ-law (8 kHz, jeden bajt na vzorek). Realtime API tento formát podporuje nativně pod názvem audio/pcmu, který deklaruješ jak pro vstup, tak pro výstup (audio.input.format a audio.output.format, jak je uvedeno v kódu výše). Tím se vyhneš jakékoli konverzi na straně serveru. Název g711_ulaw patřil beta verzi API; ekvivalent A-law se nazývá audio/pcma.

Alternativy k Twilio

Platforma Silná stránka Integrace s Realtime API
Twilio Kompletní ekosystém, čísla ve více než 100 zemích Nativní WebSocket Media Streams
LiveKit Open source, nízká latence, WebRTC Oficiální plugin OpenAI
Daily Jednoduché, hostované, vhodné pro prototypování Pipecat SDK s konektorem Realtime

Klíčové poznatky

  • Twilio Media Streams ti umožňují propojit telefonní hovor s obousměrným WebSocketem
  • Tvůj server funguje jako most mezi datovým proudem Twilio Media Stream a OpenAI Realtime API
  • Formát G.711 μ-law je pro telefonii nativní a Realtime API jej přímo podporuje
  • LiveKit (open source, WebRTC) a Daily (hostované) jsou životaschopné alternativy k Twilio
  • Architektura je vždy stejná: telefonie → tvůj server → Realtime API