Utiliser ThunderPhone avec des clients OpenAI Realtime

Configurez un client serveur compatible avec OpenAI Realtime pour utiliser ThunderPhone, avec un agent enregistré ou une configuration de session intégrée.

ThunderPhone implémente un sous-ensemble ciblé du modèle d’événements OpenAI Realtime. Un client côté serveur existant peut conserver son flux d’événements WebSocket, audio, session et réponse tout en utilisant un agent vocal ThunderPhone.

Avant de vous connecter#

Vous avez besoin d’une clé API secrète d’organisation ThunderPhone et d’un environnement d’exécution serveur capable d’ouvrir des WebSockets. Ne vous connectez pas depuis du code de navigateur et n’exposez pas la clé à un navigateur. Pour utiliser un agent enregistré, déployez-le d’abord et copiez son ID numérique.

Connectez-vous à :

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

Authentifiez la mise à niveau WebSocket depuis votre serveur :

Authorization: Bearer sk_live_YOUR_API_KEY

L’authentification par chaîne de requête est disponible pour les clients qui ne peuvent pas définir d’en-têtes de handshake, mais les URL risquent davantage d’être exposées dans les journaux.

Choisir qui gère la configuration#

Agent enregistré#

Connectez-vous avec l’ID de l’agent déployé :

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

L’agent démarre pendant la connexion du socket. Son message d’accueil reste disponible, mais Realtime désactive ses relances vocales en cas de silence et omet transfer_call et send_keypad_input. Les autres outils compatibles s’exécutent sur ThunderPhone. N’envoyez pas d’instructions en ligne ni d’outils exécutés par le client dans ce mode.

Définissez l’audio transmis avant le démarrage de l’agent avec les paramètres de requête input_audio_format, output_audio_format, input_rate et output_rate. Vous ne pouvez pas modifier la configuration enregistrée ni les formats audio après la connexion.

Session en ligne#

Sans agent_id, attendez session.created, puis envoyez 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"
    }
  }
}

La première mise à jour acceptée provisionne l’appel. session.updated signifie que la session est active. Les instructions, la voix, le produit, les outils et les formats audio ne peuvent plus être modifiés après ce point.

Les sessions en ligne n’ont ni message d’accueil automatique ni relances vocales en cas de silence. Pour faire parler l’agent en premier, ajoutez un message système ou utilisateur et envoyez response.create. Une session complètement inactive se termine tout de même à la limite d’appel silencieux de la plateforme, 600 secondes par défaut.

Utiliser le SDK officiel OpenAI#

Transmettez une URL de base WebSocket se terminant par /v1 ; le SDK ajoute /realtime. La valeur de model est un nom de compatibilité et ne sélectionne pas le produit ThunderPhone. Choisissez le produit dans la configuration de session ou dans l’agent enregistré.

Cette vérification de connexion crée une session Bolt en ligne, affiche les événements jusqu’au premier session.updated, puis se ferme. Utilisez le client Python minimal pour diffuser l’audio.

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

Conservez votre gestion existante de l’ajout d’audio d’entrée, des deltas audio de réponse, des interruptions, des appels de fonction, des erreurs et de la fermeture propre du socket. Les fonctions personnalisées en ligne s’exécutent dans votre client ; renvoyez leurs résultats via le protocole Realtime. Les outils des agents enregistrés s’exécutent sur ThunderPhone.

Cycle de vie de la session et échecs#

Un WebSocket représente un appel. Un ID d’agent non valide ou une configuration en ligne rejetée produit un événement error. Attendez session.updated avant de considérer la session comme active. Déclarez les formats d’entrée et de sortie réels ainsi que les fréquences d’échantillonnage : une incompatibilité de fréquence PCM lit l’audio trop vite ou trop lentement au lieu de produire une erreur de validation.

Après le démarrage de la session, fermez proprement le socket lorsque votre application a terminé. Les sessions en ligne peuvent utiliser des fonctions exécutées par le client. Les sessions d’agent enregistré utilisent des outils compatibles exécutés par ThunderPhone et ne proposent ni transfert ni saisie au clavier.

Tester l’intégration#

Commencez avec le client WAV Python minimal et un WAV PCM16 mono à la fréquence déclarée. Vérifiez :

1. Le serveur accepte la configuration et envoie session.updated.
2. L’entrée produit des événements de transcription et d’audio de réponse à la vitesse attendue.
3. L’interruption et l’annulation de la réponse arrêtent l’audio de sortie restant.
4. Les résultats des fonctions en ligne ou des outils d’agent enregistré sont renvoyés au modèle.
5. Une entrée non valide produit un événement error géré par votre client.
6. Votre client ferme le socket et l’appel apparaît dans l’historique des appels.

La référence WebSocket Realtime répertorie les événements acceptés, les formats audio, les champs de session et des exemples complets.

Coût#

Les appels Realtime utilisent le tarif normal par minute du produit sélectionné. L’activation des deltas de transcription en direct ajoute un supplément par minute pour toute la session ; consultez les transcriptions en direct pour le tarif et la tarification pour les tarifs des produits.

POST /v1/realtime/sessions est un chemin LiveKit géré distinct. Il crée une salle et un jeton de participant à portée limitée ; il n’est pas requis pour une connexion WebSocket directe.

Pour les intégrations de framework, consultez Utiliser ThunderPhone avec Pipecat et Utiliser ThunderPhone avec LiveKit Agents.