Bot Talk API

Bot Talk API

L'API Bot Talk 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 endpoint 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 accédez à l'onglet API en haut de la page du bot (Select Bot > API (Sélectionner le bot > API)).

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

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.

3. Dans la boîte de dialogue Create API Key, donnez un nom à la clé, définissez éventuellement une liste blanche d'adresses IP et une limite de débit, choisissez les autorisations accordées, puis cliquez sur Create (Créer).

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

Une clé ressemble à ck_abcdefghijklmnopqrstuvwxyz012345. Chaque clé appartient à ce seul bot, de sorte que chaque requête effectuée avec la clé s'adresse à ce bot - le bot est identifié par la clé et n'apparaît jamais dans l'URL.

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 : 4000 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, 4000 caractères maximum.
• conversationId - UUID facultatif. Omettez-le pour une nouvelle conversation ; réutilisez la valeur renvoyée précédemment par le serveur pour continuer une conversation existante.
• metadata - objet facultatif : {source, userName, userEmail, userPhone}. userEmail est également utilisé pour dériver l'identifiant client interne.

Corps de la réponse (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "usage": {"creditsUsed": 2},
  "actions": []
}

• message.role est toujours "assistant" ; message.content correspond à la réponse complète.
• model est l'identifiant du modèle exécuté par le bot pour cet appel.
• usage.creditsUsed prend en compte le message de l'utilisateur + la réponse du bot (généralement 2), plus un crédit supplémentaire par appel d'outil exécuté.
• actions liste les exécutions d'outils ayant eu lieu pendant ce tour. Actuellement, seules les entrées function_call sont émises (avec type, name, status: "completed").

POST /v1/chat/stream

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

Corps de la requête

Même structure que POST /v1/chat. Le paramètre stream dans le corps n'est pas requis - c'est l'utilisation de cette route qui active le SSE.

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

• message.delta - fragment de contenu { "content": "..." }. Plusieurs fragments sont diffusés au fil 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 final contenant conversationId, model, usage et (le cas échéant) la liste des actions terminées.
• error - envoyé si la génération échoue ; le flux prend fin ensuite.

Des commentaires SSE de maintien de connexion (:keepalive) sont envoyés toutes les 15 secondes lors des 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

Liste les conversations du bot associé à votre clé, toutes sources confondues (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 renvoyée dans nextCursor sur la page précédente. Omettez ce paramètre 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}

Historique complet de la conversation.

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 renvoyés ; les messages internes de type system et les messages d'outils sont filtrés. Renvoie 404 not_found_error si la conversation n'appartient pas au bot associé à votre clé.

Pour inspecter la configuration du bot, utilisez le 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 structure unique :

{
  "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 - saisie incorrecte (codes : invalid_parameter, 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 non présente dans la liste blanche de la clé (ip_not_whitelisted), ou type de clé n'autorisant pas ce endpoint (key_type_not_allowed, insufficient_permissions)
• 404 not_found_error - la conversation n'appartient pas à ce bot
• 405 invalid_request_error (method_not_allowed) - verbe HTTP incorrect 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.