Przejdź do głównej treści
Polski— Wybierz język
Menu

Integracja telefoniczna (Twilio i inne)

Lekcja 15 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Integracja telefoniczna (Twilio i inne)
  2. Architektura rozwiązania telefonicznego
  3. Implementacja z użyciem Twilio
  4. Alternatywy dla Twilio
  5. Kluczowe wnioski

Aktualizacja z 3 listopada 2026 r. na podstawie dokumentacji Realtime API: format G.711 μ-law nosi nazwę audio/pcmu (wcześniej cytowany tekst podawał g711_ulaw, co było nazwą z fazy beta). Źródło: Realtime API.

Aktualizacja z 2 listopada 2026 r. — Modele audio. Kilka modeli omawianych w tym kursie zostało wycofanych: tts-1, tts-1-hd oraz gpt-4o-mini-tts przestaną działać 6 stycznia 2027 r. (zalecanym zamiennikiem jest gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez /v1/audio/speech: migracja syntezy mowy musi odbywać się przez Realtime API); modele gpt-realtime, gpt-4o-realtime oraz starsze modele audio przestaną działać 20 stycznia 2027 r. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); modele whisper-1, gpt-4o-transcribe oraz endpoint /v1/audio/translations przestaną działać 26 lutego 2027 r. (zamienniki: gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). W przypadku komunikacji pełnodupleksowej (full-duplex), GPT-Live 1 jest dostępny w API od 10 września 2026 r.

Integracja telefoniczna (Twilio i inne)

Agent głosowy staje się naprawdę użyteczny, gdy można się z nim połączyć telefonicznie. Platformy telekomunikacyjne w chmurze, takie jak Twilio, LiveKit i Daily, pozwalają podłączyć Realtime API do globalnej sieci telefonicznej. Użytkownik wybiera numer, a Twój agent odpowiada w czasie rzeczywistym.

Architektura rozwiązania telefonicznego

Integracja telefoniczna dodaje warstwę pośredniczącą między siecią telefoniczną a Realtime API:

1

Połączenie przychodzące → Twilio

Użytkownik wybiera numer telefonu. Twilio odbiera połączenie i wysyła żądanie webhook do Twojego serwera.

2

Twój serwer → Strumień multimediów

Twój serwer odpowiada instrukcjami TwiML, które otwierają dwukierunkowe połączenie WebSocket Media Stream.

3

Strumień multimediów ↔ Realtime API

Twój serwer przekazuje dźwięk między strumieniem Twilio Media Stream a OpenAI Realtime API.

4

Odpowiedź głosowa → Użytkownik

Dźwięk odpowiedzi z Realtime API jest odsyłany przez Twilio na telefon użytkownika.

Implementacja z użyciem Twilio

Webhook dla połączeń przychodzących

Gdy nadchodzi połączenie, Twilio wysyła żądanie HTTP do Twojego serwera. Odpowiadasz kodem TwiML, który otwiera strumień multimediów (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 dla połączeń przychodzących."""
    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 między strumieniem multimediów a Realtime API

Serwer WebSocket odbiera dźwięk od Twilio i przekazuje go 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):
    """Most między Twilio Media Stream a Realtime API."""
    await twilio_ws.accept()

    # Połączenie z 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

        # Konfiguracja sesji
        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())

Format audio G.711

Telefonia wykorzystuje format G.711 μ-law (8 kHz, jeden bajt na próbkę). Realtime API obsługuje go natywnie pod nazwą audio/pcmu, którą deklarujesz zarówno dla wejścia, jak i wyjścia (audio.input.format oraz audio.output.format, jak w powyższym kodzie). Eliminuje to konieczność jakiejkolwiek konwersji po stronie serwera. Nazwa g711_ulaw należała do wersji beta API; odpowiednik A-law nosi nazwę audio/pcma.

Alternatywy dla Twilio

Platforma Mocna strona Integracja z Realtime API
Twilio Kompletny ekosystem, numery w ponad 100 krajach Natywne strumienie WebSocket Media Streams
LiveKit Open source, niskie opóźnienia, WebRTC Oficjalny plugin OpenAI
Daily Prosty, hostowany, dobry do prototypowania SDK Pipecat z konektorem Realtime

Kluczowe wnioski

  • Twilio Media Streams pozwala podłączyć rozmowę telefoniczną do dwukierunkowego gniazda WebSocket
  • Twój serwer działa jako most między strumieniem Twilio Media Stream a OpenAI Realtime API
  • Format G.711 μ-law jest natywny dla telefonii i bezpośrednio obsługiwany przez Realtime API
  • LiveKit (open source, WebRTC) i Daily (hostowany) to viable alternatywy dla Twilio
  • Architektura jest zawsze taka sama: telefonia → Twój serwer → Realtime API