ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Connect tools & data

Používanie ThunderPhone s klientmi OpenAI Realtime

Nakonfigurujte klienta servera kompatibilného s OpenAI Realtime tak, aby používal ThunderPhone, a to buď s uloženým agentom, alebo s vloženou konfiguráciou relácie.

ThunderPhone implementuje zameranú podmnožinu modelu udalostí OpenAI Realtime. Existujúci klient na strane servera môže zachovať svoj tok udalostí WebSocketu, zvuku, relácie a odpovedí a zároveň používať hlasového agenta ThunderPhone.

Pred pripojením

Potrebujete tajný kľúč API organizácie ThunderPhone a serverové prostredie, ktoré dokáže otvárať WebSockety. Nepripájajte sa z kódu prehliadača ani nevystavujte kľúč prehliadaču. Ak chcete použiť uloženého agenta, najprv ho nasaďte a skopírujte jeho číselné ID agenta.

Pripojte sa k:

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

Overte aktualizáciu WebSocketu zo svojho servera:

Authorization: Bearer sk_live_YOUR_API_KEY

Overovanie pomocou reťazca dotazu je dostupné pre klientov, ktorí nemôžu nastaviť hlavičky handshaku, ale adresy URL môžu ľahšie uniknúť do protokolov.

Vyberte, kto spravuje konfiguráciu

RežimVyberiete ho pomocouZdroj konfigurácie
Uložený agentsession.prompt.id v prvom session.update alebo ?agent_id=12Nasadená výzva, hlas, produkt, jazyky, znalosti a kompatibilné nástroje spúšťané na serveri, plus pokyny a premenné tejto relácie
VloženýAni jednoPrvý prijatý session.update od vášho klienta

Uložený agent

V uloženom agentovi uchovávajte všetko, čo majú všetky hovory spoločné, kde má verzie a testovacie sady, a v prvom session.update odošlite to, čo sa mení pre jednotlivé relácie: session.prompt.id vyberá nasadeného agenta, session.instructions obsahuje stručné zadanie tejto relácie a session.prompt.variables dopĺňa zástupné symboly {{name}} v promte agenta.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "12",
      "variables": { "user_name": "Ada Park" }
    },
    "instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}

Inštrukcie sa stanú kontextom hovoru, pridaným za prompt agenta iba pre tento hovor. Vlastné možnosti relácie (telephony, outbound, ivr_mode, call_events, placeholders) a jazyk, v ktorom sa začína (primary_language), patria do session.config, rovnako ako pri vloženej relácii. Hlas agenta, produkt a nástroje pochádzajú z jeho nasadenej konfigurácie: hlas, iné nastavenie agenta alebo pole určené len pre OpenAI, napríklad iná než predvolená hodnota tool_choice v aktualizácii, vyvolá udalosť error a bude ignorované; nástroje spúšťané vaším klientom budú odmietnuté (nástroje spúšťané klientom vyžadujú vloženú reláciu). prompt.version sa prijme a ignoruje. Všetky pravidlá nájdete v časti Použitie uloženého agenta.

Pripojenie pomocou ?agent_id=12 namiesto toho spustí agenta počas pripájania soketu, takže session.update nie je potrebné, no konfigurácia relácie je potom pevne daná: inštrukcie, premenné a možnosti relácie (outbound, ivr_mode, telephony, placeholders, call_events) odoslané potom budú odmietnuté udalosťou error. Ak chcete agenta namiesto toho spustiť pri prvom session.update, pridajte do adresy URL &wait_for_session_update=1; táto aktualizácia potom rovnakým spôsobom obsahuje inštrukcie, premenné a možnosti relácie. Odchádzajúca relácia to vyžaduje. Kým táto aktualizácia nepríde, zvuk volajúceho sa zadrží, ostatné udalosti budú odmietnuté a soket sa zatvorí, ak žiadna nepríde do 10 sekúnd.

Úvodný pozdrav zostáva k dispozícii, ale Realtime vypne hovorené kontroly ticha agenta a ponúka transfer_call a send_keypad_input iba s call_events. Ostatné kompatibilné nástroje sa spúšťajú v ThunderPhone; nástroje spúšťané klientom vyžadujú vloženú reláciu. Formáty zvuku ani inštrukcie a premenné relácie sa po začatí hovoru nemôžu zmeniť.

Vložená relácia

Bez uloženého agenta počkajte na session.created a potom odošlite 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"
    }
  }
}

Prvá prijatá aktualizácia zriadi hovor. session.updated znamená, že relácia je aktívna. Pokyny, hlas, produkt, nástroje a formáty zvuku po tomto bode nemožno zmeniť. Ak chcete zachovať pokyny nemenné a meniť iba pomenované hodnoty, zapíšte do nich zástupné symboly {{name}} a hodnoty odošlite v session.config.variables.

Vložené relácie nemajú automatický pozdrav ani hovorené kontroly ticha. Ak chcete, aby agent prehovoril ako prvý, pridajte systémovú alebo používateľskú správu a odošlite response.create. Úplne nečinná relácia sa stále ukončí pri limite platformy pre tiché hovory, ktorý je predvolene 600 sekúnd.

Použite oficiálnu súpravu OpenAI SDK

Odovzdajte základnú URL adresu WebSocketu končiacu na /v1; súprava SDK pridá /realtime. Hodnota model je názov kompatibility a nevyberá produkt ThunderPhone. Produkt vyberte v konfigurácii relácie alebo uloženom agentovi.

Táto kontrola pripojenia vytvorí vloženú reláciu Bolt, vypisuje udalosti až do prvej udalosti session.updated a potom sa zatvorí. Na streamovanie zvuku použite minimálneho klienta v jazyku Python.

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())

Zachovajte existujúce spracovanie pripájania vstupného zvuku, delta udalostí zvuku odpovede, prerušení, volaní funkcií, chýb a čistého zatvorenia soketu. Vložené vlastné funkcie sa vykonávajú vo vašom klientovi; ich výsledky vráťte prostredníctvom protokolu Realtime. Nástroje uloženého agenta sa vykonávajú v ThunderPhone.

Životný cyklus relácie a zlyhania

Jeden WebSocket predstavuje jeden hovor. Neplatné ID agenta alebo odmietnutá vložená konfigurácia vytvorí udalosť error. Pred považovaním relácie za aktívnu počkajte na session.updated. Zadajte skutočné vstupné a výstupné formáty a vzorkovacie frekvencie: nesúlad frekvencie PCM prehrá zvuk príliš rýchlo alebo príliš pomaly namiesto vytvorenia chyby overenia.

Po spustení relácie socket korektne zatvorte, keď aplikácia dokončí svoju činnosť. Vložené relácie môžu používať funkcie spúšťané klientom. Relácie s uloženým agentom používajú kompatibilné nástroje spúšťané službou ThunderPhone a ponúkajú transfer_call (a pri odchádzajúcich reláciách aj send_keypad_input) iba s call_events; tieto udalosti call.* vykonáva váš klient.

Otestujte integráciu

Začnite s minimálnym klientom WAV v jazyku Python a mono PCM16 WAV s deklarovanou vzorkovacou frekvenciou. Overte:

  1. Server prijme konfiguráciu a odošle session.updated.
  2. Vstup vytvorí udalosti prepisu a zvuku odpovede očakávanou rýchlosťou.
  3. Prerušenie a zrušenie odpovede zastavia zostávajúci výstupný zvuk.
  4. Výsledky vložených funkcií alebo nástrojov uloženého agenta sa vrátia modelu.
  5. Neplatný vstup vytvorí udalosť error, ktorú váš klient spracuje.
  6. Váš klient zatvorí soket a hovor sa zobrazí v histórii hovorov.

Referenčná dokumentácia Realtime WebSocket uvádza prijímané udalosti, zvukové formáty, polia relácie a úplné príklady.

Cena

Hovory v reálnom čase sa účtujú rovnako ako všetky ostatné hovory: podľa nákladov ich častí za cenníkové ceny našich poskytovateľov, plus poplatok za infraštruktúru a marža 17–25 %. Povolenie priebežných zmien prepisu pridáva prácu na prepise počas celej relácie; pozrite si Priebežné prepisy a Cenník.

POST /v1/realtime/sessions je samostatná spravovaná cesta LiveKit. Vytvorí miestnosť a token účastníka s obmedzeným rozsahom; pre priame pripojenie WebSocket nie je potrebná.

Informácie o integráciách s frameworkmi nájdete v časti Použitie ThunderPhone s Pipecat a Použitie ThunderPhone s LiveKit Agents.