---
title: "Utiliser ThunderPhone avec des clients OpenAI Realtime"
description: "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 à :

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

Authentifiez la mise à niveau WebSocket depuis votre serveur :

```http
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

| Mode | Se connecter avec | Source de configuration |
| --- | --- | --- |
| Agent enregistré | `?agent_id=12` | Prompt, voix, produit, langues, connaissances et outils compatibles exécutés côté serveur déployés |
| En ligne | Aucun `agent_id` | Le premier `session.update` accepté provenant de votre client |

### Agent enregistré

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

```text
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` :

```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"
    }
  }
}
```

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](/api-reference/realtime#minimal-python-client) pour diffuser l’audio.

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

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](/api-reference/realtime#minimal-python-client)
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](/fr/guides/review-calls).

La [référence WebSocket Realtime](/api-reference/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](/api-reference/realtime#live-transcripts) pour le tarif et la
[tarification](/fr/guides/pricing) 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](/fr/guides/use-with-pipecat)
et [Utiliser ThunderPhone avec LiveKit Agents](/fr/guides/use-with-livekit).