Usa ThunderPhone con client OpenAI Realtime

Indirizza un client server compatibile con OpenAI Realtime a ThunderPhone, usando un agente salvato o una configurazione di sessione inline.

ThunderPhone implementa un sottoinsieme mirato del modello di eventi OpenAI Realtime. Un client lato server esistente può mantenere il proprio flusso di eventi WebSocket, audio, sessione e risposta utilizzando un agente vocale ThunderPhone.

Prima di connetterti#

Ti servono una chiave API segreta dell'organizzazione ThunderPhone e un runtime server che possa aprire WebSocket. Non connetterti dal codice del browser e non esporre la chiave a un browser. Per utilizzare un agente salvato, distribuiscilo prima e copia il suo ID agente numerico.

Connettiti a:

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

Autentica l'upgrade WebSocket dal tuo server:

Authorization: Bearer sk_live_YOUR_API_KEY

L'autenticazione tramite query string è disponibile per i client che non possono impostare gli header di handshake, ma è più facile che gli URL finiscano nei log.

Scegli chi gestisce la configurazione#

Agente salvato#

Connettiti con l'ID dell'agente distribuito:

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

L'agente si avvia mentre il socket si connette. Il suo saluto rimane disponibile, ma Realtime disabilita i controlli vocali in caso di silenzio e omette transfer_call e send_keypad_input. Gli altri strumenti compatibili vengono eseguiti su ThunderPhone. Non inviare istruzioni inline o strumenti eseguiti dal client per questa modalità.

Imposta l'audio di trasmissione prima dell'avvio dell'agente con i parametri query input_audio_format, output_audio_format, input_rate e output_rate. Non puoi modificare la configurazione salvata o i formati audio dopo la connessione.

Sessione inline#

Senza agent_id, attendi session.created, quindi invia 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"
    }
  }
}

Il primo aggiornamento accettato configura la chiamata. session.updated indica che la sessione è attiva. Istruzioni, voce, prodotto, strumenti e formati audio non possono cambiare dopo quel momento.

Le sessioni inline non hanno un saluto automatico né controlli vocali in caso di silenzio. Per fare parlare prima l'agente, aggiungi un messaggio di sistema o utente e invia response.create. Una sessione completamente inattiva termina comunque al limite di chiamata silenziosa della piattaforma, 600 secondi per impostazione predefinita.

Usa l'SDK ufficiale OpenAI#

Fornisci un URL base WebSocket che termini con /v1; l'SDK aggiunge /realtime. Il valore di model è un nome di compatibilità e non seleziona il prodotto ThunderPhone. Scegli il prodotto nella configurazione della sessione o nell'agente salvato.

Questo controllo della connessione crea una sessione Bolt inline, stampa gli eventi fino al primo session.updated e si chiude. Usa il client Python minimale per trasmettere l'audio in streaming.

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

Mantieni la gestione esistente dell'aggiunta dell'audio di input, dei delta audio della risposta, delle interruzioni, delle chiamate di funzione, degli errori e della chiusura pulita del socket. Le funzioni personalizzate inline vengono eseguite nel tuo client; restituisci i relativi risultati tramite il protocollo Realtime. Gli strumenti degli agenti salvati vengono eseguiti su ThunderPhone.

Ciclo di vita della sessione ed errori#

Un WebSocket rappresenta una chiamata. Un ID agente non valido o una configurazione inline rifiutata produce un evento error. Attendi session.updated prima di considerare attiva la sessione. Dichiara i formati e le frequenze di campionamento effettivi di input e output: una frequenza PCM non corrispondente riproduce l'audio troppo velocemente o troppo lentamente anziché produrre un errore di convalida.

Dopo l'avvio della sessione, chiudi il socket in modo pulito quando l'applicazione ha terminato. Le sessioni inline possono utilizzare funzioni eseguite dal client. Le sessioni con agente salvato utilizzano strumenti compatibili eseguiti da ThunderPhone e non offrono il trasferimento né l'input da tastierino.

Testa l'integrazione#

Inizia con il client Python WAV minimo e un WAV PCM16 mono alla frequenza dichiarata. Verifica quanto segue:

1. Il server accetta la configurazione e invia session.updated.
2. L'input produce eventi di trascrizione e audio della risposta alla velocità prevista.
3. L'interruzione e l'annullamento della risposta interrompono l'audio di output rimanente.
4. I risultati delle funzioni inline o degli strumenti dell'agente salvato vengono restituiti al modello.
5. Un input non valido produce un evento error gestito dal tuo client.
6. Il tuo client chiude il socket e la chiamata appare nella cronologia chiamate.

Il riferimento WebSocket Realtime elenca gli eventi accettati, i formati audio, i campi della sessione e gli esempi completi.

Costo#

Le chiamate Realtime utilizzano la normale tariffa al minuto del prodotto selezionato. L'attivazione dei delta delle trascrizioni live aggiunge un supplemento al minuto per l'intera sessione; consulta Trascrizioni live per la tariffa e Prezzi per le tariffe dei prodotti.

POST /v1/realtime/sessions è un percorso LiveKit gestito separato. Crea una stanza e un token partecipante con ambito limitato; non è necessario per una connessione WebSocket diretta.

Per le integrazioni con framework, consulta Usa ThunderPhone con Pipecat e Usa ThunderPhone con LiveKit Agents.