Aller au contenu
Documentation

Actions API personnalisées : appeler votre API

Laissez votre agent intoCHAT appeler votre API HTTP pendant le chat : requête et authentification, import cURL, entrées tirées de la conversation et test.

Une action API personnalisée permet à l'agent d'appeler un point de terminaison HTTP pendant la conversation, par exemple pour vérifier un stock ou un prix à jour, et de répondre à partir du résultat. Les actions se créent dans l'onglet Actions de votre agent. Pour que l'agent propose un lien au lieu d'appeler une API, voir Boutons personnalisés.

Créer une action

Cliquez sur Add Action, ou sur Import a request pour partir d'une commande cURL. L'éditeur comporte quatre étapes et l'on enregistre une seule fois à la fin avec Create action. Le test est facultatif mais recommandé.

1. The request (la requête)

  • Method : GET, POST, PUT, PATCH ou DELETE.
  • HTTPS URL : le point de terminaison. Une chaîne de requête collée dans l'URL est déplacée vers l'onglet Parameters.
  • Parameters, Headers et Body acceptent des paires clé et valeur. Body est disponible pour toutes les méthodes sauf GET et est envoyé en JSON.
  • Collect data inputs for action (optional) : des valeurs que l'agent tire de la conversation. Chaque entrée a un Name (lettres, chiffres et tirets bas), un Type (Text, Number ou Boolean), une Description et les options Required et Array. Jusqu'à 25 entrées par action.

Utilisez une entrée n'importe où dans la requête sous la forme {{name}} : dans le chemin de l'URL, un paramètre, un en-tête ou le corps.

GET https://api.example.com/products/{{productId}}/stock

L'agent trouve la valeur dans la conversation ou la demande au visiteur. Une entrée Required empêche l'agent d'appeler l'action avant d'avoir cette valeur. Les variables utilisées mais non déclarées comme entrées sont retirées de la requête ; l'éditeur vous prévient et propose Add them.

Variables pour les visiteurs vérifiés

Une fois la vérification d'identité configurée, une action côté serveur peut aussi utiliser {{user.id}}, {{user.email}}, {{user.name}} et {{user.metadata.<key>}} dans l'URL, les paramètres, les en-têtes et le corps :

GET https://api.example.com/customers/{{user.id}}/orders

Ce ne sont pas des entrées : intoCHAT les remplit sur ses serveurs à partir du visiteur que votre site a connecté et vérifié, et les laisse vides pour tous les autres ainsi que dans Send test request. L'IA ne les voit jamais et ne peut pas les choisir. Toute autre variable {{user.…}} ne peut pas être enregistrée. Voir Variables dans les actions côté serveur.

Variables pour les contacts

Une action côté serveur peut aussi lire le contact du visiteur : {{contact.email}}, {{contact.name}}, {{contact.phone}}, {{contact.external_id}} et {{contact.<attribute>}}, par exemple {{contact.plan}} :

GET https://api.example.com/accounts/{{contact.external_id}}?plan={{contact.plan}}

Pour un visiteur vérifié, il s'agit du contact qui a son identifiant d'utilisateur ; pour tous les autres, du contact du lead enregistré dans la conversation, sauf si ce contact a un identifiant externe. intoCHAT les remplit sur ses serveurs et l'IA ne les voit jamais. Contrairement à {{user.*}}, rien n'est envoyé vide : s'il n'y a pas de contact ou qu'une valeur manque, l'action ne s'exécute pas et l'agent apprend qu'il ne peut pas faire cela ici. Les variables inconnues comme {{contact.Plan}} ne peuvent pas être enregistrées, Send test request ne peut pas les remplir et les actions côté client ne les reçoivent jamais. Voir Utiliser les contacts dans les actions.

Authentification

OptionCe qui est envoyé
No authenticationRien
Bearer token / access tokenUn en-tête Authorization: Bearer avec votre jeton
API key in a headerVotre clé dans l'en-tête que vous nommez, par exemple X-API-Key
API key in the URLVotre clé comme paramètre de requête que vous nommez, par exemple api_key
Username and passwordAuthentification HTTP basic
Custom — I'll set the headers myselfCe que vous ajoutez dans l'onglet Headers

Importer une requête

Collez l'exemple cURL de la documentation de votre API, ou utilisez « Copy as cURL » sur une requête dans les outils réseau de votre navigateur. Méthode, URL, paramètres, en-têtes et corps sont remplis, et l'identifiant est placé dans le sélecteur Authentication. L'import remplace la requête mais conserve le nom et la description. Les envois multipart (-F) sont ignorés et un corps encodé en formulaire est importé sous forme de champs JSON.

2. Try it (tester)

Saisissez des valeurs de test pour les entrées et cliquez sur Send test request. La requête est construite exactement comme l'agent la construira. La Response Preview affiche le statut, le corps de la réponse et l'URL appelée.

3. When the AI should use it (quand l'utiliser)

  • Action Name : jusqu'à 60 caractères.
  • When to use : ce que fait l'action, les données qu'elle renvoie et des exemples de questions qui doivent la déclencher. Le modèle lit les 1 024 premiers caractères.
  • Server-side action s'exécute sur les serveurs d'intoCHAT et c'est le réglage par défaut. Client-side action s'exécute dans le navigateur du visiteur ; voir Actions côté client.
  • Enable this action : désactive une action sans la supprimer.
  • Only inside procedures (actions côté serveur uniquement) : l'agent ne peut appeler l'action qu'à une étape de procédure qui l'appelle, jamais de lui-même. Un appel à tout autre moment est refusé et rien n'est envoyé. Utilisez cette option pour les actions qui modifient quelque chose, comme un remboursement. L'action affiche alors un badge Procedure only dans la liste.
  • Requires team approval (actions côté serveur uniquement, offres Pro et Enterprise) : quand l'agent appelle l'action, rien n'est encore envoyé. L'appel, avec ses paramètres, attend sur la page Approvals jusqu'à ce qu'une personne pouvant modifier cet agent l'approuve (il s'exécute alors avec exactement ces paramètres) ou le refuse, et le visiteur est informé du résultat dans le chat. Choisissez quand une demande sans décision expire : 1 heure, 4 heures, 24 heures ou 3 jours. L'action affiche un badge Needs approval dans la liste. Voir Approbation des actions par l'équipe.

4. What the AI can see (ce que l'IA voit)

Full data access transmet toute la réponse au modèle. Limited data access ne transmet que les champs cochés sous Visible ; lancez d'abord un test pour charger la liste des champs. Pour une réponse en liste, les champs viennent du premier élément et le filtre s'applique à chaque élément. Tant qu'aucun champ n'est coché, la réponse complète est transmise.

Limites et sécurité

  • Jusqu'à 25 actions par agent, y compris les boutons personnalisés et les actions créées par Connecter votre boutique.
  • Les formulaires de chat, les procédures, la réservation avec Cal.com ou Calendly et la recherche web ne comptent pas dans cette limite.
  • Une action appelée par une étape de procédure ne peut pas être supprimée, ni transformée en action côté client ou en bouton, tant que vous ne l'avez pas retirée de la procédure. Le message indique les procédures concernées.
  • Une action API ou un bouton dont le nom correspond à celui d'un outil intégré, comme « search web » ou « show booking slots », est renommé en coulisses avec un numéro (search_web_2), pour que la recherche web et la réservation continuent de fonctionner. Une action côté client garde son nom exact, car le gestionnaire de votre page est enregistré sous ce nom : n'en nommez aucune search_web, sinon l'agent ne peut pas utiliser la recherche web tant qu'elle est activée.
  • L'URL doit viser un hôte public. Localhost, réseaux privés, adresses link-local et points de métadonnées cloud sont refusés, même quand un nom d'hôte pointe vers l'une de ces adresses. L'éditeur affiche alors « URL points to a blocked or internal host ».
  • Les redirections ne sont pas suivies. Si le test affiche « This address redirects somewhere else », cliquez sur Use this address.
  • Chaque appel expire au bout de 30 secondes.
  • Les réponses de plus de 40 000 caractères sont tronquées. Limited data access permet de les garder courtes.
  • Les actions côté serveur envoient vos identifiants depuis les serveurs d'intoCHAT, jamais par le navigateur du visiteur.

Voir en Markdown