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.
Authentification
| Option | Ce qui est envoyé |
|---|---|
| No authentication | Rien |
| Bearer token / access token | Un en-tête Authorization: Bearer avec votre jeton |
| API key in a header | Votre clé dans l'en-tête que vous nommez, par exemple X-API-Key |
| API key in the URL | Votre clé comme paramètre de requête que vous nommez, par exemple api_key |
| Username and password | Authentification HTTP basic |
| Custom — I'll set the headers myself | Ce 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.
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.
- 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.