Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Puhelinintegraatio (Twilio jne.)

Oppitunti 15 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Puhelinintegraatio (Twilio jne.)
  2. Telefonia-arkkitehtuuri
  3. Toteutus Twiliolla
  4. Twilio-vaihtoehdot
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 Realtime API -dokumentaation perusteella: G.711 μ-law -muodon nimi on audio/pcmu (aiemmin tekstissä mainittu g711_ulaw oli 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-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (suositeltu korvaaja on gpt-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-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. 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:

1

Saapuva puhelu → Twilio

Käyttäjä soittaa puhelinnumeroon. Twilio vastaanottaa puhelun ja lähettää webhook-kutsun palvelimellesi.

2

Palvelimesi → Mediavirta

Palvelimesi vastaa TwiML-ohjeilla, jotka avaavat kaksisuuntaisen Media Stream WebSocket -yhteyden.

3

Mediavirta ↔ Realtime API

Palvelimesi välittää äänen Twilio Media Streamin ja OpenAI Realtime API:n välillä.

4

Ää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