Centre d'aide
Chat API

Bot Talk API

Dernière mise à jour:

Bot Talk API

Bot Talk API est une API REST permettant de communiquer avec un chatbot spécifique depuis votre propre application - applications personnalisées, outils internes ou automatisations que vous développez vous-même. Vous créez une clé API dans l'onglet API du bot, puis vous appelez le point de terminaison de chat avec la clé sous forme de token Bearer pour obtenir les réponses du bot, soit en une seule réponse, soit en continu via SSE.

Premiers pas

  1. Sélectionnez votre chatbot et rendez-vous dans l'onglet API en haut de la page du bot (Select Bot > API - Sélectionner un bot > API).

Onglet Bot Talk API

  1. Cliquez sur Create API Key (Créer une clé API).

Onglet API mis en évidence ; Create API Key se trouve dans le contenu de la page

Le compteur à côté du bouton indique le nombre de clés actives (« 1 of 5 API keys active »). Le lien View API Documentation (Voir la documentation de l'API) ouvre cette référence, et l'extrait curl Quick Start (Démarrage rapide) vous fournit un exemple prêt à l'emploi.

  1. Dans la boîte de dialogue Create API Key, donnez un nom à la clé, définissez éventuellement une liste blanche d'adresses IP ainsi qu'une limite de débit (rate limit), choisissez ses autorisations, puis cliquez sur Create (Créer).

Boîte de dialogue Create API Key

  1. Copiez la clé complète depuis la boîte de dialogue de confirmation. Le texte brut n'est affiché qu'une seule fois.

Une clé ressemble à ck_abcdefghijklmnopqrstuvwxyz012345. Chaque clé appartient à ce bot spécifique, donc chaque requête effectuée avec la clé communique avec ce bot - le bot est identifié par la clé et n'apparaît jamais dans l'URL.

  1. Depuis votre serveur, exécutez l'exemple curl ci-dessous avec votre clé et un court message de test. Conservez le conversationId renvoyé, puis réutilisez-le pour le message suivant. Confirmez la réponse et la conversation dans l'onglet Chatlogs (Journaux de chat) du bot.

Gardez les clés ck_ sur votre serveur, et non dans le JavaScript d'un site web ou les paquets d'une application mobile. Une autorisation Conversations donne accès à l'historique des conversations conservées de ce bot pour l'ensemble des visiteurs ; votre application doit donc autoriser chaque utilisateur final avant de renvoyer ces données. Utilisez Revoke (Révoquer) ou Delete (Supprimer) dans l'onglet API pour désactiver une clé ; aucune de ces actions n'affiche à nouveau son texte brut.

Avant de commencer, créez et entraînez votre chatbot et vérifiez que votre compte comprend l'accès à l'API et dispose de crédits de messages.

URL de base

https://api.chatlab.com/aichat

Tous les endpoints mentionnés dans cet article sont relatifs à cette URL de base.

Autorisations de clé

Chaque clé dispose de l'une de ces autorisations ou des deux, définies à l'aide des boutons à bascule dans la boîte de dialogue Create API Key :

  • Chat (send messages and receive responses) (Chat (envoyer des messages et recevoir des réponses)) - autorise les endpoints /v1/chat et /v1/chat/stream.
  • Conversation history (list and read past conversations) (Historique des conversations (lister et lire les conversations passées)) - autorise les endpoints /v1/conversations.

L'onglet API affiche les autorisations accordées à chaque clé sous forme de badges Chat et Conversations.

Authentification

Envoyez la clé dans l'en-tête Authorization à chaque requête :

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Les requêtes sans en-tête Authorization: Bearer ... renvoient 401 missing_api_key. Les clés inconnues renvoient 401 invalid_api_key ; les clés révoquées renvoient 401 revoked_api_key. Cinq tentatives invalides en une minute depuis la même adresse IP déclenchent un blocage de 60 minutes.

Limites

  • 5 clés Bot Talk actives au maximum par bot
  • 60 requêtes par minute au maximum par clé (token bucket, capacité de 60, réapprovisionnement régulier à 1 jeton par seconde). Configurable à la baisse lors de la création - définissez un rateLimitPerMinute inférieur et le plafond diminuera, la vitesse de réapprovisionnement s'ajustant en conséquence.
  • Longueur maximale du message : 4 000 caractères
  • Les flux SSE simultanés par clé sont soumis aux limites de votre compte

Endpoints

POST /v1/chat

Envoyez un message au bot et recevez la réponse complète dans une seule réponse JSON.

Corps de la requête

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - chaîne requise, 4 000 caractères max.
  • conversationId - UUID optionnel. Omettez-le pour une nouvelle conversation ; réutilisez la valeur retournée précédemment par le serveur pour ajouter le message à une conversation existante.
  • metadata - objet optionnel acceptant {source, userName, userEmail, userPhone}. Actuellement, seul userEmail est utilisé ici, pour dériver l'identifiant client ; le canal est enregistré en tant qu'API. Ne comptez pas sur l'enregistrement des autres champs de métadonnées dans une fiche de lead.

Corps de la réponse (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role est toujours "assistant" ; message.content est la réponse complète.
  • model est l'identifiant du modèle sur lequel le bot a tourné pour cet appel.
  • usage.creditsUsed indique actuellement 2 plus un par appel d'outil signalé pour un tour terminé. Ce compteur de réponse n'inclut pas les multiplicateurs de crédits modèle/contexte et ne doit pas servir de registre de facturation. Utilisez Données de consommation via Management API pour la consommation du compte et consultez les crédits de message.
  • actions liste les exécutions d'outils ayant tourné pendant ce tour. Aujourd'hui, seules les entrées function_call sont émises (avec type, name, status: "completed").

POST /v1/chat/stream

Variante en streaming de /v1/chat. Retourne Content-Type: text/event-stream avec des événements Server-Sent Events.

Corps de la requête

Même structure que POST /v1/chat. L'indicateur stream dans le corps n'est pas requis - c'est l'utilisation de ce chemin qui déclenche le SSE.

Corps de la réponse (événements SSE)

  • message.reset - supprimez le texte accumulé pour la réponse actuelle et recommencez à collecter les deltas. Cela peut se produire lorsque la génération redémarre ; ajouter les deux versions afficherait une réponse dupliquée ou obsolète.
  • message.delta - fragment de contenu { "content": "..." }. Plusieurs d'entre eux sont transmis en flux au fur et à mesure de l'arrivée des tokens.
  • action - exécution d'outil { "type", "name", "status": "executing" }. Émis lorsque le bot déclenche un appel de fonction.
  • message.done - événement terminal avec conversationId, model, usage, et (le cas échéant) la liste actions terminée.
  • error - envoyé si la génération échoue ; le flux se termine ensuite.

Des commentaires SSE keep-alive (:keepalive) sont envoyés toutes les 15 secondes pendant les générations longues. Délais d'expiration côté serveur : 30 secondes pour le premier token, 120 secondes au total par flux.

Exemple cURL

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Listez les conversations pour le bot associé à votre clé, sur toutes les sources (widget, WhatsApp, API, etc.).

Paramètres d'URL

  • limit - 1-100, valeur par défaut 20. Les valeurs hors plage sont ajustées.
  • cursor - valeur opaque retournée dans nextCursor sur la page précédente. Omettez-la pour la première page.

Corps de la réponse (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview est tronqué à 100 caractères avec un suffixe ....
  • nextCursor est null sur la dernière page ; transmettez-le comme cursor pour récupérer la suivante.

GET /v1/conversations/{conversation_id}

Messages de conversation conservés exposés par cet endpoint.

Corps de la réponse (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Seuls les rôles user et assistant sont retournés ; les messages internes system et d'outils sont filtrés. Retourne 404 not_found_error si la conversation n'appartient pas au bot associé à votre clé.

Pour inspecter la configuration du bot, utilisez l'endpoint de la Management API GET /v1/management/bots/{bot_id} avec une clé Management.

En-têtes de limitation de débit

Les réponses qui atteignent l'étape de limitation de débit (c'est-à-dire une fois l'authentification et la liste blanche d'IP validées) incluent :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - le plafond par clé réellement appliqué à cet appel (60 par défaut, ou votre rateLimitPerMinute configuré s'il est inférieur).
  • X-RateLimit-Remaining - jetons restants dans le compartiment immédiatement après cet appel.
  • X-RateLimit-Reset - horodatage Unix en secondes auquel le prochain jeton devient disponible (il ne s'agit pas d'une réinitialisation complète du compartiment ; celui-ci se remplit en continu). Lorsque le compartiment est plein, cela correspond à l'heure actuelle.

Sur les réponses 429 rate_limit_exceeded, l'en-tête Retry-After est également présent, exprimé en secondes entières jusqu'à ce qu'au moins un jeton se libère.

Les erreurs préalables à l'authentification (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) et 403 ip_not_whitelisted ne comportent pas les en-têtes X-RateLimit-* - le limiteur n'est sollicité qu'une fois les vérifications d'authentification et d'adresse IP réussies.

Format des erreurs

Toutes les erreurs partagent une même structure :

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Codes HTTP courants :

  • 400 invalid_request_error - entrée malformée (invalid_parameter)
  • 415 invalid_request_error - type de contenu non pris en charge (unsupported_media_type)
  • 401 authentication_error - clé manquante (missing_api_key), clé inconnue (invalid_api_key) ou clé révoquée (revoked_api_key)
  • 402 quota_exceeded_error - crédits de messages épuisés
  • 403 permission_error - IP bloquée (ip_blocked), IP absente de la liste blanche de la clé (ip_not_whitelisted) ou type de clé n'autorisant pas ce point de terminaison (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - la conversation n'appartient pas à ce bot
  • 405 invalid_request_error (method_not_allowed) - mauvais verbe HTTP sur l'URL
  • 429 rate_limit_error - trop de requêtes (rate_limit_exceeded) ou trop de flux simultanés (concurrent_streams_exceeded)
  • 500 api_error - erreur interne

Articles connexes

Pour les opérations au niveau du compte (création de bots, mise à jour de bots, consultation de la consommation), consultez la page Management API.

Rechercher dans tous les articlesDemander à l'agent