aethexDocs

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.

QUATRE ÉTAPES

Démarrer un appel

Votre serveur ouvre la session ; votre client transporte l'audio.

Attention
Ouvrez les sessions uniquement depuis votre serveur. POST /conversation/connect exige votre clé API, et la clé ne doit jamais parvenir à un client.
  1. Ouvrir une session

    Depuis votre serveur, appelez POST /conversation/connect avec votre clé API, l'agent et transport: "websocket". Vous obtenez un session_id et un ws_url. Ajoutez dynamic_variables pour personnaliser l'appel, et caller_phone avec le numéro de l'utilisateur au format E.164 quand l'appel en a un.

    Ouvrir une session WebSocket
    bash
    curl -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"
    }
  2. 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 est session_started.

  3. Converser

    Envoyez l'audio de l'utilisateur sous forme d'événements audio et faites entendre les événements audio de l'agent à mesure qu'ils arrivent. Quand vous recevez interruption, supprimez l'audio de l'agent pas encore joué : l'utilisateur a commencé à parler par-dessus l'agent. user_transcript et agent_response vous indiquent ce que chacun a dit.

  4. Raccrocher

    Pour terminer l'appel depuis votre client, fermez le socket. Quand l'agent termine l'appel, vous recevez call_ended et le socket se ferme. Pour terminer un appel depuis votre serveur, appelez POST /calls/{call_id}/end ou POST /conversation/{session_id}/end, et votre client reçoit call_ended.

DIRECTION

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.

ÉVÉNEMENTS

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énementEnvoyé parSignification
audioVotre clientL'audio de l'utilisateur, en base64 dans audio, au format audio de la session.
dtmfVotre clientUne touche du clavier : un chiffre dans digit.
contextual_updateVotre clientUn 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.
pongVotre clientVotre réponse à un ping, avec son event_id.
session_startedAethexLa session est active : session_id et audio_format.
audioAethexL'audio de l'agent, en base64 dans audio. Faites-le entendre dans l'ordre.
interruptionAethexL'utilisateur parle par-dessus l'agent. Supprimez l'audio de l'agent pas encore joué.
user_transcriptAethexCe que l'utilisateur a dit, dans text.
agent_responseAethexCe que l'agent a dit pendant son tour, dans text.
pingAethexUn maintien de connexion. Répondez par pong avec le même event_id.
call_endedAethexL'appel est terminé, et reason indique pourquoi. Le socket se ferme ensuite.
errorAethexL'appel a été refusé à l'ouverture du socket ; code indique pourquoi. Le socket se ferme ensuite.
json
{"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}
AUDIO

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.

1008Violation de règle

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.

1011Erreur interne

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.

1013Réessayez plus tard

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.