--- title: "Usa ThunderPhone con client OpenAI Realtime" description: "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: ```text wss://api.thunderphone.com/v1/realtime ``` Autentica l'upgrade WebSocket dal tuo server: ```http 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 | Modalità | Connettiti con | Origine della configurazione | | --- | --- | --- | | Agente salvato | `?agent_id=12` | Prompt, voce, prodotto, lingue, Knowledge e strumenti compatibili eseguiti sul server distribuiti | | Inline | Nessun `agent_id` | Il primo `session.update` accettato dal tuo client | ### Agente salvato Connettiti con l'ID dell'agente distribuito: ```text 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`: ```json { "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](/api-reference/realtime#minimal-python-client) per trasmettere l'audio in streaming. ```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()) ``` 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](/api-reference/realtime#minimal-python-client) 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](/it/guides/review-calls). Il [riferimento WebSocket Realtime](/api-reference/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](/api-reference/realtime#live-transcripts) per la tariffa e [Prezzi](/it/guides/pricing) 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](/it/guides/use-with-pipecat) e [Usa ThunderPhone con LiveKit Agents](/it/guides/use-with-livekit).