Appels WebSocket
Tenez une conversation vocale en temps réel avec un agent via un WebSocket, depuis votre propre code.
Vue d'ensemble
L'API WebSocket permet à votre propre code de tenir une conversation vocale en temps réel avec un agent. Votre serveur ouvre une session, votre client se connecte au WebSocket de la session, transmet l'audio de l'utilisateur et fait entendre l'audio de l'agent à mesure qu'il arrive. L'agent écoute, répond avec sa propre voix et gère les interruptions, et la conversation est conservée comme tout autre appel de votre compte : elle apparaît dans votre historique d'appels, suit les paramètres d'enregistrement et de transcription de l'agent, et est facturée de la même façon.Utilisez-la quand votre code dispose déjà de l'audio : un serveur, un appareil, une plateforme de centre de contacts ou un système téléphonique que vous exploitez. Dans un navigateur ou une application mobile, utilisez les appels WebRTC, qui gèrent pour vous le micro, l'annulation d'écho et le réseau.Les messages sont des trames texte JSON avec les types d'événements propres à Aethex, et l'audio est en PCM 16 kHz par défaut. Vous recevez sous forme d'événements texte ce que l'utilisateur et l'agent ont dit, en plus de l'audio.
Démarrer un appel
Votre serveur ouvre la session ; votre client transporte l'audio.
POST /conversation/connect exige votre clé API, et la clé ne doit jamais parvenir à un client.Ouvrir une session
Depuis votre serveur, appelez
POST /conversation/connectavec votre clé API, l'agent ettransport: "websocket". Vous obtenez unsession_idet unws_url. Ajoutezdynamic_variablespour personnaliser l'appel, etcaller_phoneavec le numéro de l'utilisateur au format E.164 quand l'appel en a un.Ouvrir une session WebSocketbashcurl -X POST https://api.aethexai.com/api/v1/conversation/connect \ -H "X-API-Key: $AETHEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "transport": "websocket", "audio_format": "pcm_16000" }' # 201 Created { "session_id": "3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d", "ws_url": "wss://api.aethexai.com/ws/v1/conversation/3f2a7b1c-8d4e-4a5b-9c2d-1e0f3a4b5c6d" }Se connecter
Ouvrez un WebSocket vers
ws_url. Il fonctionne comme une URL signée : quiconque la détient peut rejoindre cette session, une seule fois. Ne la transmettez donc qu'au client qui se connecte. Un second socket sur la même session est refusé. Le premier message que vous recevez estsession_started.Converser
Envoyez l'audio de l'utilisateur sous forme d'événements
audioet faites entendre les événementsaudiode l'agent à mesure qu'ils arrivent. Quand vous recevezinterruption, supprimez l'audio de l'agent pas encore joué : l'utilisateur a commencé à parler par-dessus l'agent.user_transcriptetagent_responsevous indiquent ce que chacun a dit.Raccrocher
Pour terminer l'appel depuis votre client, fermez le socket. Quand l'agent termine l'appel, vous recevez
call_endedet le socket se ferme. Pour terminer un appel depuis votre serveur, appelezPOST /calls/{call_id}/endouPOST /conversation/{session_id}/end, et votre client reçoitcall_ended.
Qui parle en premier
Par défaut, l'agent parle en premier : il accueille l'utilisateur avec son premier message dès que le socket se connecte, comme lors d'un appel WebRTC. Si votre côté a passé l'appel, par exemple un appel sortant composé par votre système, connectez le socket une fois l'appel décroché et définissez direction à outbound. L'agent laisse alors la personne qui a décroché parler en premier : il l'accueille juste après son allô, ou après 3 secondes de silence si elle attend que vous parliez, comme lors d'un appel sortant.caller_phone est enregistré comme from_number de l'appel pour un appel entrant et comme to_number pour un appel sortant, comme pour un appel téléphonique.
Messages
Chaque message est une trame texte JSON avec un type. Ignorez tout type que vous ne reconnaissez pas : de nouveaux événements peuvent être ajoutés. Aethex ignore de même les types qu'il n'utilise pas.
| Événement | Envoyé par | Signification |
|---|---|---|
audio | Votre client | L'audio de l'utilisateur, en base64 dans audio, au format audio de la session. |
dtmf | Votre client | Une touche du clavier : un chiffre dans digit. |
contextual_update | Votre client | Un contexte pour l'agent dans text, par exemple ce que l'utilisateur consulte. Il n'interrompt pas l'agent et ne demande pas de réponse. |
pong | Votre client | Votre réponse à un ping, avec son event_id. |
session_started | Aethex | La session est active : session_id et audio_format. |
audio | Aethex | L'audio de l'agent, en base64 dans audio. Faites-le entendre dans l'ordre. |
interruption | Aethex | L'utilisateur parle par-dessus l'agent. Supprimez l'audio de l'agent pas encore joué. |
user_transcript | Aethex | Ce que l'utilisateur a dit, dans text. |
agent_response | Aethex | Ce que l'agent a dit pendant son tour, dans text. |
ping | Aethex | Un maintien de connexion. Répondez par pong avec le même event_id. |
call_ended | Aethex | L'appel est terminé, et reason indique pourquoi. Le socket se ferme ensuite. |
error | Aethex | L'appel a été refusé à l'ouverture du socket ; code indique pourquoi. Le socket se ferme ensuite. |
{"type": "audio", "audio": "AAABAP7/AgD9/wMA/P8EAPv/BQD6/wYA..."}
{"type": "dtmf", "digit": "5"}
{"type": "contextual_update", "text": "The user opened the pricing page"}
{"type": "pong", "event_id": 1}Format audio
Choisissez le format avec audio_format à l'ouverture de la session ; les deux sens l'utilisent. pcm_16000, par défaut, est du PCM 16 bits little-endian à 16 kHz, mono. ulaw_8000 est du G.711 µ-law à 8 kHz, mono, pour l'audio provenant d'une ligne téléphonique. L'audio circule encodé en base64 dans le champ audio des événements audio. Envoyez des blocs de 20 ms au rythme réel (640 octets de PCM ou 160 octets de µ-law avant encodage), et continuez d'envoyer pendant les silences : l'agent s'en sert pour savoir quand l'utilisateur a fini de parler.
Compatibilité Twilio Media Streams
Si votre système parle déjà le format Twilio Media Streams, ouvrez la session avec protocol: "twilio". Le socket utilise alors les messages de Twilio : media et dtmf depuis votre client, et media, clear et stop depuis Aethex, avec un audio µ-law à 8 kHz. Ce mode n'a pas d'événements de transcription ni de texte de l'agent, et audio_format ne peut valoir que ulaw_8000.
Pendant l'appel
- L'appel apparaît dans GET /calls avec provider à websocket et la direction choisie. Sa transcription et son enregistrement s'obtiennent par les endpoints habituels, avec le session_id.
- GET /conversation/{session_id}/status indique created jusqu'à la connexion de votre client, puis in-progress, puis completed, ou failed si l'appel n'a pas pu démarrer.
- La durée maximale d'appel de l'agent s'applique. À la limite, l'appel se termine et vous recevez call_ended.
- Ces appels ne peuvent pas être transférés : l'audio passe par votre client, il n'y a donc aucune ligne qu'Aethex puisse transmettre. L'outil de transfert de l'agent est désactivé pour eux.
Codes de fermeture
Si le socket se ferme avant ou pendant un appel pour une autre raison qu'un raccrochage normal, le code de fermeture indique pourquoi.
La session est inconnue ou expirée, n'a pas été ouverte avec transport: "websocket", a déjà un socket ou est terminée.
Ouvrez une nouvelle session avec POST /conversation/connect et connectez-vous une seule fois à son ws_url.
L'appel a échoué après son démarrage. La session est marquée failed.
Démarrez une nouvelle session. Si le problème persiste, contactez le support avec le session_id.
L'appel n'a pas pu démarrer : la capacité manquait, ou votre compte ne peut pas être facturé. Un événement error arrive d'abord, avec code à admission_rejected ou billing_blocked.
Pour admission_rejected, réessayez avec une nouvelle session après un court délai. Pour billing_blocked, vérifiez la facturation dans votre tableau de bord.
Étapes suivantes
Consultez chaque champ de POST /conversation/connect et du WebSocket dans la référence de l'API Conversation, personnalisez chaque appel avec Personnalisation, et recevez les événements d'appel avec les Webhooks.
