←обратно към документацията

API

API на ChatBotKit е мощен инструмент за разработчици, които искат да интегрират функционалност на разговорен изкуствен интелект в своите приложения. Тази документация предоставя изчерпателно ръководство за разбиране и използване на различните крайни точки и функции, предлагани от 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.

Крайни точки

The ChatBotKit API provides the following endpoints:

  • Базов URL на API: api.chatbotkit.com
  • Версия на API: v1

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

Подход към ресурсите, основан на действия

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

...

Оторизация

ChatBotKit поддържа оторизация, базирана на токени. За да получат достъп до API, разработчиците трябва да създадат токени от инструментите за разработчици, налични на адрес https://chatbotkit.com/tokens. Токените служат като механизъм за оторизация за извършване на повиквания към API.

Някои крайни точки в приложния програмен интерфейс ChatBotKit могат да генерират ограничени токени. Тези токени са предназначени да бъдат ограничени до определени ресурси и действия. Разработчиците могат да използват scoped токени, за да оторизират повикванията към API, като гарантират, че се предоставят само необходимите разрешения.

За да оторизирате повикване към API, включете токена в Оторизация заглавието на заявката:

Authorization: Token {your_token_here}

Уверете се, че сте заменили {your_token_here} с действителната стойност на токена.

Предположение на потребителя

В допълнение към Оторизация можете също така да подадете X-RunAs-UserId ако искате да превключите контекста на заявката към подсметка (известна също като дъщерна сметка) в конфигурация на взаимоотношенията родител-дете. Това е част от Партньорски API. Ето един пример:

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

Уверете се, че сте заменили двете {your_token_here} и {child_user_id_here} със съответните стойности.

Страница

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.

В контекста на ChatBotKit API, когато се извършва извикване на списък, API може да включва незадължителен параметър курсор. Този курсор съответства на идентификатора на последния ресурс от предишния извлечен списък с ресурси.

За да използвате страниране, базирано на курсора, с /v1/conversation/list можете да направите следните HTTP заявки:

  1. Първоначална заявка без курсор:

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

    Тази заявка ще върне първата страница с резултати.

  2. Следващи заявки, използващи параметъра курсор:

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

    Замяна на {last_resource_id} с ID на последния ресурс от предишния отговор. Тази заявка ще извлече следващата страница с резултати.

Стрийминг

В допълнение към странирането ChatBotKit API поддържа и поточно предаване за определени действия. Потокът позволява на викащия да получава данни на части и продължава, докато потокът се изчерпи. Това може да бъде полезно за ефективно извличане на големи количества данни от API.

За да активирате стрийминг, повикващият трябва да предостави Приемане на заглавие със стойност application/jsonl. Когато използвате този метод за поточно предаване, информацията от API ще се предоставя в непрекъснат поток от JSON редове.

Пример за стрийминг: Списък с разговори

Поточно предаване на данни с помощта на /v1/conversation/list можете да направите следната HTTP заявка:

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

В тази заявка се посочва Приемане на заглавие със стойност application/jsonl, с което се указва, че отговорът трябва да се предава поточно във формат на JSON. API ще изпраща непрекъснато JSON редове, докато не бъдат изтеглени всички данни.

Пример за стрийминг: Токени и събития

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 маршрут, можете да получавате жетони и други събития, свързани с конкретен разговор.

За да предавате токени и събития, трябва да направите POST заявка към /v1/conversation/{conversationId}/complete маршрут. Заявката трябва да включва полезен товар JSON с текст параметър, съответстващ на въведените от потребителя данни:

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"
}

Тази заявка ще инициира стрийминг на токени и събития, свързани с посочения разговор. API ще изпраща непрекъснато актуализации, докато разговорът бъде завършен или прекратен.

Потокът може да бъде мощна алтернатива на странирането, като ви позволява да получавате данни в реално време и ефективно да обработвате големи количества информация.

Грешки

Обработката на грешки в приложния програмен интерфейс ChatBotKit се основава на HTTP кодове за състояние. На всяка грешка съответства конкретен код на състоянието, който указва естеството на грешката. В следващата таблица е представено обобщение на дефинициите на грешки и съответстващите им кодове на състояние:

Код за грешкаКод на състояниетоОписание на грешката
BAD_REQUEST400Заявката е неправилно оформена
NOT_AUTHENTICATED401Не е удостоверено
NOT_AUTHORIZED401Не е разрешено
НЯМА АБОНАМЕНТ402Без абонамент
NOT_FOUND404Не е намерен
METHOD_NOT_ALLOWED405Метод, който не е разрешен
КОНФЛИКТ409Има конфликт при работа с ресурса
TOO_MANY_REQUESTS429Твърде много заявки
LIMITS_REACHED429Достигнати лимити за абонамент
INTERNAL_SERVER_ERROR500Грешка на вътрешния сървър

Всички грешки, върнати от приложния програмен интерфейс ChatBotKit, включват полезен товар JSON в следния формат:

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

Сайтът съобщение предоставя кратко описание на грешката, а полето код полето посочва кода на грешката, свързан с нея. Този полезен товар може да помогне на разработчиците да идентифицират и обработват по подходящ начин грешките, когато интегрират ChatBotKit API в своите приложения.

В приложния програмен интерфейс на ChatBotKit има специфичен клас грешки, които могат да възникнат, когато всички налични токени са изчерпани. Тези грешки са свързани с лимити и показват, че е достигнат максималният брой разрешени заявки или действия.

Когато се сблъскат с тези грешки, разработчиците могат да получат един от следните кодове за състояние:

  • TOO_MANY_REQUESTS: Този код на състоянието (429) показва, че лимитът на скоростта за подаване на заявки е превишен.
  • LIMITS_REACHED: Този код на състоянието (429) показва, че лимитите за определени действия или ресурси са достигнати.

За да се справят с тези грешки, разработчиците трябва да приложат подходящи механизми за обработка на грешки в своите приложения. Това може да включва прилагане на логика за повторение, регулиране на скоростта на заявките или свързване с доставчика на API, за да се поинтересуват от увеличаване на ограниченията за конкретни действия или ресурси.

Важно е да се наблюдават и управляват ефективно лимитите, за да се осигури гладка и непрекъсната интеграция с ChatBotKit API.

Кодове за грешки в обхвата

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 вместо TOO_MANY_REQUESTS.

Важно е да се отбележи, че платформата ChatBotKit има цялостна политика за повторение за всички услуги нагоре по веригата, с които си взаимодейства. Ние ще се опитаме да изпълним всяка една заявка, независимо от ситуацията. В редки случаи всички заявки може да се окажат неуспешни. Тогава ще върнем разширена грешка.

Характеристики

API на ChatBotKit предлага редица мощни функции, които подобряват функционалността и възможностите на приложенията с изкуствен интелект за разговори. Тези функции позволяват на разработчиците да създават интерактивни и ангажиращи чатботове и виртуални асистенти, които могат да се справят със сложни диалози и да предоставят смислени отговори.

Продължения

Функцията за продължаване в приложния програмен интерфейс ChatBotKit е мощен инструмент, който позволява на всеки ограничен модел с ограничен размер на контекста да продължи да предава безкрайно. С тази функция разработчиците могат да преодолеят ограниченията на размера на контекста и безпроблемно да генерират отговори, които поддържат последователност и съгласуваност при продължителни разговори.

Като използват функцията за продължаване, разработчиците могат да разширят разговора отвъд ограниченията на контекста на модела, като осигурят плавен и непрекъснат поток на диалога. Това е особено полезно при сценарии, при които поддържането на контекста и генерирането на последователни отговори при дълги разговори е от решаващо значение.

Функцията за продължаване дава възможност на разработчиците да създават по-интерактивни и ангажиращи преживявания с AI в разговори. Тя открива възможности за създаване на чатботове и виртуални асистенти, които могат да се справят със сложни диалози и да предоставят смислени отговори, независимо от дължината или сложността на разговора.

Съгласуване на жетони

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.

Когато даден разговор или съобщение надхвърли максималния разрешен размер на контекста, API интелигентно прилага различни стратегии в зависимост от използвания модел. Тези стратегии гарантират, че разговорът остава последователен и непротиворечив, дори когато става въпрос за дълги или сложни взаимодействия.

Като използват съгласуването на токени, разработчиците могат уверено да създават разговорни преживявания с изкуствен интелект, които безпроблемно се справят с продължителни разговори. Тази функция елиминира необходимостта от ръчно съкращаване или модифициране на съобщенията, за да се вместят в ограниченията на контекста, което позволява по-рационален и естествен диалогов поток.

Независимо дали работите с модели, които имат строги ограничения за токените, или просто искате да осигурите оптимална производителност, съгласуването на токените в API на ChatBotKit осигурява надеждно решение за управление на размера на контекста и генериране на висококачествени отговори.

Агенти и фонови задачи

Една от мощните функции на ChatBotKit е способността му да обработва агенти с изкуствен интелект и фонови задачи. Благодарение на тази функционалност ChatBotKit може безпроблемно да изпълнява продължителни процеси, чието изпълнение може да отнеме минути. Тази способност е особено полезна за провеждане на многоетапни взаимодействия с бот и за изпълнение на сложни задачи, използващи различни набори от умения.

Като използват агенти и фонови задачи, разработчиците могат да създават разговорни преживявания с изкуствен интелект, които надхвърлят обикновените взаимодействия с въпроси и отговори. Ботът може да изпълнява задачи, които включват множество стъпки и изискват време за изпълнение, като например извличане на информация от външни източници, обработка на големи масиви от данни или изпълнение на сложни алгоритми.

Тази функционалност позволява на бота да обработва сложни потребителски заявки, които надхвърлят възможностите на традиционните чатботове. Тя дава възможност за по-сложни и динамични разговори, предоставяйки на потребителите по-богато и по-интерактивно преживяване.

Мета данни

Всеки ресурс - независимо дали е бот, набор от данни, набор от умения, разговор, контакт или друг тип - може да има свързани метаданни, представени като обект JSON. Можете да присвоите метаданни просто като използвате мета собственост. Важно е да се отбележи, че когато актуализирате ресурс, свойството замяна на метаданни ще замени всички съществуващи метаданни, които вече са съхранени. За да се адаптира към частични актуализации, API поддържа специален формат за промяна на метаданни.

За да създадете или изцяло да замените метаданните, използвайте следния синтаксис:

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

За да актуализирате само определени полета в метаданните, използвайте този синтаксис:

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

API Spec

Пълната спецификация на API за приложния програмен интерфейс на ChatBotKit е налична във формат OpenAPI. Можете да получите достъп до спецификацията на API на адрес https://api.chatbotkit.com/v1/spec.json.

За по-интерактивно преживяване можете да разгледате спецификацията на API на адрес https://chatbotkit.com/docs/api/v1/spec. Тази документация предоставя подробна информация за всяка крайна точка, включително примери за заявки и отговори, описания на параметрите и др.

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.

С помощта на Node SDK, разработчиците могат лесно да използват мощните функции на ChatBotKit API, без да се налага ръчно да обработват HTTP заявки и отговори на ниско ниво. SDK абстрахира сложността на комуникацията с API, като позволява на разработчиците да се съсредоточат върху изграждането на функционалността на разговорния AI в своите приложения.

За да започнете работа с ChatBotKit Node SDK, направете справка с пълната документация, налична на адрес https://chatbotkit.com/docs/node-sdk. Тази документация съдържа подробни инструкции за това как да инсталирате SDK, да се удостоверите с API и да правите различни API повиквания, използвайки интуитивните методи и функции на SDK.

APIразработване на чатботбезплатен ai чатбот apiразработване на чатбот ai