Utilizați ThunderPhone cu clienți OpenAI Realtime

Direcționați un client de server compatibil cu OpenAI Realtime către ThunderPhone, utilizând fie un agent salvat, fie o configurație de sesiune inline.

ThunderPhone implementează un subset concentrat al modelului de evenimente OpenAI Realtime. Un client existent de pe server își poate păstra fluxul de evenimente WebSocket, audio, sesiune și răspuns în timp ce utilizează un agent vocal ThunderPhone.

Înainte de conectare#

Aveți nevoie de o cheie API secretă de organizație ThunderPhone și de un mediu de rulare pe server care poate deschide WebSocket-uri. Nu vă conectați din codul browserului și nu expuneți cheia într-un browser. Pentru a utiliza un agent salvat, implementați-l mai întâi și copiați ID-ul său numeric de agent.

Conectați-vă la:

wss://api.thunderphone.com/v1/realtime

Autentificați actualizarea WebSocket de pe serverul dumneavoastră:

Authorization: Bearer sk_live_YOUR_API_KEY

Autentificarea prin șir de interogare există pentru clienții care nu pot seta antete la negocierea conexiunii, dar URL-urile sunt mai ușor de divulgat în jurnale.

Alegeți cine deține configurația#

Agent salvat#

Conectați-vă cu ID-ul agentului implementat:

wss://api.thunderphone.com/v1/realtime?agent_id=12

Agentul pornește în timpul conectării socketului. Salutul său rămâne disponibil, însă Realtime îi dezactivează verificările vocale în perioadele de tăcere și omite transfer_call și send_keypad_input. Alte instrumente compatibile rulează pe ThunderPhone. Nu trimiteți instrucțiuni inline sau instrumente executate de client pentru acest mod.

Setați formatul audio transmis înainte ca agentul să pornească folosind parametrii de interogare input_audio_format, output_audio_format, input_rate și output_rate. Nu puteți modifica configurația salvată sau formatele audio după conectare.

Sesiune inline#

Fără agent_id, așteptați session.created, apoi trimiteți session.update:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}

Prima actualizare acceptată pregătește apelul. session.updated înseamnă că sesiunea este activă. Instrucțiunile, vocea, produsul, instrumentele și formatele audio nu pot fi modificate după acel moment.

Sesiunile inline nu au un salut automat sau verificări vocale în perioadele de tăcere. Pentru ca agentul să vorbească primul, adăugați un mesaj de sistem sau de utilizator și trimiteți response.create. O sesiune complet inactivă se încheie totuși la limita platformei pentru apeluri silențioase, implicit 600 de secunde.

Utilizați SDK-ul oficial OpenAI#

Transmiteți un URL de bază WebSocket care se termină cu /v1; SDK-ul adaugă /realtime. Valoarea model este un nume de compatibilitate și nu selectează produsul ThunderPhone. Alegeți produsul în configurația sesiunii sau în agentul salvat.

Această verificare a conexiunii creează o sesiune Bolt inline, afișează evenimente până la primul session.updated, apoi se închide. Utilizați clientul Python minimal pentru a transmite audio în flux.

import asyncio
import os
 
from openai import AsyncOpenAI
 
 
async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )
 
    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break
 
 
if __name__ == "__main__":
    asyncio.run(main())

Păstrați gestionarea existentă pentru adăugarea audio de intrare, diferențele audio ale răspunsului, întreruperi, apeluri de funcții, erori și închiderea corectă a socketului. Funcțiile personalizate inline se execută în clientul dumneavoastră; returnați rezultatele lor prin protocolul Realtime. Instrumentele agentului salvat se execută pe ThunderPhone.

Ciclul de viață al sesiunii și erori#

Un WebSocket reprezintă un apel. Un ID de agent nevalid sau o configurație inline respinsă produce un eveniment error. Așteptați session.updated înainte de a considera sesiunea activă. Declarați formatele și frecvențele de eșantionare reale pentru intrare și ieșire: o nepotrivire a frecvenței PCM redă sunetul prea rapid sau prea lent, în loc să producă o eroare de validare.

După ce sesiunea începe, închideți corect socketul când aplicația dumneavoastră a terminat. Sesiunile inline pot utiliza funcții executate de client. Sesiunile cu agent salvat utilizează instrumente compatibile executate de ThunderPhone și nu oferă transfer sau introducere prin tastatură.

Testați integrarea#

Începeți cu clientul Python WAV minimal și un WAV PCM16 mono la frecvența declarată. Verificați:

1. Serverul acceptă configurația și trimite session.updated.
2. Intrarea produce evenimente de transcriere și audio de răspuns la viteza așteptată.
3. Întreruperea și anularea răspunsului opresc sunetul de ieșire rămas.
4. Rezultatele funcțiilor inline sau rezultatele instrumentelor agentului salvat sunt returnate modelului.
5. O intrare nevalidă produce un eveniment error pe care clientul dumneavoastră îl gestionează.
6. Clientul dumneavoastră închide socketul, iar apelul apare în Istoricul apelurilor.

Referința WebSocket Realtime listează evenimentele acceptate, formatele audio, câmpurile sesiunii și exemple complete.

Cost#

Apelurile Realtime utilizează tariful normal pe minut al produsului selectat. Activarea diferențelor de transcriere live adaugă o suprataxă pe minut pentru întreaga sesiune; consultați Transcrieri live pentru tarif și Prețuri pentru tarifele produselor.

POST /v1/realtime/sessions este o cale LiveKit gestionată separată. Aceasta creează o cameră și un token de participant cu domeniu de aplicare; nu este necesară pentru o conexiune WebSocket directă.

Pentru integrări cu frameworkuri, consultați Utilizați ThunderPhone din Pipecat și Utilizați ThunderPhone din LiveKit Agents.