API

The ChatBotKit API is a powerful tool for developers looking to integrate conversational AI functionality into their applications. This documentation provides a comprehensive guide to understanding and utilizing the various endpoints and features offered by the API. You can find the full V1 OpenAPI specification here.

Points finaux

The ChatBotKit API provides the following endpoints:

• URL de base de l'API : api.chatbotkit.com
• Version API : v1

The current version of the API, v1, can be accessed at https://api.chatbotkit.com/v1/.

Approche des ressources basée sur l'action

The ChatBotKit API follows an action-based approach to resources. Each resource within the API supports a set of available actions, including list, create, update, delete, search, and more. When interacting with an endpoint, you will need to specify the desired action by sending a POST request. However, some actions, such as list, only support GET requests. POST requests expect JSON payloads.

GET /v1/conversation/list HTTP/1.1
Host: api.chatbotkit.com
Authorization: Token ...

POST /v1/conversation/create HTTP/1.1
Host: api.chatbotkit.com
Authorization: Token ...
Content-Type: application/json

...

Autorisation

ChatBotKit prend en charge les autorisations basées sur des jetons. Pour accéder à l'API, les développeurs doivent créer des jetons à partir des outils de développement disponibles sur https://chatbotkit.com/tokens. Les jetons servent de mécanisme d'autorisation pour les appels à l'API.

Certains points de terminaison de l'API ChatBotKit peuvent générer des jetons à portée limitée. Ces jetons sont conçus pour être limités à des ressources et des actions spécifiques. Les développeurs peuvent utiliser des jetons à portée limitée pour autoriser les appels à l'API, en veillant à ce que seules les autorisations nécessaires soient accordées.

Pour autoriser un appel à l'API, incluez le jeton dans le fichier Autorisation de la demande :

Authorization: Token {your_token_here}

Veillez à remplacer {votre_token_ici} avec la valeur réelle du jeton.

Hypothèse de l'utilisateur

En plus de la Autorisation vous pouvez également passer dans l'en-tête X-RunAs-UserId si vous souhaitez basculer le contexte de la demande vers un sous-compte (également connu sous le nom de compte enfant) dans une configuration de relation de compte parent-enfant. Cela fait partie de l'en-tête API partenaire. En voici un exemple :

Authorization: Token {your_token_here}
X-RunAs-UserId: {child_user_id_here}

Veillez à remplacer les deux {votre_token_ici} et {child_user_id_here} avec les valeurs correspondantes.

Pagination

Pagination is available only on the list actions in ChatBotKit API. It is based on cursors, which provide a way to navigate through a large set of results. Cursor-based pagination allows you to retrieve a set of resources in smaller chunks, making it easier to handle large datasets.

Dans le contexte de l'API ChatBotKit, lors d'un appel de liste, l'API peut inclure un paramètre de curseur facultatif. Ce curseur correspond à l'ID de la dernière ressource de la liste précédente de ressources récupérées.

Pour utiliser la pagination basée sur le curseur avec l'option /v1/conversation/list vous pouvez effectuer les requêtes HTTP suivantes :

1. Demande initiale sans curseur :

   GET /v1/conversation/list HTTP/1.1
   Host: api.chatbotkit.com
   Authorization: Token {your_token_here}
   
   

   Cette demande renverra la première page de résultats.

2. Demandes ultérieures utilisant le paramètre du curseur :

   GET /v1/conversation/list?cursor={last_resource_id} HTTP/1.1
   Host: api.chatbotkit.com
   Authorization: Token {your_token_here}
   
   

   Remplacer {last_resource_id} avec l'identifiant de la dernière ressource de la réponse précédente. Cette demande permet d'obtenir la page suivante de résultats.

Streaming

Outre la pagination, l'API ChatBotKit prend également en charge la diffusion en continu pour certaines actions. La diffusion en continu permet à l'appelant de recevoir des données par petits morceaux et continue jusqu'à ce que le flux soit épuisé. Cela peut être utile pour extraire efficacement de grandes quantités de données de l'API.

Pour activer la diffusion en continu, l'appelant doit fournir un numéro de téléphone et un mot de passe. Accepter avec la valeur application/jsonl. Lorsque vous utilisez cette méthode de diffusion en continu, les informations provenant de l'API sont fournies dans un flux continu de lignes JSON.

GET /v1/conversation/list HTTP/1.1
Host: api.chatbotkit.com
Authorization: Token {your_token_here}
Accept: application/jsonl

POST /v1/conversation/{conversationId}/complete HTTP/1.1
Host: api.chatbotkit.com
Authorization: Token {your_token_here}
Content-Type: application/json

{
  "text": "User input goes here"
}

La diffusion en continu peut être une alternative puissante à la pagination, vous permettant de recevoir des données en temps réel et de traiter efficacement de grandes quantités d'informations.

Erreurs

La gestion des erreurs dans l'API ChatBotKit est basée sur les codes d'état HTTP. Chaque erreur correspond à un code d'état spécifique, indiquant la nature de l'erreur. Le tableau suivant résume les définitions d'erreur et les codes d'état correspondants :

Toutes les erreurs renvoyées par l'API ChatBotKit comprennent une charge utile JSON au format suivant :

{
  "message": "error message",
  "code": "error code"
}

Les message fournit une brève description de l'erreur, tandis que le champ code spécifie le code d'erreur associé à l'erreur. Cette charge utile peut aider les développeurs à identifier et à traiter les erreurs de manière appropriée lorsqu'ils intègrent l'API ChatBotKit dans leurs applications.

Erreurs liées aux limites

Dans l'API ChatBotKit, il existe une catégorie spécifique d'erreurs qui peuvent se produire lorsque tous les tokens disponibles sont épuisés. Ces erreurs sont liées aux limites et indiquent que le nombre maximum de demandes ou d'actions autorisées a été atteint.

Lorsqu'ils rencontrent ces erreurs, les développeurs peuvent recevoir l'un des codes d'état suivants :

• TROP DE DEMANDES: Ce code d'état (429) indique que la limite de débit pour les requêtes a été dépassée.
• LIMITS_REACHED: Ce code d'état (429) indique que les limites de certaines actions ou ressources ont été atteintes.

Pour gérer ces erreurs, les développeurs doivent mettre en œuvre des mécanismes appropriés de gestion des erreurs dans leurs applications. Il peut s'agir d'implémenter une logique de réessai, d'ajuster le taux de requêtes ou de contacter le fournisseur de l'API pour s'enquérir de l'augmentation des limites pour des actions ou des ressources spécifiques.

Il est important de surveiller et de gérer efficacement les limites afin de garantir une intégration harmonieuse et ininterrompue avec l'API ChatBotKit.

Codes d'erreurs de portée

Some API calls may return a scoped error. This is an error that is within a subsystem, such as remote store or a model. Scoped errors produce error codes similar to the one above but they are prefixed by the system that exhibits the error. For example, if there is a rate limited enforced by Discord, the error will be DISCORD_TOO_MANY_REQUESTS au lieu de TROP DE DEMANDES.

Il est important de noter que la plateforme ChatBotKit dispose d'une politique de relance complète pour tous les services en amont avec lesquels elle interagit. Nous nous efforçons de répondre à toutes les demandes, quelle que soit la situation. Dans de rares circonstances, toutes les demandes peuvent échouer. Dans ce cas, nous renverrons une erreur de portée.

Caractéristiques

L'API ChatBotKit offre une gamme de fonctions puissantes qui améliorent la fonctionnalité et les capacités des applications d'IA conversationnelle. Ces fonctionnalités permettent aux développeurs de créer des chatbots et des assistants virtuels interactifs et attrayants, capables de gérer des dialogues complexes et de fournir des réponses pertinentes.

Continuations

La fonction de continuation de l'API ChatBotKit est un outil puissant qui permet à n'importe quel modèle limité avec une taille de contexte limitée de continuer à diffuser indéfiniment. Grâce à cette fonctionnalité, les développeurs peuvent surmonter les contraintes liées à la taille du contexte et générer de manière transparente des réponses qui conservent leur consistance et leur cohérence au cours de conversations prolongées.

En utilisant la fonction de continuation, les développeurs peuvent étendre la conversation au-delà des limites contextuelles du modèle, garantissant ainsi un flux de dialogue fluide et ininterrompu. Cette fonction est particulièrement utile dans les scénarios où il est crucial de maintenir le contexte et de générer des réponses cohérentes au cours de longues conversations.

La fonction de continuation permet aux développeurs de créer des expériences d'IA conversationnelle plus interactives et engageantes. Elle ouvre la voie à la création de chatbots et d'assistants virtuels capables de gérer des dialogues complexes et de fournir des réponses pertinentes, quelle que soit la longueur ou la complexité de la conversation.

Rapprochement des jetons

The ChatBotKit API includes a powerful feature called token reconciliation, which automatically adjusts messages and conversations to fit perfectly within the maximum allowed context size. This feature is particularly useful when working with models that have limitations on the number of tokens they can process.

Lorsqu'une conversation ou un message dépasse la taille maximale autorisée du contexte, l'API applique intelligemment différentes stratégies en fonction du modèle utilisé. Ces stratégies garantissent que la conversation reste cohérente et homogène, même lorsqu'il s'agit d'interactions longues ou complexes.

En tirant parti de la réconciliation des jetons, les développeurs peuvent en toute confiance créer des expériences d'IA conversationnelle qui gèrent de manière transparente les conversations prolongées. Cette fonctionnalité élimine le besoin de tronquer ou de modifier manuellement les messages pour les adapter aux limites du contexte, ce qui permet un flux de dialogue plus rationalisé et plus naturel.

Que vous travailliez avec des modèles soumis à des contraintes strictes en matière de jetons ou que vous souhaitiez simplement garantir des performances optimales, la réconciliation des jetons dans l'API ChatBotKit constitue une solution fiable pour gérer la taille du contexte et générer des réponses de haute qualité.

Agents et tâches d'arrière-plan

L'une des puissantes fonctionnalités de ChatBotKit est sa capacité à gérer des agents d'intelligence artificielle et des tâches d'arrière-plan. Grâce à cette fonctionnalité, ChatBotKit peut exécuter de manière transparente des processus longs qui peuvent prendre plusieurs minutes. Cette capacité est particulièrement utile pour mener des interactions en plusieurs étapes avec un bot et effectuer des tâches complexes en utilisant différents ensembles de compétences.

En utilisant des agents et des tâches d'arrière-plan, les développeurs peuvent créer des expériences d'IA conversationnelle qui vont au-delà de simples interactions de type question-réponse. Le robot peut effectuer des tâches qui comportent plusieurs étapes et nécessitent du temps, comme la récupération d'informations à partir de sources externes, le traitement de grands ensembles de données ou l'exécution d'algorithmes complexes.

Cette fonctionnalité permet au bot de traiter des demandes complexes d'utilisateurs qui dépassent les capacités des chatbots traditionnels. Elle permet des conversations plus complexes et plus dynamiques, offrant aux utilisateurs une expérience plus riche et plus interactive.

Métadonnées

Chaque ressource - qu'il s'agisse d'un bot, d'un ensemble de données, d'un ensemble de compétences, d'une conversation, d'un contact ou d'un autre type - peut être associée à des métadonnées représentées sous la forme d'un objet JSON. Vous pouvez attribuer des métadonnées en utilisant simplement la fonction méta . Il est important de noter que lors de la mise à jour d'une ressource, la propriété metadata override remplacera toutes les métadonnées existantes déjà stockées. Pour tenir compte des mises à jour partielles, l'API prend en charge un format spécial pour la modification des métadonnées.

Pour créer ou remplacer complètement les métadonnées, utilisez la syntaxe suivante :

{
  "meta": {
    "field1": "string",
    "field2": true
  }
}

Pour ne mettre à jour que des champs spécifiques des métadonnées, utilisez la syntaxe suivante :

{
  "$update": {
    "field2": false
  }
}

Spécification API

La spécification complète de l'API ChatBotKit est disponible au format OpenAPI. Vous pouvez accéder à la spécification de l'API à l'adresse https://api.chatbotkit.com/v1/spec.json.

Pour une expérience plus interactive, vous pouvez consulter la spécification de l'API à l'adresse https://chatbotkit.com/docs/api/v1/spec. Cette documentation fournit des informations détaillées sur chaque point de terminaison, y compris des exemples de demandes et de réponses, des descriptions de paramètres, etc.

Node SDK

The ChatBotKit Node SDK is a software development kit specifically designed for developers working with Node.js. This SDK provides a comprehensive set of tools and libraries that simplify the integration of the ChatBotKit API into Node.js applications.

Avec Node SDK, les développeurs peuvent facilement exploiter les puissantes fonctionnalités de l'API ChatBotKit sans avoir à gérer manuellement les demandes et les réponses HTTP de bas niveau. Le SDK fait abstraction des complexités de la communication API, ce qui permet aux développeurs de se concentrer sur l'intégration de fonctionnalités d'IA conversationnelle dans leurs applications.

Pour commencer à utiliser le ChatBotKit Node SDK, consultez la documentation complète disponible à l'adresse https://chatbotkit.com/docs/node-sdk. Cette documentation fournit des instructions détaillées sur la manière d'installer le SDK, de s'authentifier auprès de l'API et d'effectuer divers appels API à l'aide des méthodes et fonctions intuitives du SDK.