API de chatbot : REST, Zapier et webhooks expliqués

Une API de chatbot est une interface HTTP qui vous permet d’envoyer des messages à un chatbot IA et de recevoir des réponses par programmation — sans passer par un widget visuel. Plutôt qu’un utilisateur qui tape dans une bulle de discussion, votre code envoie une requête, reçoit une réponse, et en fait quelque chose : afficher une interface personnalisée, journaliser la réponse, déclencher une action ou router le résultat vers un autre système.

Ce guide couvre ce qu’est une API de chatbot, quand l’utiliser plutôt qu’un widget intégré, les trois méthodes de connexion principales (REST, Zapier et webhooks), et des modèles d’intégration concrets pour construire de vraies intégrations.

Qu’est-ce qu’une API de chatbot ?

Une API de chatbot expose votre chatbot IA entraîné comme un service que n’importe quel code peut appeler en HTTP. Vous envoyez le message d’un utilisateur dans le corps de la requête, et l’API renvoie la réponse du chatbot — puisée dans les sources que vous avez utilisées pour l’entraîner (contenu de site web, documents, paires de questions-réponses).

La distinction clé par rapport à un widget préconstruit : l’API renvoie des données brutes. C’est votre application qui décide comment les présenter. Cela signifie que vous pouvez intégrer le même chatbot dans une application mobile, un bot Slack, un tableau de bord interne et un pipeline d’automatisation back-end — tous avec la même base de connaissances entraînée.

La plupart des API de chatbot suivent un schéma similaire :

1. S’authentifier — inclure une clé API dans l’en-tête Authorization.
2. Envoyer un message en POST — envoyer le texte de l’utilisateur, un ID de chatbot et, éventuellement, un ID de conversation pour un contexte multi-tours.
3. Traiter la réponse — analyser la réponse, éventuellement diffuser les tokens en streaming pour un rendu en temps réel, et stocker le conversationId pour le tour suivant.

Pour les équipes qui comparent les options de chatbot avant de s’engager sur une plateforme, ce panorama des meilleurs chatbots IA pour site web couvre les critères à examiner selon les outils.

Quand utiliser l’API plutôt que le widget

Le widget intégré couvre la majorité des cas d’usage sur un site web. L’API est le bon choix quand vous avez besoin de quelque chose que le widget ne peut pas offrir.

Si votre cas d’usage se trouve dans la colonne de droite, l’API est le bon outil. Pour toutes les options d’intégration — widget, composant React, iframe et plugin WordPress — consultez le guide d’intégration de chatbot.

Méthodes de connexion et disponibilité selon le forfait

Il existe trois façons de connecter votre chatbot à des systèmes externes. Elles servent des objectifs différents et sont disponibles sur des forfaits différents.

L’API REST vous donne le plus de contrôle. Zapier est plus rapide à mettre en place si vous n’avez pas besoin de code personnalisé. Les webhooks complètent les deux — ils vous envoient les données au lieu d’attendre que vous alliez les chercher.

Pour une analyse complète de ce que chaque forfait inclut, consultez le guide sur le coût et la tarification d’un chatbot.

Exigences par forfait

La facturation annuelle réduit chaque prix de forfait d’environ 20 %. Les messages envoyés via l’API sont décomptés de votre quota mensuel de la même façon que les messages du widget.

Authentification

Chaque requête API nécessite un jeton Bearer. Vous générez vos clés API depuis les paramètres de l’espace de travail dans votre tableau de bord Agentkit.

Générer une clé API

1. Ouvrez votre espace de travail Agentkit.
2. Accédez à Paramètres puis Clés API.
3. Cliquez sur Créer une clé API.
4. Donnez-lui un nom explicite (par exemple, « Bot Slack Production »).
5. Copiez la clé immédiatement. Elle ne sera plus jamais affichée.

Utiliser la clé dans les requêtes

Incluez votre clé API dans l’en-tête Authorization :

Authorization: Bearer ak_live_your_api_key_here

Toutes les requêtes doivent être envoyées en HTTPS. Les requêtes sans jeton valide renvoient une réponse 401 Unauthorized.

Bonnes pratiques de gestion des clés

• Stockez les clés API dans des variables d’environnement, jamais dans du code côté client.
• Renouvelez vos clés périodiquement, surtout après un changement d’équipe.
• Créez des clés distinctes pour des intégrations distinctes afin de pouvoir en révoquer une sans affecter les autres.
• Supprimez les clés que vous n’utilisez plus.

Pour tous les détails sur l’authentification, consultez la documentation d’authentification.

Le point de terminaison de chat

Le cœur de l’API est un point de terminaison unique qui envoie un message utilisateur à votre chatbot et renvoie la réponse de l’IA.

Requête

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Corps de la requête :

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Réponse

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

Le conversationId dans la réponse est important. Stockez-le et repassez-le dans les requêtes suivantes pour conserver le contexte de la conversation. Sans lui, chaque message démarre une nouvelle conversation et le chatbot perd le fil.

Réponses d’erreur

Pour la référence complète des points de terminaison, consultez la documentation de l’API.

Réponses en streaming

Pour les applications en temps réel où vous voulez afficher la réponse au fur et à mesure de sa génération (l’effet machine à écrire attendu par les utilisateurs de chat IA), utilisez les Server-Sent Events (SSE).

Ajoutez le paramètre stream: true à votre requête :

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

La réponse arrive sous forme de flux d’événements SSE :

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Gérer le flux en JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

Le streaming est recommandé pour toute intégration destinée aux utilisateurs. Il rend le chatbot plus réactif, même lorsqu’il génère de longues réponses.

Webhooks

Là où le point de terminaison de chat vous permet d’envoyer des messages au chatbot, les webhooks laissent le chatbot vous envoyer des données. Quand des événements spécifiques se produisent, Agentkit envoie une requête HTTP POST à une URL que vous configurez. Les webhooks sont disponibles à partir du forfait Hobby.

Configurer les webhooks

1. Accédez à Paramètres puis Webhooks de votre espace de travail.
2. Saisissez l’URL de votre point de terminaison (doit être en HTTPS).
3. Sélectionnez les événements auxquels vous voulez vous abonner.
4. Enregistrez. Agentkit envoie une requête de vérification pour confirmer que votre point de terminaison est joignable.

Événements disponibles

Charge utile du webhook

Chaque envoi de webhook POST inclut un corps JSON à la structure uniforme :

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Vérifiez toujours le champ signature par rapport à votre secret webhook pour confirmer que la requête vient bien d’Agentkit, et non d’un tiers.

Comportement des nouvelles tentatives

Si votre point de terminaison renvoie un code de statut non-2xx, Agentkit retente l’envoi avec un backoff exponentiel : après 1 minute, 5 minutes, 30 minutes, puis s’arrête. Les envois échoués sont visibles dans les journaux de webhook de votre tableau de bord.

Schémas d’intégration courants

Modèle 1 : bot Slack

Faites remonter les questions clients de votre chatbot de site web vers un canal Slack, et laissez votre équipe répondre quand l’IA ne peut pas le faire.

1. Créez une application Slack avec les webhooks entrants activés.
2. Configurez un webhook Agentkit pour les événements conversation.completed.
3. Dans votre gestionnaire de webhook, vérifiez si la conversation a été résolue ou transférée.
4. Si elle a été transférée, envoyez un message formaté à votre URL de webhook Slack avec la transcription de la conversation.

Cela donne à votre équipe de support de la visibilité sans exiger qu’elle surveille le tableau de bord Agentkit.

Modèle 2 : interface de chat personnalisée

Remplacez le widget par défaut par une expérience de chat intégrée directement dans votre application.

1. Construisez votre interface de chat avec le framework de votre choix.
2. À l’envoi d’un message, appelez le point de terminaison de chat avec stream: true.
3. Affichez les tokens au fur et à mesure de leur arrivée, pour un retour en temps réel.
4. Stockez le conversationId dans l’état local pour conserver le contexte entre les messages.

C’est la bonne approche pour les applications mobiles, les applications de bureau, ou tout produit où le widget flottant ne correspond pas au design. Pour les équipes qui veulent s’en tenir au widget mais ont besoin de plus de contrôle sur le placement, le guide pour intégrer un chatbot sur votre site web couvre les quatre options d’intégration.

Modèle 3 : automatisation back-end

Utilisez le chatbot comme couche IA dans un workflow plus large, sans aucune interface de chat.

Exemple : traitement des tickets de support.

1. Un nouveau ticket arrive dans votre système de gestion de tickets.
2. Votre back-end envoie le contenu du ticket au point de terminaison de chat.
3. Le chatbot génère une réponse suggérée à partir de votre base de connaissances entraînée.
4. Votre système répond automatiquement (si la confiance est élevée) ou met la suggestion en file d’attente pour une revue humaine.

Ce schéma fonctionne parce que le chatbot est entraîné sur la même base de connaissances que votre équipe de support. L’API vous donne un accès programmatique à cette intelligence. Pour en savoir plus sur ce que vous pouvez utiliser pour entraîner un chatbot — explorations de site web, PDF, CSV, paires de questions-réponses — consultez comment entraîner un chatbot.

Modèle 4 : pipeline d’analyse

Capturez chaque conversation pour analyse.

1. Abonnez-vous aux événements webhook message.received et message.sent.
2. Votre gestionnaire de webhook écrit les événements dans votre entrepôt de données (BigQuery, Snowflake, etc.).
3. Construisez des tableaux de bord montrant les questions courantes, les taux de résolution, les heures de pointe et les tendances de conversation.

Le champ metadata du point de terminaison de chat vous permet d’associer du contexte (URL de la page, segment d’utilisateur, variante de test A/B) qui enrichit vos analyses.

Limite de débit

L’API applique des limites de débit pour garantir la fiabilité pour tous les utilisateurs.

Quand vous atteignez la limite, l’API renvoie un code de statut 429 avec un en-tête Retry-After indiquant combien de secondes attendre. Intégrez une logique de nouvelle tentative dans votre intégration :

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Considérations de sécurité

Lors de la construction d’intégrations API, gardez ces pratiques à l’esprit :

• N’exposez jamais les clés API dans du code côté client. Si vous construisez une interface de chat personnalisée pour une application web, faites transiter les requêtes par votre propre back-end.
• Validez les signatures des webhooks. Vérifiez toujours la signature HMAC avant de traiter les charges utiles des webhooks.
• Utilisez les restrictions de domaine. Dans les paramètres de votre chatbot, restreignez les domaines autorisés à interagir avec lui.
• Surveillez l’usage. Consultez régulièrement votre usage de l’API dans le tableau de bord pour repérer des pics inattendus qui pourraient signaler une clé compromise.
• Appliquez le principe du moindre privilège. Si une intégration n’a besoin que d’envoyer des messages, ne lui donnez pas une clé avec des permissions d’administration.

Pour les équipes qui explorent comment les API de chatbot IA se connectent à des écosystèmes d’outils plus larges, le MCP (Model Context Protocol) mérite d’être compris — c’est un standard émergent pour donner aux modèles d’IA un accès structuré à des outils et des données externes.

Pour commencer

Le chemin le plus rapide entre zéro et une intégration fonctionnelle :

1. Inscrivez-vous sur Agentkit et créez votre premier chatbot.
2. Entraînez le chatbot sur votre contenu (voir comment entraîner un chatbot).
3. Passez au forfait Hobby ($29.99/mois) pour activer l’accès à l’API.
4. Générez une clé API dans les paramètres de votre espace de travail.
5. Envoyez votre première requête de test avec cURL ou Postman.
6. Construisez à partir de là : interface personnalisée, bot Slack, automatisation, ou tout autre usage dont vous avez besoin.

Questions fréquentes

Qu’est-ce qu’une clé API de chatbot ?

Une clé API de chatbot est un jeton secret qui authentifie votre application quand elle effectue des requêtes vers l’API du chatbot. Vous la générez dans les paramètres de votre espace de travail, l’incluez dans l’en-tête Authorization: Bearer de chaque requête, et la traitez comme un mot de passe — stockez-la dans des variables d’environnement, jamais dans du code côté client, et renouvelez-la si vous soupçonnez qu’elle a été exposée. Chaque clé peut être limitée à une intégration spécifique, ce qui permet d’en révoquer une sans affecter les autres.

Existe-t-il une API de chatbot gratuite ?

Le forfait Free d’Agentkit ($0/mois) n’inclut pas l’accès à l’API REST — cela nécessite le forfait Hobby à $29.99/mois. Le forfait Free inclut le widget JS intégrable, la collecte de prospects et les restrictions de domaine, ce qui couvre la plupart des cas d’usage sur site web sans aucun code. Si vous avez besoin d’un accès programmatique dès le premier jour, le forfait Hobby est le point d’entrée, et vous pouvez tester la plateforme complète gratuitement avant de passer à un forfait supérieur.

Faut-il coder pour utiliser une API de chatbot ?

Pas toujours. Si vous avez besoin de l’accès à l’API REST pour des intégrations personnalisées, il vous faudra écrire du code — ou utiliser un outil comme Postman pour tester les appels manuellement. Mais si votre objectif est de connecter le chatbot à d’autres applications sans code, l’intégration Zapier (disponible sur le forfait Hobby et plus) se connecte à plus de 7 000 applications via une interface sans code. Pour l’intégration sur site web, aucun code n’est requis au-delà de coller une balise <script>.

Quels modèles d’IA l’API du chatbot prend-elle en charge ?

Le modèle d’IA sous-jacent est configuré par chatbot dans le tableau de bord. Agentkit prend en charge des modèles de trois fournisseurs : OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5) et Google (Gemini 3.7 Flash, Gemini 3.1 Pro). Le modèle par défaut est GPT-5.6 Luna. Vos appels API utilisent le modèle sélectionné pour ce chatbot — vous ne spécifiez pas le modèle au niveau de l’appel API.

Puis-je utiliser l’API du chatbot pour intégrer le chat sur mon site web ?

Oui, mais l’intégration via le widget JS est généralement plus simple pour les cas d’usage sur site web. Le widget se charge de façon asynchrone via une seule balise <script> et gère automatiquement l’interface, l’état de la conversation et le streaming. Utilisez l’API quand vous avez besoin d’une interface entièrement personnalisée, d’une intégration à une application mobile, ou d’une automatisation back-end. Pour une comparaison côte à côte de toutes les options d’intégration, consultez le guide pour intégrer un chatbot sur votre site web.

Une API de chatbot transforme une base de connaissances entraînée en un service appelable — les mêmes réponses IA qui apparaissent dans le widget sont disponibles pour tout système capable d’effectuer une requête HTTP. Que vous construisiez une interface personnalisée, automatisiez un workflow de support, ou connectiez votre chatbot à un écosystème d’outils plus large, l’API vous donne le contrôle qu’un widget préconstruit ne peut pas offrir.

Créez votre chatbot gratuitement → Aucune carte bancaire requise.