Puhelinintegraatio (Twilio jne.)
Tällä sivulla
Päivitetty 3. marraskuuta 2026 Realtime API -dokumentaation perusteella: G.711 μ-law -muodon nimi on
audio/pcmu(aiemmin tekstissä mainittug711_ulawoli beta-vaiheen nimi). Lähde: Realtime API.
2. marraskuuta 2026 päivitys — Äänimallit. Useat tämän kurssin mallit on poistettu käytöstä:
tts-1,tts-1-hdjagpt-4o-mini-ttslakkaavat toimimasta 6. tammikuuta 2027 (suositeltu korvaaja ongpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tuetun endpointissa/v1/audio/speech: puheentuotannon migraation on kuljettava Realtime API:n kautta);gpt-realtime,gpt-4o-realtimeja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. helmikuuta 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien.
Puhelinintegraatio (Twilio jne.)
Ääniagentista tulee todella hyödyllinen, kun siihen pääsee puhelimitse. Pilvipohjaiset telefonia-alustat kuten Twilio, LiveKit ja Daily mahdollistavat Realtime API:n yhdistämisen maailmanlaajuiseen puhelinverkkoon. Käyttäjä soittaa numeroon, ja agenttisi vastaa reaaliajassa.
Telefonia-arkkitehtuuri
Telefoniaintegraatio lisää kerroksen puhelinverkon ja Realtime API:n väliin:
Saapuva puhelu → Twilio
Käyttäjä soittaa puhelinnumeroon. Twilio vastaanottaa puhelun ja lähettää webhook-kutsun palvelimellesi.
Palvelimesi → Mediavirta
Palvelimesi vastaa TwiML-ohjeilla, jotka avaavat kaksisuuntaisen Media Stream WebSocket -yhteyden.
Mediavirta ↔ Realtime API
Palvelimesi välittää äänen Twilio Media Streamin ja OpenAI Realtime API:n välillä.
Äänivaste → Käyttäjä
Realtime API:n tuottama vastausääni lähetetään takaisin Twilion kautta käyttäjän puhelimeen.
Toteutus Twiliolla
Saapuvan puhelun webhook
Kun puhelu saapuu, Twilio lähettää HTTP-pyynnön palvelimellesi. Vastaat TwiML-koodilla, joka avaa mediavirran:
from fastapi import FastAPI, Request
from fastapi.responses import Response
app = FastAPI()
@app.post("/incoming-call")
async def incoming_call(request: Request):
"""Twilio-webhook saapuville puheluille."""
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")
Mediavirran ja Realtime API:n silta
WebSocket-palvelin vastaanottaa äänen Twiliolta ja välittää sen Realtime API:lle:
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):
"""Silta Twilio Media Streamin ja Realtime API:n välillä."""
await twilio_ws.accept()
# Yhdistä Realtime API:hin
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
# Määritä istunto
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())
G.711-äänimuoto
Telefonia käyttää G.711 μ-law -muotoa (8 kHz, yksi tavu näytettä kohti). Realtime API tukee tätä natiivisti nimellä audio/pcmu, jonka määrität sekä syötteelle että tulosteelle (audio.input.format ja audio.output.format, kuten yllä olevassa koodissa). Tämä eliminoi tarpeen palvelinpuolen muunnoksille. Nimi g711_ulaw kuului API:n beta-vaiheeseen; A-law-vastineen nimi on audio/pcma.
Twilio-vaihtoehdot
| Alusta | Vahvuus | Realtime API -integraatio |
|---|---|---|
| Twilio | Kattava ekosysteemi, numeroita yli 100 maassa | Natiivit WebSocket-mediavirrat |
| LiveKit | Avoin lähdekoodi, pieni viive, WebRTC | Virallinen OpenAI-liitännäinen |
| Daily | Yksinkertainen, hostattu, sopii prototypointiin | Pipecat SDK Realtime-koneistolla |
Keskeiset asiat
- Twilio Media Streams mahdollistaa puhelinpuhelun yhdistämisen kaksisuuntaiseen WebSocketiin
- Palvelimesi toimii siltana Twilio Media Streamin ja OpenAI Realtime API:n välillä
- G.711 μ-law -muoto on natiivi telefoniassa ja Realtime API tukee sitä suoraan
- LiveKit (avoin lähdekoodi, WebRTC) ja Daily (hostattu) ovat toimivia vaihtoehtoja Twiliolle
- Arkkitehtuuri on aina sama: telefonia → palvelimesi → Realtime API