Live Webhook
Appelle un endpoint HTTP depuis la conversation, avec une méthode, une URL, des en-têtes JSON et un corps JSON pouvant transporter des variables dynamiques.
Live Webhook envoie des données vers un endpoint d’API externe pendant l’appel. L’agent décide de l’appeler, la plateforme effectue la requête HTTP, et la réponse revient à l’agent pour qu’il puisse exploiter ce qu’il a appris. C’est le connecteur polyvalent : rechercher une commande, créer un ticket, vérifier un solde, enregistrer un lead.
Le configurer
Ouvrez Tools (outils) sous Build (création), choisissez Add tool (ajouter un outil), puis Live Webhook. Après les champs communs :
| Champ | Type | Valeur par défaut | Remarques |
|---|---|---|---|
| Tool Title (titre de l’outil) | Texte | Send Webhook |
Nommez-le d’après sa fonction : Look up order. Lettres et espaces uniquement ; son ID, send_webhook par défaut, s’affiche sous le champ. |
| Description | Texte | Send data to an external API endpoint during the call |
Précisez le moment : Look up the order when the caller gives an order number. |
| AI Response (réponse de l’IA) | Texte | Let me process that information for you. |
Prononcée pendant l’exécution de la requête. |
| Method (méthode) | Liste déroulante | POST |
GET, POST, PUT, PATCH ou DELETE. |
| URL | URL | https://api.example.com/webhook |
Obligatoire. L’endpoint. Il doit être accessible depuis Internet. |
| Headers (en-têtes) | Objet JSON | { "Content-Type": "application/json", "Authorization": "Bearer YOUR_TOKEN" } |
Doit être un JSON valide. Remplacez YOUR_TOKEN. La valeur est enregistrée avec l’agent. |
| Body (corps) | Objet JSON | voir ci-dessous | Affiché uniquement pour POST, PUT et PATCH, où il est obligatoire et doit être un JSON valide. La charge utile. Écrivez {{variable}} pour toute valeur que l’agent doit renseigner au moment de l’appel. |
Le corps par défaut illustre le principe :
{
"message": "Call data",
"timestamp": "{{timestamp}}",
"caller_number": "{{caller_number}}",
"call_duration": "{{call_duration}}"
}Une valeur entre doubles accolades est remplacée au moment de la requête. Utilisez les
variables dynamiques de l’agent, les variables prédéfinies telles que
{{call_from_number}}, ou, dans un agent de type flow, une variable extraite à un
nœud précédent. Pour que l’agent fournisse une valeur recueillie en conversation, nommez
la variable dans le corps et décrivez-la dans Description : Send the order number the caller gave as order_number.
Paramètres d’exécution
Sous les champs de la requête, un encadré définit la façon dont la conversation traite la requête.
| Champ | Valeur par défaut | Remarques |
|---|---|---|
| Wait for result (attendre le résultat) | Activé | Lorsqu’il est activé, l’agent attend la réponse. Lorsqu’il est désactivé, l’agent peut poursuivre la conversation pendant l’exécution de la requête, et doit attendre le résultat avant d’annoncer une réussite. |
| Announce when finished (annoncer à la fin) | Désactivé | Affiché lorsque Wait for result est désactivé. Lorsqu’il est activé, le résultat est annoncé à un moment opportun sans interrompre l’appelant ; lorsqu’il est désactivé, il met à jour le contexte de l’agent sans rien dire. |
| HTTP timeout (milliseconds, optional) (délai d’expiration HTTP en millisecondes, facultatif) | vide | Un nombre entier de 1 à 120000. Laissez-le vide pour conserver le comportement actuel du délai d’expiration. |
Lorsque Wait for result est désactivé, le résultat n’est disponible que pendant la même session, et non après que l’appelant a raccroché. Un outil ajouté dans l’onglet Tools d’un nœud de flow n’affiche pas ces paramètres.
Choisissez Add Tool, puis Save (enregistrer) l’agent.
Comportement et limites
- La requête est effectuée lorsque le modèle appelle l’outil : c’est donc la Description qui décide du moment. Pour une requête qui doit se produire à un point fixe, utilisez le nœud Webhook d’un agent de type flow, qui se déclenche dès qu’il est atteint.
- Le corps de la réponse est renvoyé à l’agent comme résultat de l’outil. Gardez-le court et lisible : un objet JSON contenant les champs dont l’agent a besoin, pas un enregistrement complet.
- Par défaut, l’agent attend la réponse ; AI Response comble l’attente. Désactivez Wait for result pour que la conversation se poursuive pendant ce temps.
- Chaque outil dispose d’une seule URL et d’une seule méthode. Pour plusieurs endpoints, ajoutez plusieurs outils.
- La requête et la réponse apparaissent sur la page de l’appel sous forme d’appel d’outil. Voir Détails de l’appel.
Dépannage
- L’agent ne l’appelle jamais. La Description ne correspond pas à ce que disent les appelants. Reformulez-la autour du déclencheur, et mentionnez également l’outil dans Tasks (tâches).
- L’endpoint renvoie une erreur 401. Les Headers contiennent encore
YOUR_TOKEN, ou le token a expiré. - Le corps arrive avec des accolades littérales. Le nom de la variable n’est pas connu de l’agent. Vérifiez l’orthographe dans Variables, ou décrivez-la dans Description pour que l’agent la renseigne.