ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Connect tools & data

Upotrebljavajte ThunderPhone s klijentima OpenAI Realtime

Usmjerite klijent poslužitelja kompatibilan s OpenAI Realtimeom na ThunderPhone, koristeći spremljenog agenta ili ugrađenu konfiguraciju sesije.

ThunderPhone implementira fokusirani podskup modela događaja OpenAI Realtime. Postojeći klijent na poslužiteljskoj strani može zadržati svoj tijek događaja za WebSocket, zvuk, sesiju i odgovore dok upotrebljava glasovnog agenta ThunderPhone.

Prije povezivanja

Potreban Vam je tajni API ključ organizacije ThunderPhone i poslužiteljsko izvršno okruženje koje može otvoriti WebSocket veze. Nemojte se povezivati iz koda preglednika niti izlagati ključ pregledniku. Da biste upotrebljavali spremljenog agenta, najprije ga implementirajte i kopirajte njegov numerički ID agenta.

Povežite se s:

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

Autorizirajte nadogradnju WebSocket veze sa svojeg poslužitelja:

Authorization: Bearer sk_live_YOUR_API_KEY

Autentifikacija putem niza upita dostupna je za klijente koji ne mogu postaviti zaglavlja rukovanja, ali URL-ovi lakše mogu dospjeti u zapisnike.

Odaberite tko upravlja konfiguracijom

Način radaOdaberite ga pomoćuIzvor konfiguracije
Spremljeni agentsession.prompt.id u prvom session.update ili ?agent_id=12Objavljeni prompt, glas, proizvod, jezici, baza znanja i kompatibilni alati koji se pokreću na poslužitelju, uz upute i varijable ove sesije
UmetnutoNi jednoPrvi prihvaćeni session.update od Vašeg klijenta

Spremljeni agent

Zadržite u spremljenom agentu ono što je zajedničko svim pozivima, gdje ima verzije i skupove za testiranje, a ono što se mijenja po sesiji pošaljite u prvom session.update: session.prompt.id odabire objavljeni agent, session.instructions sadrži kratki opis ove sesije, a session.prompt.variables popunjava rezervirana mjesta {{name}} u promptu 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 } }
    }
  }
}

Upute postaju kontekst poziva, dodan nakon prompta agenta samo za taj poziv. Vlastite opcije sesije (telephony, outbound, ivr_mode, call_events, placeholders) i jezik na kojem započinje (primary_language) navode se u session.config, kao i za ugrađenu sesiju. Glas, proizvod i alati agenta dolaze iz njegove objavljene konfiguracije: glas, druga postavka agenta ili polje koje podržava samo OpenAI, kao što je tool_choice koji nije zadani u ažuriranju, stvara događaj error i zanemaruje se, a alati koje izvršava vaš klijent odbijaju se (alati koje izvršava klijent zahtijevaju ugrađenu sesiju). prompt.version prihvaća se i zanemaruje. Pogledajte Korištenje spremljenog agenta za sva pravila.

Povezivanje s ?agent_id=12 umjesto toga pokreće agenta dok se soket povezuje, pa session.update nije potreban, ali je konfiguracija njegove sesije tada nepromjenjiva: upute, varijable i opcije sesije (outbound, ivr_mode, telephony, placeholders, call_events) poslane nakon toga odbijaju se događajem error. Dodajte &wait_for_session_update=1 u URL da biste ga umjesto toga pokrenuli pri prvom session.update, koji tada na isti način sadrži upute, varijable i opcije sesije; odlazna sesija to zahtijeva. Dok to ažuriranje ne stigne, zvuk pozivatelja zadržava se, drugi događaji se odbijaju, a soket se zatvara ako nijedno ne stigne u roku od 10 sekundi.

Pozdrav ostaje dostupan, ali Realtime onemogućuje glasovne provjere tišine agenta i nudi transfer_call i send_keypad_input samo uz call_events. Ostali kompatibilni alati izvode se na ThunderPhone; alati koje izvršava klijent zahtijevaju ugrađenu sesiju. Formati zvuka te upute i varijable sesije ne mogu se promijeniti nakon početka poziva.

Ugrađena sesija

Bez spremljenog agenta pričekajte session.created, a zatim pošaljite 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"
    }
  }
}

Prvo prihvaćeno ažuriranje uspostavlja poziv. session.updated znači da je sesija aktivna. Upute, glas, proizvod, alati i audioformati nakon toga se ne mogu mijenjati. Da bi upute ostale nepromijenjene, a mijenjali se samo imenovani podaci, u njih upišite rezervirana mjesta {{name}} i pošaljite vrijednosti u session.config.variables.

Ugrađene sesije nemaju automatsku uvodnu poruku ni glasovne provjere tijekom tišine. Da bi agent prvi progovorio, dodajte poruku sustava ili korisnika i pošaljite response.create. Potpuno neaktivna sesija i dalje završava pri ograničenju platforme za tihi poziv, koje prema zadanim postavkama iznosi 600 sekundi.

Upotrijebite službeni OpenAI SDK

Proslijedite osnovni URL za WebSocket koji završava s /v1; SDK dodaje /realtime. Vrijednost model naziv je za kompatibilnost i ne odabire proizvod ThunderPhone. Odaberite proizvod u konfiguraciji sesije ili spremljenom agentu.

Ova provjera veze stvara ugrađenu Bolt sesiju, ispisuje događaje do prvog session.updated i zatvara se. Upotrijebite minimalni Python klijent za strujanje zvuka.

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

Zadržite postojeću obradu za dodavanje ulaznog zvuka, delta promjene zvuka odgovora, prekide, pozive funkcija, pogreške i pravilno zatvaranje utičnice. Ugrađene prilagođene funkcije izvršavaju se u vašem klijentu; njihove rezultate vratite putem protokola Realtime. Alati spremljenog agenta izvršavaju se na ThunderPhoneu.

Životni ciklus sesije i neuspjesi

Jedan WebSocket predstavlja jedan poziv. Nevažeći ID agenta ili odbijena ugrađena konfiguracija proizvodi događaj error. Pričekajte session.updated prije nego što sesiju smatrate aktivnom. Navedite stvarne ulazne i izlazne formate te frekvencije uzorkovanja: nepodudaranje PCM frekvencije reproducira zvuk prebrzo ili presporo umjesto da proizvede pogrešku provjere valjanosti.

Nakon pokretanja sesije uredno zatvorite utičnicu kada vaša aplikacija završi s radom. Ugrađene sesije mogu koristiti funkcije koje izvršava klijent. Sesije sa spremljenim agentom koriste kompatibilne alate koje pokreće ThunderPhone te nude transfer_call (uz send_keypad_input u odlaznim sesijama) samo s call_events; vaš klijent izvršava te događaje call.*.

Testirajte integraciju

Počnite s minimalnim Python WAV klijentom i mono PCM16 WAV datotekom pri deklariranoj frekvenciji. Provjerite:

  1. Poslužitelj prihvaća konfiguraciju i šalje session.updated.
  2. Ulaz proizvodi događaje prijepisa i zvuka odgovora očekivanom brzinom.
  3. Prekid i otkazivanje odgovora zaustavljaju preostali izlazni zvuk.
  4. Rezultati ugrađene funkcije ili rezultati alata spremljenog agenta vraćaju se modelu.
  5. Nevažeći unos proizvodi događaj error koji vaš klijent obrađuje.
  6. Vaš klijent zatvara utičnicu, a poziv se pojavljuje u Povijesti poziva.

Referenca za Realtime WebSocket navodi prihvaćene događaje, formate zvuka, polja sesije i potpune primjere.

Cijena

Pozivi u stvarnom vremenu naplaćuju se kao i svaki drugi poziv: prema cijeni njihovih dijelova po cjenicima naših pružatelja usluga, uz infrastrukturnu naknadu i maržu od 17–25 %. Omogućavanje delta ažuriranja prijepisa uživo dodaje rad na transkripciji za cijelu sesiju; pogledajte Prijepise uživo i Cijene.

POST /v1/realtime/sessions zaseban je upravljani LiveKit put. Stvara sobu i token s ograničenim opsegom za sudionika; nije potreban za izravnu WebSocket vezu.

Za integracije s okvirima pogledajte Upotreba ThunderPhonea iz Pipecata i Upotreba ThunderPhonea s LiveKit Agents.