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.
Exemple : Lister les conversations
GET /v1/conversation/list HTTP/1.1 Host: api.chatbotkit.com Authorization: Token ...
Exemple : Créer une conversation
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 :
-
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.
-
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.
Exemple de streaming : Liste de conversation
Pour transmettre des données en continu à l'aide de la fonction /v1/conversation/list
vous pouvez effectuer la requête HTTP suivante :
GET /v1/conversation/list HTTP/1.1 Host: api.chatbotkit.com Authorization: Token {your_token_here} Accept: application/jsonl
Cette demande précise le Accepter
avec la valeur application/jsonl
indiquant que la réponse doit être transmise au format JSON. L'API enverra continuellement des lignes JSON jusqu'à ce que toutes les données aient été récupérées.
Exemple de flux : Jetons et événements
Streaming can also be used to receive real-time updates and events from the ChatBotKit conversational AI engine. By streaming the /v1/conversation/{conversationId}/complete
vous pouvez recevoir des jetons et d'autres événements liés à une conversation spécifique.
Pour diffuser des jetons et des événements, vous devez envoyer une requête POST à l'adresse suivante /v1/conversation/{conversationId}/complete
route. La demande doit inclure une charge utile JSON avec un élément texte
correspondant à l'entrée de l'utilisateur :
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" }
Cette demande déclenche la diffusion en continu des jetons et des événements liés à la conversation spécifiée. L'API enverra continuellement des mises à jour jusqu'à ce que la conversation soit terminée ou interrompue.
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 :
Code d'erreur | Code de statut | Description de l'erreur |
---|---|---|
BAD_REQUEST | 400 | La demande est malformée |
NON_AUTHENTIFIÉ | 401 | Non authentifié |
NOT_AUTHORIZED | 401 | Non autorisé |
PAS D'ABONNEMENT | 402 | Pas d'abonnement |
NOT_FOUND | 404 | Non trouvé |
MÉTHODE_NON_AUTORISÉE | 405 | Méthode non autorisée |
CONFLIT | 409 | Il y a un conflit lors de la gestion de la ressource |
TROP DE DEMANDES | 429 | Trop de demandes |
LIMITS_REACHED | 429 | Limites d'abonnement atteintes |
ERREUR_SERVEUR_INTERNE | 500 | Erreur de serveur interne |
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.