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.

Pontos finais

The ChatBotKit API provides the following endpoints:

• URL da base da API: api.chatbotkit.com
• Versão da API: v1

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

Abordagem de recursos baseada em ações

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

...

Autorização

O ChatBotKit oferece suporte à autorização baseada em token. Para acessar a API, os desenvolvedores precisam criar tokens a partir das ferramentas de desenvolvedor disponíveis em https://chatbotkit.com/tokens. Os tokens funcionam como o mecanismo de autorização para fazer chamadas para a API.

Alguns pontos de extremidade na API do ChatBotKit podem gerar tokens com escopo. Esses tokens são projetados para serem limitados a recursos e ações específicos. Os desenvolvedores podem usar tokens com escopo para autorizar chamadas para a API, garantindo que somente as permissões necessárias sejam concedidas.

Para autorizar uma chamada à API, inclua o token no Autorização da solicitação:

Authorization: Token {your_token_here}

Certifique-se de substituir {seu_token_aqui} com o valor real do token.

Suposição do usuário

Além do Autorização você também pode passar o cabeçalho X-RunAs-UserId se você quiser mudar o contexto da solicitação para uma subconta (também conhecida como conta filha) em uma configuração de relacionamento de conta pai-filho. Isso faz parte do cabeçalho API do parceiro. Aqui está um exemplo:

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

Certifique-se de substituir ambos {seu_token_aqui} e {child_user_id_here} com os valores correspondentes.

Paginação

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.

No contexto da API do ChatBotKit, ao fazer uma chamada de lista, a API pode incluir um parâmetro de cursor opcional. Esse cursor corresponde à ID do último recurso da lista anterior de recursos recuperados.

Para usar a paginação baseada em cursor com o /v1/conversation/list você pode fazer as seguintes solicitações HTTP:

1. Solicitação inicial sem um cursor:

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

   Essa solicitação retornará a primeira página de resultados.

2. Solicitações subsequentes usando o parâmetro cursor:

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

   Substituir {last_resource_id} com o ID do último recurso da resposta anterior. Essa solicitação recuperará a próxima página de resultados.

Transmissão em fluxo contínuo

Além da paginação, a API do ChatBotKit também suporta streaming para determinadas ações. O streaming permite que o chamador receba dados em pedaços pequenos e continue até que o fluxo se esgote. Isso pode ser útil para extrair com eficiência grandes quantidades de dados da API.

Para ativar o streaming, o chamador deve fornecer um Aceitar com o valor aplicativo/jsonl. Ao usar esse método de streaming, as informações da API serão fornecidas em um fluxo contínuo de linhas 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"
}

O streaming pode ser uma alternativa eficiente à paginação, permitindo que você receba dados em tempo real e manipule com eficiência grandes quantidades de informações.

Erros

O tratamento de erros na API do ChatBotKit é baseado em códigos de status HTTP. Cada erro corresponde a um código de status específico, indicando a natureza do erro. A tabela a seguir fornece um resumo das definições de erro e seus códigos de status correspondentes:

Todos os erros retornados pela API do ChatBotKit incluem um payload JSON no seguinte formato:

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

O mensagem fornece uma breve descrição do erro, enquanto o campo código especifica o código de erro associado ao erro. Essa carga útil pode ajudar os desenvolvedores a identificar e tratar os erros adequadamente ao integrar a API do ChatBotKit em seus aplicativos.

Erros relacionados a limites

Na API do ChatBotKit, há uma classe específica de erros que podem ocorrer quando todos os tokens disponíveis estão no máximo. Esses erros estão relacionados a limites e indicam que o número máximo de solicitações ou ações permitidas foi atingido.

Ao encontrar esses erros, os desenvolvedores podem receber um dos seguintes códigos de status:

• MUITOS_PEDIDOS: Esse código de status (429) indica que o limite de taxa para fazer solicitações foi excedido.
• LIMITS_REACHHED: Esse código de status (429) indica que os limites de determinadas ações ou recursos foram atingidos.

Para lidar com esses erros, os desenvolvedores devem implementar mecanismos adequados de tratamento de erros em seus aplicativos. Isso pode envolver a implementação da lógica de repetição, o ajuste da taxa de solicitações ou o contato com o provedor de API para obter informações sobre o aumento dos limites de ações ou recursos específicos.

É importante monitorar e gerenciar os limites de forma eficaz para garantir uma integração tranquila e ininterrupta com a API do ChatBotKit.

Códigos de erros de escopo

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 em vez de MUITOS_PEDIDOS.

É importante observar que a plataforma ChatBotKit tem uma política de repetição abrangente para todos os serviços upstream com os quais interage. Tentaremos atender a todas as solicitações, independentemente da situação. Em raras circunstâncias, todas as solicitações podem falhar. Nesse caso, retornaremos um erro de escopo.

Recursos

A API do ChatBotKit oferece uma série de recursos avançados que aprimoram a funcionalidade e os recursos dos aplicativos de IA de conversação. Esses recursos permitem que os desenvolvedores criem chatbots e assistentes virtuais interativos e envolventes que podem lidar com diálogos complexos e fornecer respostas significativas.

Continuações

O recurso de continuação na API do ChatBotKit é uma ferramenta avançada que permite que qualquer modelo limitado com um tamanho de contexto limitado continue a transmitir indefinidamente. Com esse recurso, os desenvolvedores podem superar as restrições do tamanho do contexto e gerar respostas perfeitas que mantêm a consistência e a coerência em conversas prolongadas.

Ao utilizar o recurso de continuação, os desenvolvedores podem estender a conversa para além das limitações de contexto do modelo, garantindo um fluxo de diálogo suave e ininterrupto. Isso é particularmente útil em cenários em que é fundamental manter o contexto e gerar respostas coerentes em conversas longas.

O recurso de continuação permite que os desenvolvedores criem experiências de IA de conversação mais interativas e envolventes. Ele abre possibilidades para a criação de chatbots e assistentes virtuais que podem lidar com diálogos complexos e fornecer respostas significativas, independentemente da duração ou da complexidade da conversa.

Reconciliação de tokens

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.

Quando uma conversa ou mensagem excede o tamanho máximo permitido do contexto, a API aplica de forma inteligente diferentes estratégias, dependendo do modelo que está sendo usado. Essas estratégias garantem que a conversa permaneça coerente e consistente, mesmo ao lidar com interações longas ou complexas.

Ao aproveitar a reconciliação de tokens, os desenvolvedores podem criar com confiança experiências de IA conversacional que lidam perfeitamente com conversas estendidas. Esse recurso elimina a necessidade de truncar ou modificar manualmente as mensagens para que se ajustem às limitações do contexto, permitindo um fluxo de diálogo mais simplificado e natural.

Se você está trabalhando com modelos que têm restrições rigorosas de token ou simplesmente deseja garantir o desempenho ideal, a reconciliação de token na API do ChatBotKit oferece uma solução confiável para gerenciar o tamanho do contexto e gerar respostas de alta qualidade.

Agentes e tarefas em segundo plano

Um dos recursos poderosos do ChatBotKit é sua capacidade de lidar com agentes de IA e tarefas em segundo plano. Com essa funcionalidade, o ChatBotKit pode executar sem problemas processos longos que podem levar minutos para serem concluídos. Esse recurso é especialmente útil para realizar interações em várias etapas com um bot e executar tarefas complexas utilizando vários conjuntos de habilidades.

Ao utilizar agentes e tarefas em segundo plano, os desenvolvedores podem criar experiências de IA conversacional que vão além das simples interações de perguntas e respostas. O bot pode executar tarefas que envolvem várias etapas e exigem tempo para serem concluídas, como a recuperação de informações de fontes externas, o processamento de grandes conjuntos de dados ou a execução de algoritmos complexos.

Essa funcionalidade permite que o bot lide com solicitações complexas do usuário que vão além dos recursos dos chatbots tradicionais. Ela permite conversas mais complexas e dinâmicas, proporcionando aos usuários uma experiência mais rica e interativa.

Metadados

Cada recurso, seja ele um bot, conjunto de dados, conjunto de habilidades, conversa, contato ou outros tipos, pode ter metadados associados representados como um objeto JSON. Você pode atribuir metadados simplesmente usando a função meta propriedade. É importante observar que, ao atualizar um recurso, a propriedade de substituição de metadados substituirá todos os metadados existentes já armazenados. Para acomodar atualizações parciais, a API oferece suporte a um formato especial para modificar metadados.

Para criar ou substituir completamente os metadados, use a seguinte sintaxe:

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

Para atualizar apenas campos específicos nos metadados, use esta sintaxe:

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

Especificação da API

A especificação completa da API do ChatBotKit está disponível no formato OpenAPI. Você pode acessar a especificação da API em https://api.chatbotkit.com/v1/spec.json.

Para uma experiência mais interativa, você pode explorar a especificação da API em https://chatbotkit.com/docs/api/v1/spec. Essa documentação fornece informações detalhadas sobre cada endpoint, incluindo exemplos de solicitações e respostas, descrições de parâmetros e muito mais.

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.

Com o Node SDK, os desenvolvedores podem aproveitar facilmente os recursos avançados da API do ChatBotKit sem precisar lidar manualmente com solicitações e respostas HTTP de baixo nível. O SDK abstrai as complexidades da comunicação da API, permitindo que os desenvolvedores se concentrem na criação da funcionalidade de IA conversacional em seus aplicativos.

Para começar a usar o ChatBotKit Node SDK, consulte a documentação completa disponível em https://chatbotkit.com/docs/node-sdk. Essa documentação fornece instruções detalhadas sobre como instalar o SDK, autenticar com a API e fazer várias chamadas de API usando os métodos e funções intuitivos do SDK.