Compétence IA : Effectuer des requêtes HTTP

Éligibilité du forfait : Disponible sur les forfaits Advanced, Enterprise et certains forfaits Legacy. Les tests sont disponibles pour tous les utilisateurs, mais la publication nécessite un forfait éligible.

La compétence Make HTTP requests permet à votre Agent IA d'appeler des API externes pendant une conversation. Cela permet à votre Agent IA de récupérer des données en temps réel ou de déclencher des actions dans des systèmes externes en fonction de la demande du Contact. Par exemple, il peut vérifier le statut d'une commande, récupérer les informations de compte ou créer des enregistrements dans un autre système. Dans cet article, vous apprendrez comment configurer la compétence « Effectuer des requêtes HTTP » et la tester avec votre Agent IA.

L'Agent IA :

1. Analyse le message du Contact pour déterminer s'il correspond à l'intention définie dans les instructions de ton action.

2. Collecte les informations requises.

3. Envoie la requête HTTP.

4. Interprète la réponse de l'API.

5. Répond naturellement au Contact.

Ajoute une action Make HTTP requests

Si Effectuer des requêtes HTTP n'a pas encore été ajoutée à votre Agent IA, cliquez sur + Ajouter une compétence et sélectionnez-la. Puis sélectionnez + Ajouter une action pour configurer votre première requête HTTP. Vous pouvez ajouter jusqu'à 10 actions de cette manière, chacune appelant un point de terminaison différent ou traitant un scénario distinct.

Définissez quand l'action doit s'exécuter

Donnez un nom descriptif à l'action dans le champ Nom de l'action.

Dans le champ Quand et comment cette action doit-elle être effectuée ? champ, décrivez :

• Quand l'Agent IA doit utiliser cette action

• Ce qu'elle récupère ou envoie

• Toute condition ou résultat à gérer

Exemple :

Utilisez cette action pour récupérer le statut de commande d'un Contact lorsque celui-ci demande des informations sur sa commande. Si l'API renvoie une erreur 404, informez le Contact que la commande est introuvable.

L'Agent IA utilise cette description pour décider quand déclencher la requête.

Informations dont l'Agent IA peut avoir besoin (facultatif)

Définissez les entrées requises dans cette section avant d'appeler votre API.

Il s'agit de variables structurées que l'Agent IA doit collecter. La requête n'est déclenchée qu'une fois que toutes les entrées requises sont disponibles.

Si une valeur est :

• Déjà mentionnée dans la conversation → l'Agent IA l'utilise.

• Manquante → l'Agent IA la demande au Contact.

Les variables créées ici peuvent être utilisées dans la configuration de l'API. Les variables de Contact (comme $contact.email) sont disponibles automatiquement et n'ont pas besoin d'être ajoutées.

Paramètres du champ

Configuration de la requête

Définissez comment l'Agent IA doit appeler votre API.

Vous pouvez configurer :

• Méthode

• URL

• Paramètres de requête

• En-têtes

• Corps JSON (pour POST, PUT, PATCH)

Référence des variables

Vous pouvez insérer des variables dans l'URL, les paramètres, les en-têtes ou le corps en utilisant $.

Il existe deux types :

• Variables de Contact — champs de Contact existants

  • $contact.email

• Variables de l'Agent IA — champs définis sous Informations dont l'Agent IA peut avoir besoin

  • $agent.order_id

Les variables sont remplacées par des valeurs réelles lors de l'exécution de la requête. Si une variable requise de l'Agent IA est manquante, l'Agent IA la demandera avant de déclencher l'appel API.

Comment l'Agent IA gère les réponses de l'API

Exemple de corps :

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

L'Agent IA interprète automatiquement la réponse JSON de l'API et génère une réponse naturelle.

Exemple de réponse API :

{
  "status": "shipped",
  "eta": "2025-12-12"
}

Réponse de l'Agent IA : « Bonne nouvelle ! Votre commande a été expédiée et devrait arriver le 12 décembre 2025. »

Envoi d'images ou de fichiers depuis la réponse de l'API

Si la réponse de l'API contient une URL d'image ou de fichier valide (par ex. un plan, une facture ou une photo produit), l'Agent IA peut l'envoyer en pièce jointe rendue — le même mécanisme utilisé pour les Sources de connaissances et les URL d'instructions. Voir Envoi de fichiers et d'images en pièces jointes.

Cela nécessite une instruction explicite l'autorisant, par exemple :

Envoyez l'image/le fichier en pièce jointe chaque fois qu'il y a une URL d'image/fichier valide dans la réponse de l'API.

Sans cette instruction, l'Agent IA n'utilisera l'URL que pour informer sa réponse textuelle — il ne l'enverra pas en pièce jointe.

Tests

Vous pouvez tester votre action de requête HTTP dans le panneau Tester l'Agent IA avant de publier.

Comment tester

1. Démarrez une conversation de test qui correspond aux conditions de votre action.

   

2. Lorsque l'intention est détectée et que les entrées requises sont disponibles, l'Agent IA exécute la requête HTTP.

3. Un événement d'exécution apparaît dans le panneau de test :

   

   1. {AI Agent name} a exécuté {Action name}

   2. Les réponses 2xx sont affichées comme réussies

   3. Tous les autres codes de statut sont affichés comme des échecs

4. Cliquez sur l'événement pour voir :

   1. Response onglet (par défaut) — corps complet de la réponse de l'API

   2. Request onglet — charge utile complète de la requête cURL

   3. Option de copie pour le débogage

5. Après avoir reçu la réponse de l'API, l'Agent IA génère une réponse basée sur les données renvoyées.

Notes importantes

• Les événements d'exécution apparaissent uniquement dans le panneau Tester l'Agent IA. Ils n'apparaissent pas dans Inbox ni dans l'activité du Contact.

• Si des entrées requises manquent, l'Agent IA les demandera avant de déclencher la requête.

Meilleures pratiques

• Soyez précis dans la description de votre action. Des instructions vagues entraînent des déclenchements vagues.

• Définissez clairement les entrées requises. Si l'IA doit demander quelque chose, rendez-le évident.

• Prenez en charge les cas d'erreur dans vos instructions.

• Testez toujours avant de publier.

• Évitez de dupliquer la logique déjà gérée par les flux de travail, sauf si cela est intentionnel.

Limitations

• Maximum : 10 actions de requête HTTP par Agent IA.

• Maximum par action :

  • 20 champs de saisie de données

  • 50 paramètres

  • 50 en-têtes

• L'Agent IA attend jusqu'à 15 secondes la réponse d'une API. Si votre endpoint prend plus de temps, la requête échoue.

• L'Agent IA détermine quand appeler l'API en se basant sur ta description écrite. Des instructions mal rédigées peuvent provoquer des déclenchements inattendus.

• Le traitement des réponses de l'API est automatique. Tu ne peux pas mapper manuellement les champs de réponse — l'IA interprète le JSON de façon contextuelle.

• Les événements d'exécution des requêtes HTTP apparaissent uniquement dans le panneau Test AI Agent et non dans Contact Activity.

• Les Agents IA vocaux peuvent déclencher l'action « Effectuer des requêtes HTTP ». Cependant, la réponse renvoyée par l'API n'est pas transmise à l'Agent IA vocal pour la génération de la réponse, ce qui signifie que les conversations vocales ne peuvent pas répondre dynamiquement en fonction du résultat de l'API.

• Si votre agent IA met à jour un champ Contact et utilise également ce champ dans cette action au cours du même tour, la requête envoie à chaque fois l'ancienne valeur (ou vide, si elle n'a jamais été définie). Cela se produit indépendamment de l'ordre d'exécution des actions. Si vous êtes intéressé, votez pour la demande de fonctionnalité.