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.

Puntos finales

The ChatBotKit API provides the following endpoints:

• URL base de la API: api.chatbotkit.com
• Versión API: v1

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

Enfoque de los recursos basado en la acción

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

...

Autorización

ChatBotKit admite la autorización basada en tokens. Para acceder a la API, los desarrolladores deben crear tokens desde las herramientas para desarrolladores disponibles en https://chatbotkit.com/tokens. Los tokens sirven como mecanismo de autorización para realizar llamadas a la API.

Algunos puntos finales de la API de ChatBotKit pueden generar tokens de alcance. Estos tokens están diseñados para limitarse a recursos y acciones específicos. Los desarrolladores pueden utilizar tokens de alcance para autorizar llamadas a la API, asegurándose de que sólo se conceden los permisos necesarios.

Para autorizar una llamada a la API, incluya el token en el campo Autorización de la solicitud:

Authorization: Token {your_token_here}

Asegúrese de sustituir {your_token_here} con el valor real del token.

Suposición del usuario

Además del Autorización también puede introducir X-RunAs-UserId si desea cambiar el contexto de solicitud a una subcuenta (también conocida como cuenta secundaria) en una configuración de relación de cuenta padre-hijo. Esto forma parte del API de socios. He aquí un ejemplo:

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

Asegúrese de sustituir ambos {your_token_here} y {child_user_id_here} con los valores correspondientes.

Paginación

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.

En el contexto de la API ChatBotKit, al realizar una llamada a una lista, la API puede incluir un parámetro de cursor opcional. Este cursor corresponde al ID del último recurso de la lista anterior de recursos recuperados.

Para utilizar la paginación basada en el cursor con la función /v1/conversación/lista puede realizar las siguientes peticiones HTTP:

1. Petición inicial sin cursor:

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

   Esta petición devolverá la primera página de resultados.

2. Solicitudes posteriores utilizando el parámetro cursor:

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

   Sustituir {last_resource_id} con el ID del último recurso de la respuesta anterior. Esta petición recuperará la siguiente página de resultados.

Streaming

Además de la paginación, la API de ChatBotKit también admite el streaming para determinadas acciones. El streaming permite a la persona que llama recibir datos en trozos del tamaño de un bocado y continúa hasta que el flujo se agota. Esto puede ser útil para obtener grandes cantidades de datos de la API.

Para activar la transmisión en flujo continuo, la persona que llama debe proporcionar un Acepte con el valor application/jsonl. Al utilizar este método de streaming, la información de la API se entregará en un flujo continuo de líneas 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"
}

El streaming puede ser una potente alternativa a la paginación, ya que permite recibir datos en tiempo real y manejar con eficacia grandes cantidades de información.

Errores

La gestión de errores en la API de ChatBotKit se basa en los códigos de estado HTTP. Cada error corresponde a un código de estado específico, que indica la naturaleza del error. La siguiente tabla proporciona un resumen de las definiciones de error y sus códigos de estado correspondientes:

Todos los errores devueltos por la API ChatBotKit incluyen una carga útil JSON con el siguiente formato:

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

En mensaje proporciona una breve descripción del error, mientras que el campo código especifica el código de error asociado al error. Esta carga útil puede ayudar a los desarrolladores a identificar y gestionar adecuadamente los errores al integrar la API de ChatBotKit en sus aplicaciones.

Errores relacionados con los límites

En la API de ChatBotKit, hay una clase específica de errores que pueden producirse cuando se agotan todos los tokens disponibles. Estos errores están relacionados con los límites e indican que se ha alcanzado el número máximo de solicitudes o acciones permitidas.

Al encontrarse con estos errores, los desarrolladores pueden recibir uno de los siguientes códigos de estado:

• DEMASIADAS_SOLICITUDES: Este código de estado (429) indica que se ha superado el límite de velocidad para realizar peticiones.
• LÍMITES ALCANZADOS: Este código de estado (429) indica que se han alcanzado los límites para determinadas acciones o recursos.

Para gestionar estos errores, los desarrolladores deben implementar mecanismos de gestión de errores adecuados en sus aplicaciones. Esto puede implicar implementar una lógica de reintento, ajustar el ritmo de las solicitudes o ponerse en contacto con el proveedor de la API para informarse sobre el aumento de los límites para acciones o recursos específicos.

Es importante controlar y gestionar eficazmente los límites para garantizar una integración fluida e ininterrumpida con la API de ChatBotKit.

Códigos de errores de alcance

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 en lugar de DEMASIADAS_SOLICITUDES.

Es importante tener en cuenta que la plataforma ChatBotKit tiene una política de reintentos exhaustiva para todos los servicios ascendentes con los que interactúa. Intentaremos satisfacer todas y cada una de las solicitudes sin importar la situación. En raras circunstancias, todas las solicitudes pueden fallar. En ese caso, devolveremos un error de alcance.

Características

La API ChatBotKit ofrece una serie de potentes características que mejoran la funcionalidad y las capacidades de las aplicaciones de IA conversacional. Estas funciones permiten a los desarrolladores crear chatbots y asistentes virtuales interactivos y atractivos que pueden manejar diálogos complejos y ofrecer respuestas significativas.

Continuaciones

La función de continuación de la API de ChatBotKit es una potente herramienta que permite que cualquier modelo limitado con un tamaño de contexto limitado continúe transmitiendo indefinidamente. Con esta función, los desarrolladores pueden superar las limitaciones del tamaño del contexto y generar sin problemas respuestas que mantengan la consistencia y la coherencia en conversaciones prolongadas.

Utilizando la función de continuación, los desarrolladores pueden extender la conversación más allá de las limitaciones contextuales del modelo, garantizando un flujo de diálogo fluido e ininterrumpido. Esto resulta especialmente útil en situaciones en las que es crucial mantener el contexto y generar respuestas coherentes en conversaciones largas.

La función de continuación permite a los desarrolladores crear experiencias de IA conversacional más interactivas y atractivas. Abre posibilidades para crear chatbots y asistentes virtuales que puedan manejar diálogos complejos y ofrecer respuestas significativas, independientemente de la duración o la complejidad de la conversación.

Conciliación de fichas

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.

Cuando una conversación o un mensaje superan el tamaño de contexto máximo permitido, la API aplica de forma inteligente diferentes estrategias en función del modelo que se esté utilizando. Estas estrategias garantizan que la conversación siga siendo coherente y consistente, incluso cuando se trata de interacciones largas o complejas.

Al aprovechar la reconciliación de tokens, los desarrolladores pueden crear con confianza experiencias de IA conversacional que gestionen sin problemas conversaciones extensas. Esta función elimina la necesidad de truncar o modificar manualmente los mensajes para ajustarlos a las limitaciones del contexto, lo que permite un flujo de diálogo más ágil y natural.

Tanto si trabaja con modelos que tienen restricciones estrictas de tokens como si simplemente desea garantizar un rendimiento óptimo, la reconciliación de tokens en la API de ChatBotKit proporciona una solución fiable para gestionar el tamaño del contexto y generar respuestas de alta calidad.

Agentes y tareas en segundo plano

Una de las potentes características de ChatBotKit es su capacidad para manejar agentes de IA y tareas en segundo plano. Con esta funcionalidad, ChatBotKit puede realizar sin problemas procesos largos que pueden tardar minutos en completarse. Esta capacidad es especialmente útil para llevar a cabo interacciones de varios pasos con un bot y realizar tareas complejas utilizando varios conjuntos de habilidades.

Utilizando agentes y tareas en segundo plano, los desarrolladores pueden crear experiencias de IA conversacional que van más allá de las simples interacciones de pregunta y respuesta. El bot puede realizar tareas que implican múltiples pasos y requieren tiempo para completarse, como recuperar información de fuentes externas, procesar grandes conjuntos de datos o ejecutar algoritmos complejos.

Esta funcionalidad permite al bot gestionar peticiones complejas de los usuarios que van más allá de las capacidades de los chatbots tradicionales. Permite conversaciones más intrincadas y dinámicas, proporcionando a los usuarios una experiencia más rica e interactiva.

Metadatos

Cada recurso -ya sea un bot, un conjunto de datos, un conjunto de habilidades, una conversación, un contacto u otros tipos- puede tener metadatos asociados representados como un objeto JSON. Puedes asignar metadatos simplemente utilizando la función meta propiedad. Es importante tener en cuenta que al actualizar un recurso, la propiedad de modificación de metadatos sustituirá a cualquier metadato existente ya almacenado. Para dar cabida a las actualizaciones parciales, la API admite un formato especial para modificar los metadatos.

Para crear o sustituir completamente los metadatos, utilice la siguiente sintaxis:

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

Para actualizar sólo campos específicos dentro de los metadatos, utilice esta sintaxis:

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

Especificación API

La especificación completa de la API ChatBotKit está disponible en formato OpenAPI. Puede acceder a la especificación de la API en https://api.chatbotkit.com/v1/spec.json.

Para una experiencia más interactiva, puede explorar la especificación de la API en https://chatbotkit.com/docs/api/v1/spec. Esta documentación proporciona información detallada sobre cada punto final, incluidos ejemplos de solicitud y respuesta, descripciones de parámetros, 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.

Con Node SDK, los desarrolladores pueden aprovechar fácilmente las potentes funciones de la API ChatBotKit sin tener que gestionar manualmente las solicitudes y respuestas HTTP de bajo nivel. El SDK abstrae las complejidades de la comunicación de la API, lo que permite a los desarrolladores centrarse en crear funcionalidades de IA conversacional en sus aplicaciones.

Para empezar a utilizar ChatBotKit Node SDK, consulte la documentación completa disponible en https://chatbotkit.com/docs/node-sdk. Esta documentación proporciona instrucciones detalladas sobre cómo instalar el SDK, autenticarse con la API y realizar varias llamadas a la API utilizando los métodos y funciones intuitivos del SDK.