/conversation/connectOuvrir une session pour un agent. Côté serveur ; utilise votre clé API directement.
Connecter
Démarre une session WebRTC pour l'agent donné. Vous obtenez un session_id et un ice_config. Passez ice_config.iceServers directement dans new RTCPeerConnection({ iceServers }) côté navigateur. Agents publics : si l'agent a public_access activé, un navigateur ou une application peut appeler ce point de terminaison avec uniquement l'agent_id et sans clé API. Restreignez les sites autorisés à l'intégrer avec le champ allowed_origins de l'agent.Sessions WebSocket : avec transport: "websocket", la réponse contient un session_id et un ws_url à la place, pour que votre client y transmette la conversation (voir WS /ws/v1/conversation/:session_id ci-dessous). Seule une clé API peut en ouvrir une. Par défaut, l'agent accueille l'utilisateur en premier ; définissez direction à outbound quand votre côté a passé l'appel.
Corps de la requête
9agent_idstring (UUID)requisL'UUID de l'agent pour démarrer la session. Doit appartenir au compte appelant.
dynamic_variablesobjectoptionnelValeurs des placeholders
{{variable}}de l'agent, pour cette session uniquement — rien n'est enregistré sur l'agent. Même forme quePOST /calls/trigger: un objet plat de chaînes, nombres ou booléens. Les valeurs envoyées remplacent les valeurs par défaut de l'agent ; un placeholder sans l'une ni l'autre n'est jamais lu avec ses accolades : le modèle voit[nom: not provided]à sa place, et le message d'accueil parlé l'omet. Les clés ne peuvent pas commencer parsystem__— celles-là sont remplies pour vous, etsystem__caller_id/system__called_numbersont vides sur un appel navigateur, faute de ligne téléphonique. Sur une session WebSocket,caller_phoneremplit celui qui correspond à son côté de l'appel. Contrairement àPOST /calls/trigger, un placeholdersystem__non pris en charge est traité de la même façon au lieu d'être rejeté. Ignoré quand la session elle-même est sans clé — un agent public atteint sans clé d'API, ou un jeton d'appel — car ces identifiants vivent dans le navigateur ; ces sessions utilisent les valeurs par défaut de l'agent. Atteindre ce même agent public avec votre clé d'API personnalise normalement : ce qui décide, c'est l'identifiant, pas l'agent.transportstringoptionnelwebrtc(par défaut) pour un pair navigateur ou application, ouwebsocketpour transmettre l'audio de la conversation via un WebSocket depuis votre propre code. Une sessionwebsocketexige une clé API et renvoie unws_urlau lieu d'unice_config.directionstringoptionnelSessions WebSocket uniquement.
inbound(par défaut) : l'agent accueille l'utilisateur dès que le socket se connecte.outbound: votre côté a passé l'appel, l'agent laisse donc la personne qui a décroché parler en premier et l'accueille après son allô ou après 3 secondes de silence. Ignoré sur une session WebRTC.protocolstringoptionnelSessions WebSocket uniquement.
aethex(par défaut) : les événements JSON d'Aethex, avec ce que l'utilisateur et l'agent ont dit sous forme de texte.twilio: le format Twilio Media Streams, pour les systèmes qui le parlent déjà. Ignoré sur une session WebRTC.audio_formatstringoptionnelSessions WebSocket uniquement. L'audio échangé, dans les deux sens :
pcm_16000(PCM 16 bits à 16 kHz, par défaut) ouulaw_8000(G.711 µ-law à 8 kHz). Le protocoletwilion'accepte queulaw_8000. Ignoré sur une session WebRTC.caller_phonestring (E.164)optionnelSessions WebSocket uniquement. Le numéro de téléphone de la personne en ligne, au format E.164 (par exemple
+14155550199), quand l'appel en a un. Enregistré commefrom_numberde l'appel pour une session entrante et commeto_numberpour une session sortante, et remplitsystem__caller_idousystem__called_numberen conséquence. Ignoré sur une session WebRTC.opener_playedbooleanoptionnelSessions WebRTC uniquement. Mettez
truequand votre application fait entendre elle-même lefirst_messagede l'agent à l'utilisateur, avant ou pendant la connexion, par exemple à partir d'un audio gardé prêt, pour qu'il n'y ait pas de silence pendant la connexion. L'audio doit dire lefirst_messagetel qu'il se lit une fois ses variables remplies pour cette session. Coupez le micro pendant qu'il joue (n'envoyez pas d'audio de l'utilisateur) : sinon l'agent peut entendre son écho comme une parole de l'utilisateur. L'audio de l'utilisateur n'atteint l'agent qu'une fois l'appel connecté : si votre audio peut se terminer avant, gardez le micro coupé et affichez un état de connexion jusqu'à ce que la connexion soit établie. L'agent ne le redit pas : ce texte est ajouté à la conversation comme une phrase que l'agent a déjà dite, et l'agent attend que l'utilisateur parle. Si l'utilisateur reste silencieux, les relances habituelles de l'agent s'appliquent toujours : elles comptent à partir de la connexion de l'appel, ou de la fin de votre audio si vous envoyezopener_duration_secs. Avec ce paramètre, c'est votre application, et non l'agent, qui fait entendre lefirst_message: gardez-le en tête s'il contient une mention obligatoire (enregistrement de l'appel ou présence d'une IA, par exemple). L'enregistrement de l'appel ne contient pas votre audio : une mention que vous jouez (celle de l'enregistrement, par exemple) n'y figure pas. Vautfalsepar défaut. Ignoré sur une session WebSocket. Le champopener_playedde la réponse indique si l'agent tient votre audio pour joué : lancez-le ou continuez à le jouer seulement s'il vauttrue. Avecfalse, l'agent accueille lui-même l'utilisateur, parce que sonfirst_messageest vide une fois ses variables remplies, ou parce que le serveur ne connaît pas ce paramètre ; les serveurs plus anciens n'incluent pasopener_playeddans la réponse, donc traitez un champ absent commefalse.opener_duration_secsnumberoptionnelSessions WebRTC avec
opener_playeduniquement. La durée, en secondes, de l'audio dufirst_messageque joue votre application, comptée à partir de l'arrivée de cette requête : lancez donc la lecture au moment où vous l'envoyez. La première relance de l'agent auprès d'un utilisateur silencieux attend alors la fin de cet audio au lieu de compter à partir de la connexion, et ne parle jamais par-dessus la fin d'un longfirst_message. De0à60. Sans ce paramètre, les relances comptent à partir de la connexion de l'appel.
Erreurs
8Clé API manquante ou invalide.
Envoyez un en-tête X-API-Key valide ou un bearer token.
La clé API n'a pas la portée calls:write.
Utilisez une clé avec la portée requise.
transport vaut websocket, mais la requête n'utilise pas de clé API : par exemple un jeton d'appel, ou un agent public atteint sans clé.
Ouvrez les sessions WebSocket depuis votre serveur avec une clé API.
Le compte est bloqué : abonnement annulé après la période de grâce, ou solde nul sans moyen de paiement.
Réabonnez-vous, ajoutez un moyen de paiement, ou rechargez des crédits, puis réessayez.
L'agent_id n'existe pas ou n'appartient pas à ce compte.
Vérifiez via GET /api/v1/agents.
agent_id absent ou UUID invalide, ou dynamic_variables invalide — pas un objet plat de chaînes, nombres et booléens, ou une clé utilisant le préfixe réservé system__. Également une direction, un protocol ou un audio_format hors de leurs valeurs, audio_format pcm_16000 avec protocol twilio, ou, sur une session WebSocket, un caller_phone qui n'est pas au format E.164.
Envoyez un corps JSON avec un agent_id valide. Si vous envoyez dynamic_variables, gardez un objet plat de valeurs scalaires et retirez toute clé system__. Envoyez caller_phone au format E.164, par exemple +14155550199.
Le compte ou le backend partagé n'a pas de slot disponible. La réponse inclut retry_after et l'en-tête Retry-After.
Respectez l'en-tête Retry-After et réessayez.
Aucun slot backend ne peut être réservé.
Réessayez sous peu. Si persistant, contactez [email protected].
