Integracja telefoniczna (Twilio i inne)
Na tej stronie
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-hdorazgpt-4o-mini-ttsprzestaną działać 6 stycznia 2027 r. (zalecanym zamiennikiem jestgpt-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); modelegpt-realtime,gpt-4o-realtimeoraz starsze modele audio przestaną działać 20 stycznia 2027 r. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5); modelewhisper-1,gpt-4o-transcribeoraz endpoint/v1/audio/translationsprzestaną 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:
Połączenie przychodzące → Twilio
Użytkownik wybiera numer telefonu. Twilio odbiera połączenie i wysyła żądanie webhook do Twojego serwera.
Twój serwer → Strumień multimediów
Twój serwer odpowiada instrukcjami TwiML, które otwierają dwukierunkowe połączenie WebSocket Media Stream.
Strumień multimediów ↔ Realtime API
Twój serwer przekazuje dźwięk między strumieniem Twilio Media Stream a OpenAI Realtime API.
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