Bloc API - Appelez des API externes depuis le flux de votre chatbot

Vue d'ensemble

Le bloc API permet à votre chatbot d'appeler n'importe quelle API REST externe en cours de conversation, de capturer la réponse et d'orienter le flux selon le succès ou l'échec. Utilisez-le pour rechercher des commandes dans votre base de données, vérifier des OTP, récupérer le statut d'une expédition, consulter des soldes de compte ou intégrer tout système exposant un point de terminaison HTTP.

Lorsque le bot atteint un bloc API, il envoie la requête HTTP configurée, attend la réponse, extrait des champs du corps JSON ou XML vers des variables, puis suit la branche de succès (HTTP 2xx/3xx) ou la branche d'échec (HTTP 4xx/5xx). Les blocs suivants du flux peuvent utiliser les variables extraites dans des messages, des conditions ou des appels API ultérieurs.

Où le trouver

1. Ouvrez votre chatbot dans Studio
2. Faites glisser le bloc API depuis la barre latérale gauche vers le canevas
3. Connectez-le depuis n'importe quel bloc précédent
4. Double-cliquez sur le bloc pour le configurer

Le bloc API possède deux connexions de sortie : Succès (haut/par défaut) pour les réponses 2xx et 3xx, et Échec (secondaire) pour les réponses 4xx et 5xx.

Configuration

Étape 1 : Définissez l'URL et la méthode de la requête

Champ	Description
URL	Le point de terminaison complet, par exemple https://api.example.com/orders/{order_id}
Méthode	Verbe HTTP : GET, POST, PUT, PATCH ou DELETE

Vous pouvez insérer toute variable capturée plus tôt dans le flux avec la syntaxe {variable_name} (accolades simples). Les variables sont résolues au moment de l'exécution, avant l'envoi de la requête.

Étape 2 : Ajoutez des paramètres de requête (facultatif)

Pour les requêtes GET, utilisez les paramètres de requête pour ajouter des paires clé-valeur à l'URL. Chaque ligne comporte une clé et une valeur. La substitution de variables fonctionne dans les deux champs.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

Étape 3 : Configurez les en-têtes

Ajoutez des en-têtes HTTP personnalisés dans la section En-têtes. Chaque ligne comporte une clé et une valeur.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

Content-Type est détecté automatiquement lorsque vous choisissez un format de corps, mais vous pouvez le remplacer.

Étape 4 : Ajoutez l'authentification

Le bloc API prend en charge trois modes d'authentification. Choisissez celui qui correspond à votre API cible.

Type d'auth	Champs	Comment il est envoyé
Authentification basique	Nom d'utilisateur, Mot de passe	Envoyé comme Authorization: Basic <base64>
Jeton Bearer	Jeton Bearer	Envoyé comme Authorization: Bearer <token>
En-tête personnalisé	Nom d'en-tête, Valeur d'en-tête	Envoyé comme <Name>: <Value> (pour les clés d'API, schémas personnalisés)

Remarque : Pour les API utilisant x-api-key ou similaire, choisissez En-tête personnalisé et définissez le Nom sur x-api-key et la Valeur sur votre clé. Vous pouvez aussi stocker la clé dans une variable et la référencer comme {api_key}.

Étape 5 : Construisez le corps de la requête

Pour les requêtes POST, PUT et PATCH, configurez le corps dans la section Corps. Choisissez le format :

Format	À utiliser quand
JSON	La plupart des API REST modernes
XML	Points de terminaison SOAP ou XML hérités
Aucun	Aucun corps nécessaire (typique pour GET et DELETE)

Écrivez le JSON ou XML brut dans l'éditeur de corps. Les variables peuvent être insérées en ligne :

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

Étape 6 : Mappez la réponse vers des variables

Sous Enregistrer la réponse dans des variables, définissez comment extraire des champs de la réponse JSON vers des variables de flux.

Chemin JSON	Nom de variable
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

Syntaxe de chemin prise en charge :

• Notation par points pour les objets imbriqués : result.user.email
• Index de tableau : items[0].name
• Extraction de tableau par caractère générique : items[*].id renvoie tous les ID sous forme de tableau
• Champ racine : status ou message

Les valeurs extraites sont disponibles dans tous les blocs suivants sous la forme {variable_name}.

Étape 7 : Soumettez et enregistrez

Cliquez sur Soumettre dans la fenêtre du bloc, puis enregistrez le flux avec Enregistrer les modifications dans la barre supérieure.

Comment la réponse est gérée

Chemin de succès (HTTP 2xx / 3xx)

1. Les variables de Enregistrer la réponse dans des variables sont renseignées
2. Le flux suit la connexion de sortie Succès

Chemin d'échec (HTTP 4xx / 5xx)

1. Les variables de réponse peuvent ou non être renseignées selon le corps d'erreur
2. Le flux suit la connexion de sortie Échec
3. Utilisez cette branche pour envoyer un message d'erreur convivial ou réessayer

Délai d'expiration

Les requêtes expirent après 30 secondes. Si votre API est lente, envisagez de diviser le travail en deux étapes ou d'utiliser un schéma asynchrone piloté par webhook.

Tester dans le bac à sable API

Chaque appel de bloc API est journalisé et disponible dans le bac à sable API au sein de Studio. Pour chaque exécution de test, vous pouvez voir :

• L'URL, la méthode et les en-têtes entièrement résolus
• Le corps de la requête envoyé
• Le code de statut HTTP reçu
• Le corps complet de la réponse
• Les variables extraites

Utilisez le bac à sable pour déboguer les variables de modèle, l'authentification et les mappages de chemins JSON avant de mettre le flux en production.

Bonnes pratiques

• Stockez les secrets dans des variables, pas dans la configuration du bloc. Capturez les clés d'API depuis des paramètres spécifiques à l'environnement et transmettez-les via des variables afin que le même flux fonctionne en préproduction et en production
• Configurez toujours la branche Échec. Ne supposez jamais que l'appel API réussit. Envoyez un message de repli comme « Nous n'avons pas pu récupérer votre commande pour le moment. Veuillez réessayer plus tard. »
• Gardez les corps de requête petits. N'envoyez pas l'historique complet des discussions ou de grandes charges utiles, sauf si l'API en a besoin
• Validez les champs de réponse avant de les utiliser. Si order_status peut être absent, ajoutez un bloc Condition après l'appel API pour vérifier {order_status} avant de l'utiliser dans un message
• Utilisez des noms de variables descriptifs. user_email est préférable à val1 car il est plus facile à déboguer dans le bac à sable et le journal de conversation
• Définissez Content-Type explicitement lors de l'envoi de JSON, afin que les API strictes acceptent la requête

Cas d'usage courants

Recherche de commande

Le client fournit un identifiant de commande, le bot récupère le statut depuis votre backend e-commerce.

• Méthode : GET
• URL : https://api.myshop.com/orders/{order_id}
• Auth : Jeton Bearer
• Mappage de réponse : data.status vers order_status, data.tracking_url vers tracking_url

Vérification d'OTP

Le bot collecte un code à 6 chiffres, appelle votre point de terminaison de vérification et oriente le flux selon le résultat.

• Méthode : POST
• URL : https://api.myapp.com/verify-otp/
• Corps : {"phone": "{phone}", "code": "{otp_code}"}
• Mappage de réponse : verified vers otp_verified
• Utilisez ensuite un bloc Condition : si {otp_verified} == true continuez, sinon redemandez

Synchronisation de contact CRM

Poussez les coordonnées collectées vers votre CRM lorsque l'utilisateur termine la qualification.

• Méthode : POST
• URL : https://api.crm.com/v1/contacts/
• Auth : En-tête personnalisé (x-api-key: {crm_key})
• Corps : {"name": "{name}", "email": "{email}", "source": "chatbot"}

Dépannage

La requête échoue avec 401 Unauthorized

1. Vérifiez que le type d'auth correspond à ce que l'API attend
2. Pour les jetons Bearer, n'incluez pas le mot Bearer dans le champ du jeton. Le bloc l'ajoute automatiquement
3. Pour l'auth En-tête personnalisé, vérifiez que le nom de l'en-tête correspond exactement à la documentation de l'API (sensible à la casse pour certaines API)
4. Inspectez la requête dans le bac à sable API pour confirmer que l'en-tête est bien envoyé

Les variables ne se renseignent pas à partir de la réponse

1. Ouvrez le bac à sable API et inspectez le corps réel de la réponse
2. Confirmez que le chemin JSON correspond à la structure de la réponse. Les chemins sont sensibles à la casse
3. Pour les tableaux, utilisez items[0].field pour une seule valeur ou items[*].field pour toutes les valeurs
4. Si la réponse est en XML, assurez-vous d'avoir correctement défini le format de corps. Les chemins JSON fonctionnent aussi sur le XML analysé

Le flux suit la branche d'échec même quand l'API fonctionne

1. Vérifiez le code de statut HTTP dans le bac à sable API. Certaines API renvoient 201 (Created) sur POST, ce qui est toujours un succès
2. Si l'API renvoie 200 mais avec une erreur dans le corps, utilisez un bloc Condition après la branche de succès pour inspecter le champ de réponse

La requête expire

1. Le délai est fixé à 30 secondes. Si votre API prend régulièrement plus de temps, l'API peut ne pas être adaptée au chat en temps réel
2. Envisagez de déplacer le travail lent vers une tâche en arrière-plan et d'interroger le résultat, ou utilisez un webhook pour être notifié lorsque c'est prêt

Les variables de modèle apparaissent comme {variable} brut dans la requête

1. Confirmez que la variable a été définie par un bloc antérieur dans le flux
2. Vérifiez l'orthographe du nom de la variable (sensible à la casse)
3. Utilisez le journal de conversation pour inspecter quelles variables sont réellement renseignées à ce point

Étapes suivantes

• Bloc Webhook - Recevez des appels HTTP entrants pour déclencher ou reprendre un flux
• Bloc Fin de conversation - Terminez les conversations avec un bouton de redémarrage
• Vue d'ensemble de Studio - Explorez tous les types de blocs et les fonctionnalités du générateur de flux