# Express - Платформа BotX: HTTP(s) BotX API
## Ограничения API
### Длина запроса
Общая длина запроса (Content-Length) не должна превышать 512 мб
При этом суммарный вес JSON полей запроса (исключая вес файла) не должен превышать 1мб
### Размер передаваемого файла
Размер передаваемого файла не должен превышать 512 мб, что составляет ~536 мб в base64 представление
### Расширения файлов
:::warning
При валидации файла, расширение файла определяется на основе переданного mimetype и таблицы соответствия (см. Таблица соответствия mimetype и расширений)
* Если mimetype присутствует в таблице то файл сохраняется с соответствующим расширением и переданным mimetype
* Если mimetype отсутствует в таблице, то файл сохраняется, как неопределенный бинарный файл с mimetype "application/octet-stream"
:::
#### Таблица соответствия mimetype и расширений
```elixir
%{
"application/epub+zip" => ["epub"],
"application/gzip" => ["gz"],
"application/java-archive" => ["jar"],
"application/javascript" => ["js"],
"application/json" => ["json"],
"application/json-patch+json" => ["json-patch"],
"application/ld+json" => ["jsonld"],
"application/manifest+json" => ["webmanifest"],
"application/msword" => ["doc"],
"application/octet-stream" => ["bin"],
"application/ogg" => ["ogx"],
"application/pdf" => ["pdf"],
"application/postscript" => ["ps", "eps", "ai"],
"application/rtf" => ["rtf"],
"application/vnd.amazon.ebook" => ["azw"],
"application/vnd.api+json" => ["json-api"],
"application/vnd.apple.installer+xml" => ["mpkg"],
"application/vnd.mozilla.xul+xml" => ["xul"],
"application/vnd.ms-excel" => ["xls"],
"application/vnd.ms-fontobject" => ["eot"],
"application/vnd.ms-powerpoint" => ["ppt"],
"application/vnd.oasis.opendocument.presentation" => ["odp"],
"application/vnd.oasis.opendocument.spreadsheet" => ["ods"],
"application/vnd.oasis.opendocument.text" => ["odt"],
"application/vnd.openxmlformats-officedocument.presentationml.presentation" => ["pptx"],
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" => ["xlsx"],
"application/vnd.openxmlformats-officedocument.wordprocessingml.document" => ["docx"],
"application/vnd.rar" => ["rar"],
"application/vnd.visio" => ["vsd"],
"application/x-7z-compressed" => ["7z"],
"application/x-abiword" => ["abw"],
"application/x-bzip" => ["bz"],
"application/x-bzip2" => ["bz2"],
"application/x-cdf" => ["cda"],
"application/x-csh" => ["csh"],
"application/x-freearc" => ["arc"],
"application/x-httpd-php" => ["php"],
"application/x-msaccess" => ["mdb"],
"application/x-sh" => ["sh"],
"application/x-shockwave-flash" => ["swf"],
"application/x-tar" => ["tar"],
"application/xhtml+xml" => ["xhtml"],
"application/xml" => ["xml"],
"application/wasm" => ["wasm"],
"application/zip" => ["zip"],
"audio/3gpp" => ["3gp"],
"audio/3gpp2" => ["3g2"],
"audio/aac" => ["aac"],
"audio/midi" => ["mid", "midi"],
"audio/mpeg" => ["mp3"],
"audio/ogg" => ["oga"],
"audio/opus" => ["opus"],
"audio/wav" => ["wav"],
"audio/webm" => ["weba"],
"font/otf" => ["otf"],
"font/ttf" => ["ttf"],
"font/woff" => ["woff"],
"font/woff2" => ["woff2"],
"image/avif" => ["avif"],
"image/bmp" => ["bmp"],
"image/gif" => ["gif"],
"image/jpeg" => ["jpg", "jpeg"],
"image/png" => ["png"],
"image/svg+xml" => ["svg", "svgz"],
"image/tiff" => ["tiff", "tif"],
"image/vnd.microsoft.icon" => ["ico"],
"image/webp" => ["webp"],
"text/calendar" => ["ics"],
"text/css" => ["css"],
"text/csv" => ["csv"],
"text/html" => ["html", "htm"],
"text/javascript" => ["js", "mjs"],
"text/plain" => ["txt", "text"],
"text/xml" => ["xml"],
"video/3gpp" => ["3gp"],
"video/3gpp2" => ["3g2"],
"video/quicktime" => ["mov"],
"video/mp2t" => ["ts"],
"video/mp4" => ["mp4"],
"video/mpeg" => ["mpeg", "mpg"],
"video/ogg" => ["ogv"],
"video/webm" => ["webm"],
"video/x-msvideo" => ["avi"],
"video/x-ms-wmv" => ["wmv"]
}
```
## Bots API
### Список методов
| Метод | URL | Описание |
| ----- | ----------------------------------------- | ----------------------------------------------- |
| GET | /api/v2/botx/bots/:bot_id/token | Получение токена |
### Получение токена
#### Описание
#### Параметры запроса
* **bot_id** [UUID] - идентификатор бота. Необходим для шифрования данных.
* **signature** [String] - bot_id подписанный секретным ключом бота (secret_key) используя hmac-sha256, представленный в виде base16 (hex) строки (используя традиционный [rfc4648](https://datatracker.ietf.org/doc/html/rfc4648#section-8) алфавит 0-9 A-F).
#### Пример подписи
```
:crypto.hmac(:sha256, "secret", "8dada2c8-67a6-4434-9dec-570d244e78ee") |> Base.encode16
"904E39D3BC549C71F4A4BDA66AFCDA6FC90D471A64889B45CC8D2288E56526AD
```
#### Пример запроса
```
/api/v2/botx/bots/8dada2c8-67a6-4434-9dec-570d244e78ee/token?signature=904E39D3BC549C71F4A4BDA66AFCDA6FC90D471A64889B45CC8D2288E56526AD
```
#### Пример ответа
```json
{
"status": "ok",
"result": "<token>"
}
```
### Получение списка ботов своего сервера
| Метод | URL | Описание |
| --- | --- | --- |
| GET | GET /api/v1/botx/bots/catalog?since=datatime | Получение токена |
#### Параметры запроса
* **since** [ISO-8601 timestamp] - минимально допустимое время последнего обновления бота в выборке.
#### Пример ответа
```json
{
"result": {
"generated_at": <datetime>,
"bots": [
{
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"name": "First bot",
"description": "My bot",
"avatar": "https://cts.ccsteam.ru/uploads/profile_avatar/796640bd-7add-5274-9f02-7bd169b88dab/04db7577-238c-5aec-8d21-22e831839c21.jpg?v=21"
"enabled": true,
}
]
}
}
```
## Notifications API
### Список методов
| Метод | URL | Описание |
| ----- | --------------------------------------------- | ----------------------------------------------- |
| POST | ~~/api/v3/botx/notification/callback/direct~~ | Отправка директ нотификации в чат (Deprecated) |
| POST | /api/v4/botx/notifications/internal | Отправка внутренней бот нотификации |
| POST | /api/v4/botx/notifications/direct | Отправка директ нотификации в чат |
### Отправка директ нотификации v4
#### Описание
* Обрабатывается асинхронно
* В ответ на запрос приходит **sync_id** [UUID] - идентификатор отправляемого сообщения
* В случае успеха или провала отправки, на коллбек боту отправляется запрос с результатом отправки
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "multipart/form-data" (при отсутствие файла можно использовать "application/json")
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата в который придет сообщение
* **recipients** [Array[UUID]] (Default: null) - huid получателей события. По умолчанию все участники чата.
* **notification** [Object]
* **status** [String] - "ok" | "error". Служит идентификатором успешности или провала выполнения команды.
* **body** [String] - текстовое сообщение. Отображается в чате, как текстовое сообщение.
* **metadata** [Object] (Default: {}) - метаданные которые будут отправлены в параметрах команды при нажатие на любую кнопку.
* **opts** [Object] (Default: {}) - опции сообщения
* **silent_response** [Boolean](Default: false) - если значение `true`, то последующие сообщения пользователя не будут отображаться в чате, до тех пор пока не придет сообщения бота у которого это значение будет установлено в `false`. Разрешено только в личных чатах (1-1)
* **buttons_auto_adjust** [Boolean](Default: false) - если значение 'true', то кнопки, при отображение, будут автоматически переноситься на новый ряд, если не помещаются в заданном ряду
* **keyboard** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные на клавиатуре, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **bubble** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные под сообщением, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **mentions** [Array[Object]] (Default: []) - список меншнов
:::info
Отображение меншнов в тексте (body) задается по следующему шаблону:
@{mention:**mention_id**} - для user/all mention
@@{mention:**mention_id**} - для contact mention
##{mention:**mention_id**} - для chat/channel mention
Например: @{mention:a465f0f3-1354-491c-8f11-f400164295cb}
:::
* **mention_type** [String] (Default: "user") - тип меншна user|chat|channel|contact|all
* **mention_id** [UUID5] - id меншна
* **mention_data** [Object]
для mention_type "all" - **null**
для mention_type "user" и "contact"
* **user_huid** [UUID5] - huid пользователя которого меншат
* **name** [String] - имя пользователя
для mention_type "chat" и "channel"
* **group_chat_id** [UUID5] - id чата
* **name** [String] - отображаемое имя чата
* **file** [Object] (Default: null) - файл в base64 представление.
* file_name [String] - имя файла
* data [String] - data URL + base64 data (RFC 2397)
* **opts** [Object] - опции запроса
* **stealth_mode** [Boolean] (Default: false) - если true, то сообщение будет отправлено в чат только в том случае, если в чате включен стелс режим
* **notification_opts** [Object]
* **send** [Boolean] (Default: true) - отправлять/не отправлять пуш нотификацию
* **force_dnd** [Boolean] (Default: false) - игнорировать/не игнорировать DND/Mute.
#### Пример запроса
```json
{
"group_chat_id": "a465f0f3-1354-491c-8f11-f400164295cb",
"recipients": null,
"notification": {
"status": "ok",
"body": "@{mention:a465f0f3-1354-491c-8f11-f400164295cb} Выберите пункт меню",
"metadata": {"account_id": 94},
"opts": {"silent_response": true},
"bubble": [
[
{"command": "/profile", "label": "Профиль", "opts": {"background_color": "#010205", "align": "center"}}
],
[
{"command": "/balance", "label": "Баланс", "data": {"operation_id": 1}},
{"command": "/transactions", "label": "Транзакции", "data": {"operation_id": 2}}
]
],
"keyboard": [
[
{"command": "/help", "label": "Помощь", "opts": {"silent": true, "h_size": 2}}
]
],
"mentions": [
{
"mention_id": "a465f0f3-1354-491c-8f11-f400164295cb",
"mention_type": "user",
"mention_data": {
"user_huid": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"name": "Gena the Croc"
}
}
]
},
"file": {
"data": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=",
"file_name": "card.png"
},
"opts": {
"stealth_mode": false,
"notification_opts": {
"send": true,
"force_dnd": false
}
}
}
```
#### Успешный ответ (202)
* **status** [String] (Value: "ok")
* **result** [Object]
* **sync_id** [UUID] - идентификатор отправляемого сообщения
```json
{
"status": "ok",
"result": {
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36"
}
}
```
#### Результат и возможные ошибки
Следующий результат или ошибки будут отправлены боту на callback метод
##### Успех
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "ok",
"result": {}
}
```
##### Чат не найден
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"error_description": "Chat with specified id not found"
}
}
```
##### Ошибка от Messaging сервиса
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"reason": "some_error",
"error_description": "Messaging service returns error. Check BotX container logs (level :warn or upper) for more info."
}
}
```
##### Бот отправитель не является участником чата
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "bot_is_not_a_chat_member",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"bot_id": "b165f00f-3154-412c-7f11-c120164257da",
"error_description": "Bot is not a chat member"
}
}
```
##### Стелс-режим отключен в чате, но требуется опцией
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "stealth_mode_disabled",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"bot_id": "b165f00f-3154-412c-7f11-c120164257da",
"error_description": "Stealth mode disabled in specified chat"
}
}
```
##### Итоговый список получателей события пуст
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "event_recipients_list_is_empty",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"bot_id": "b165f00f-3154-412c-7f11-c120164257da",
"recipients_param": ["b165f00f-3154-412c-7f11-c120164257da"],
"error_description": "Event recipients list is empty"
}
}
```
##### Ошибка в процессе обработки
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "flow_processing_error",
"errors": ["{error1}", "{error2}"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info"
}
}
```
##### Непредвиденная ошибка
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "unexpected_error",
"errors": ["{error1}", "{error2}"],
"error_data": {
"error_description": "Got unexpected error. Check BotX container logs (level :error or upper) for more info"
}
}
```
##### Ошибки загрузки файла
Список возможных ошибок можно найти в описание метода [Загрузка файла](/s/PZJXHXPSRie_GCJIIk0e9w#Загрузка-файла)
### Отправка внутренней бот нотификации
#### Описание
* Обрабатывается асинхронно
* В ответ на запрос приходит **sync_id** [UUID] - идентификатор отправляемого сообщения
* В случае успеха или провала отправки, на коллбек боту отправляется запрос с результатом отправки
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - ID чата
* **data** [Object] - пользовательские данные
* **opts** [Object] (default: {}) - пользовательские опции
* **recipients** [Array[UUID]] (default: Null) - список ботов получателей. Если не передан, то отправляется всем ботам в чате
```json
{
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"data": {
"message": "ping"
},
"opts": {
"internal_token": "FEFctII3lRlRBcetROeFfduPmXxE"
},
"recipients": null
}
```
#### Успешный ответ (202)
* **status** [String] (Value: "ok")
* **result** [Object]
* **sync_id** [UUID] - идентификатор отправляемого сообщения
```json
{
"status": "ok",
"result": {
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36"
}
}
```
#### Превышен лимит интенсивности запросов (429)
```json
{
"status": "error",
"reason": "too_many_requests",
"errors": [],
"error_data": {
"bot_id": "b165f00f-3154-412c-7f11-c120164257da"
}
}
```
#### Результат и возможные ошибки
Следующий результат или ошибки будут отправлены боту на callback метод
##### Успех
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "ok",
"result": {}
}
```
##### Чат не найден
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"error_description": "Chat with specified id not found"
}
}
```
##### Ошибка от Messaging сервиса
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"reason": "some_error",
"error_description": "Messaging service returns error. Check BotX container logs (level :warn or upper) for more info."
}
}
```
##### Бот отправитель не является участником чата
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "bot_is_not_a_chat_member",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"bot_id": "b165f00f-3154-412c-7f11-c120164257da",
"error_description": "Bot is not a chat member"
}
}
```
##### Итоговый список получателей события пуст
```json
{
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36",
"status": "error",
"reason": "event_recipients_list_is_empty",
"errors": [],
"error_data": {
"group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c",
"bot_id": "b165f00f-3154-412c-7f11-c120164257da",
"recipients_param": ["b165f00f-3154-412c-7f11-c120164257da"],
"error_description": "Event recipients list is empty"
}
}
```
### Отправка директ нотификации
:::warning
Данное API является устаревшим и в дальнейшем будет недоступно :zap:
Рекомендуется использовать /api/v4/botx/notifications/direct
:::
#### Описание
* Обрабатывается асинхронно
* В ответ на запрос приходит **sync_id** [UUID] - идентификатор отправляемого сообщения
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "multipart/form-data" (при отсутствие файла можно использовать "application/json")
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата в который придет сообщение
* **event_sync_id** [UUID] (Default: autogenerate) - идентификатор отправляемого сообщения
* **recipients** [Array[UUID]] || [String] (Default: "all") - huid получателей события. По умолчанию все участники чата.
* **notification** [Object]
* **status** [String] - "ok" | "error". Служит идентификатором успешности или провала выполнения команды.
* **body** [String] - текстовое сообщение. Отображается в чате, как текстовое сообщение.
* **metadata** [Object] (Default: {}) - метаданные которые будут отправлены в параметрах команды при нажатие на любую кнопку.
* **opts** [Object] (Default: {}) - опции сообщения
* **silent_response** [Boolean](Default: false) - если значение `true`, то последующие сообщения пользователя не будут отображаться в чате, до тех пор пока не придет сообщения бота у которого это значение будет установлено в `false`. Разрешено только в личных чатах (1-1)
* **buttons_auto_adjust** [Boolean](Default: false) - если значение 'true', то кнопки, при отображение, будут автоматически переноситься на новый ряд, если не помещаются в заданном ряду
* **keyboard** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные на клавиатуре, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **bubble** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные под сообщением, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **mentions** [Array[Object]] (Default: []) - список меншнов
* **mention_type** [String] (Default: "user") - тип меншна user|chat|contact
* **mention_id** [UUID5] (Default: autogenerate) - id меншна
* **mention_data** [Object]
для mention_type "user" и "contact"
* **user_huid** [UUID5] - huid пользователя которого меншат
* **name** [String] - имя пользователя
для mention_type "chat"
* **group_chat_id** [UUID5] - id чата
* **name** [String] - отображаемое имя чата
* **file** [Object] (Default: null) - файл в base64 представление.
* file_name [String] - имя файла
* data [String] - data URL + base64 data (RFC 2397)
* **opts** [Object] - опции запроса
* **stealth_mode** [Boolean] (Default: false) - если true, то сообщение будет отправлено в чат только в том случае, если в чате включен стелс режим
* **raw_mentions** [Boolean] (Default: false) - если true, то меншны не будут подставляться в начало текста сообщения, а будут подставлены в соответствие с заданным форматом
* **notification_opts** [Object]
* **send** [Boolean] (Default: true) - отправлять/не отправлять пуш нотификацию
* **force_dnd** [Boolean] (Default: false) - игнорировать/не игнорировать DND/Mute.
#### Пример запроса
```json
{
"group_chat_id": "a465f0f3-1354-491c-8f11-f400164295cb",
"recipients": "all",
"notification": {
"status": "ok",
"body": "Выберите пункт меню",
"metadata": {"account_id": 94},
"opts": {"silent_response": true},
"bubble": [],
"keyboard": [
[
{"command": "/balance", "label": "Баланс", "data": {"operation_id": 1}},
{"command": "/transactions", "label": "Транзакции", "data": {"operation_id": 2}}
],
[
{"command": "/help", "label": "Помощь", "opts": {"silent": true, "h_size": 2}}
]
],
"mentions": [
{
"mention_data": {
"user_huid": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"name": "Gena the Croc"
}
}
]
},
"file": {
"data": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=",
"file_name": "card.png"
},
"opts": {
"stealth_mode": false,
"notification_opts": {
"send": true,
"force_dnd": false
}
}
}
```
#### Параметры успешного ответа
* **status** [String] (Value: "ok")
* **result** [Object]
* **sync_id** [UUID] - идентификатор отправляемого сообщения
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"sync_id": "f0f105d2-101f-59b0-9e10-e432efce2c36"
}
}
```
## Events API
### Список методов
| Метод | URL | Описание |
| ----- | ----------------------------------- | -------------------------- |
| POST | /api/v3/botx/events/edit_event | Редактирование события |
| POST | /api/v3/botx/events/reply_event | Ответ (reply) на сообщение |
| GET | /api/v3/botx/events/:sync_id/status | Статус сообщения |
| POST | /api/v3/botx/events/typing | Отправка typing |
| POST | /api/v3/botx/events/stop_typing | Отправка stop_typing |
| POST | /api/v3/botx/events/delete_event | Удаление сообщения |
### Редактирование события
#### Описание
* Редактирование содержимого события (результата команды или нотификации)
* Можно редактировать только те события, что были отправлены текущим ботом
* Обрабатывается асинхронно
#### Логика обновления полей события
* Если поле не указано в запросе, то оно не обновляется
* Для полей keyboard/bubble/mentions, если в запросе указан пустой массив [], то набор становится пустым
* Если обновлен текст, но при этом есть меншны, то существующие меншны будут добавлены в новый текст
* Если обновляется список меншнов, но есть текст, то новый список меншнов будет добавлен в текст (а старый будет удален из текста)
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **sync_id** [UUID] - uuid редактируемого события
* **payload** [Object]
* **status** [String] - "ok" | "error" (Default: Skip). Служит идентификатором успешности или провала выполнения команды.
* **body** [String] (Default: Skip) - текстовое сообщение. Отображается в чате, как текстовое сообщение.
* **metadata** [Object] (Default: Skip) - метаданные которые будут отправлены в параметрах команды при нажатие на любую кнопку.
* **opts** [Object] (Default: {}) - опции сообщения
* **silent_response** [Boolean](Default: false) - если значение `true`, то последующие сообщения пользователя не будут отображаться в чате, до тех пор пока не придет сообщения бота у которого это значение будет установлено в `false`. Разрешено только в личных чатах (1-1)
* **buttons_auto_adjust** [Boolean](Default: false) - если значение 'true', то кнопки, при отображение, будут автоматически переноситься на новый ряд, если не помещаются в заданном ряду
* **keyboard** [Array[Array[Object]]] (Default: Skip) - кнопки команд расположенные на клавиатуре, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **bubble** [Array[Array[Object]]] (Default: Skip) - кнопки команд расположенные под сообщением, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **mentions** [Array[Object]] (Default: Skip) - список меншнов
* **mention_type** [String] (Default: "user") - тип меншна user|chat|contact
* **mention_id** [UUID5] (Default: autogenerate) - id меншна
* **mention_data** [Object]
для mention_type "user" и "contact"
* **user_huid** [UUID5] - huid пользователя которого меншат
* **name** [String] (default: имя из Active Directory) - имя пользователя
для mention_type "chat"
* **group_chat_id** [UUID5] - id чата
* **name** [String] - отображаемое имя чата
* **file** [Object] (Default: Skip) - файл в base64 представление. Если передать null, то существующий файл удалится из события
* file_name [String] - имя файла
* data [String] - data URL + base64 data (RFC 2397)
* **opts** [Object] - опции запроса
* **silent_response** [Boolean](Default: false) - если значение `true`, то последующие сообщения пользователя не будут отображаться в чате, до тех пор пока не придет сообщения бота у которого это значение будет установлено в `false`. Разрешено только в личных чатах (1-1).
* **raw_mentions** [Boolean] (Default: false) - если true, то меншны не будут подставляться в начало текста сообщения, а будут подставлены в соответствие с заданным форматом
#### Пример запроса
```json
{
"sync_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"payload": {
"status": "ok",
"body": "Операция завершена!",
"bubble": [],
"keyboard": [
[
{"command": "/balance", "label": "Баланс"},
{"command": "/transactions", "label": "Транзакции"}
],
[
{"command": "/help", "label": "Помощь", "opts": {"silent": true, "h_size": 2}}
]
],
"mentions": []
},
"opts": {}
}
```
### Ответ (reply) на сообщение
#### Описание
* Обрабатывается асинхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "multipart/form-data" (при отсутствие файла можно использовать "application/json")
#### Параметры запроса
* **source_sync_id** [UUID] - идентификатор сообщения, на который будет отправлен ответ
* **reply** [Object]
* **status** [String] - "ok" | "error". Служит идентификатором успешности или провала выполнения команды.
* **body** [String] - текстовое сообщение. Отображается в чате, как текстовое сообщение.
* **metadata** [Object] (Default: {}) - метаданные которые будут отправлены в параметрах команды при нажатие на любую кнопку.
* **opts** [Object] (Default: {}) - опции сообщения
* **silent_response** [Boolean](Default: false) - если значение `true`, то последующие сообщения пользователя не будут отображаться в чате, до тех пор пока не придет сообщения бота у которого это значение будет установлено в `false`. Разрешено только в личных чатах (1-1)
* **buttons_auto_adjust** [Boolean](Default: false) - если значение 'true', то кнопки, при отображение, будут автоматически переноситься на новый ряд, если не помещаются в заданном ряду
* **keyboard** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные на клавиатуре, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **bubble** [Array[Array[Object]]] (Default: []) - кнопки команд расположенные под сообщением, представленные в виде двумерного массива объектов.
* **command** [String] - тело команды
* **label** [String] - наименование команды
* **data** [Object] (Default: {}) - объект с данными, которые будут отправлены в качестве параметров команды при нажатие на кнопку
* **opts** [Object] - объект с клиентскими опциями кнопки
* **silent** [Boolean] (Default: false) - если значение true, то при нажатие на кнопку в чат не будет отправлено сообщение с текстом команды и сама команда отправится боту в фоне
* **h_size** [Integer] (Default: 1) - размер кнопки по горизонтали
* **show_alert** [Boolean] (Default: false) - если значение true, то при нажатии на кнопку отобразится всплывающее уведомление с заданным в **alert_text** сообщением
* **alert_text** [String](Default: null) - текст уведомления. Если значение null, то выведется тело команды
* **font_color** [String] (Default: null) - цвет текста в hex формате
* **background_color** [String] (Default: null) - цвет фона/границ в hex формате
* **align** [String] (Default: "left") - выравнивание текста left|center|right
* **mentions** [Array[Object]] (Default: []) - список меншнов
* **mention_type** [String] (Default: "user") - тип меншна user|chat|contact
* **mention_id** [UUID5] (Default: autogenerate) - id меншна
* **mention_data** [Object]
для mention_type "user" и "contact"
* **user_huid** [UUID5] - huid пользователя которого меншат
* **name** [String] (default: имя из Active Directory) - имя пользователя
для mention_type "chat"
* **group_chat_id** [UUID5] - id чата
* **name** [String] - отображаемое имя чата
* **file** [Binary]|[Object] (Default: null) - файл в бинарном представление (multipart запрос) или base64.
* Base64 file format
* file_name [String] - имя файла
* data [String] - data URL + base64 data (RFC 2397)
* caption [String] (Default: null) - текст под файлом
* **opts** [Object] - опции запроса
* **stealth_mode** [Boolean] (Default: false) - если true, то сообщение будет отправлено в чат только в том случае, если в чате включен стелс режим
* **notification_opts** [Object]
* **send** [Boolean] (Default: true) - отправлять/не отправлять пуш нотификацию
* **force_dnd** [Boolean] (Default: false) - игнорировать/не игнорировать DND/Mute.
#### Пример запроса
```json
{
"source_sync_id": "b165f00f-3154-412c-7f11-c120164257da",
"reply": {
"status": "ok",
"body": "Хороший выбор! Я сохранил ваш вариант ответа.",
"metadata": {},
"opts": {"silent_response": false},
"bubble": [],
"keyboard": [],
"mentions": []
},
"file": null,
"opts": {
"stealth_mode": false,
"notification_opts": {
"send": true,
"force_dnd": false
}
}
}
```
#### Параметры успешного ответа
* **status** [String] (Value: "ok")
* **result** [String] (Value: “bot_reply_pushed”)
#### Пример успешного ответа
```json
{
"status": "ok",
"result": "bot_reply_pushed"
}
```
### Получение статуса сообщения
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **sync_id** [UUID] - идентификатор события
#### Пример параметров запроса
```
/api/v3/botx/events/dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4/status
```
#### Пример успешного ответа
* **group_chat_id** [UUID] - идентификатор чата
* **sent_to** [Array[UUID]] - список huid пользователей которым было отправлено событие
* **read_by** [Array[Object]]
* **user_huid** [UUID] - huid пользователя прочитавшего событие
* **read_at** [DateTime] - время прочтения
* **received_by** [Array[Object]]
* **user_huid** [UUID] - huid пользователя получившего событие
* **received_at** [DateTime] - время получения
```json
{
"status": "ok",
"result": {
"group_chat_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5",
"sent_to": ["32bb051e-cee9-5c5c-9c35-f213ec18d11e"],
"read_by": [
{
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"read_at": "2019-08-29T11:22:48.358586Z"
}
],
"received_by": [
{
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"received_at": "2019-08-29T11:22:48.358586Z"
}
]
}
}
```
#### Событие не найдено (404)
```json
{
"status": "error",
"reason": "event_not_found",
"errors": [],
"error_data": {
"sync_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd"
}
}
```
#### Ошибка messaging сервиса при запросе события (500)
```json
{
"status": "error",
"reason": "messaging_service_error",
"errors": [],
"error_data": {
"sync_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd"
}
}
```
### Отправка typing
#### Описание
Обрабатывается асинхронно
:::info
Событие отправляется только пользователям с того же сервера, где зарегистрирован бот
:::
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
#### Пример запроса
```json
{
"group_chat_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5"
}
```
#### Пример успешного ответа (202)
```json
{
"status": "ok",
"result": "typing_event_pushed"
}
```
### Отправка stop_typing
#### Описание
Обрабатывается асинхронно
:::info
Событие отправляется только пользователям с того же сервера, где зарегистрирован бот
:::
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
#### Пример запроса
```json
{
"group_chat_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5"
}
```
#### Пример успешного ответа (202)
```json
{
"status": "ok",
"result": "stop_typing_event_pushed"
}
```
### Удаление сообщения
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **sync_id** [UUID] - идентификатор сообщения
#### Пример запроса
```json
{
"sync_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5"
}
```
#### Пример успешного ответа (202)
```json
{
"status": "ok",
"result": "event_deleted"
}
```
#### Сообщение не найдено (404)
```json
{
"status": "error",
"reason": "sync_id_not_found",
"errors": [],
"error_data": {}
}
```
## Chats API
### Список методов
| Метод | URL | Описание |
| ----- | ---------------------------------- | ------------------------------- |
| GET | /api/v3/botx/chats/list | Получение списка чатов бота |
| GET | /api/v3/botx/chats/info | Получение информации о чате |
| POST | /api/v3/botx/chats/add_user | Добавление юзеров в чат |
| POST | /api/v3/botx/chats/remove_user | Удаление юзеров из чата |
| POST | /api/v3/botx/chats/add_admin | Добавление администратора в чат |
| POST | /api/v3/botx/chats/stealth_set | Включение стелс режима в чате |
| POST | /api/v3/botx/chats/stealth_disable | Отключение стелс режима в чате |
| POST | /api/v3/botx/chats/create | Создание чата |
| POST | /api/v3/botx/chats/pin_message | Закрепление сообщения в чате |
| POST | /api/v3/botx/chats/unpin_message | Открепление сообщения в чате |
### Получение списка чатов бота
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
Отсутствуют
#### Пример запроса
#### Пример успешного ответа
```json
{
"status": "ok",
"result": [
{
"group_chat_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5",
"chat_type": "group_chat",
"name": "Chat Name",
"description": "Desc",
"members": [
"6fafda2c-6505-57a5-a088-25ea5d1d0364",
"705df263-6bfd-536a-9d51-13524afaab5c"
],
"shared_history": false,
"inserted_at": "2019-08-29T11:22:48.358586Z",
"updated_at": "2019-08-30T21:02:10.453786Z"
}
]
}
```
### Получение информации о чате
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
#### Пример параметров запроса
```
?group_chat_id=dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"chat_type": "group_chat",
"creator": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"description": null,
"group_chat_id": "740cf331-d833-5250-b5a5-5b5cbc697ff5",
"inserted_at": "2019-08-29T11:22:48.358586Z",
"members": [
{
"admin": true,
"server_id": "32bb051e-cee9-5c5c-9c35-f213ec18d11e",
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"user_kind": "user"
},
{
"admin": false,
"server_id": "32bb051e-cee9-5c5c-9c35-f213ec18d11e",
"user_huid": "705df263-6bfd-536a-9d51-13524afaab5c",
"user_kind": "botx"
}
],
"name": "Group Chat Example",
"shared_history": false
}
}
```
#### Чат не найден (404)
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"error_description": "Chat with specified id not found"
}
}
```
#### Ошибка messaging сервиса при запросе чата (500)
```json
{
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"reason": "some_error",
"error_description": "Chat info fetching failed. Check BotX container logs (level :warn or upper) for more info."
}
}
```
### Добавление юзеров в чат
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
* **user_huids** [Array[UUID]] - список добавляемых юзеров
#### Пример запроса
```json
{
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"user_huids": ["a465f0f3-1354-491c-8f11-f400164295cb"]
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": ["Chat not found"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Бот не является админом чата
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": ["Sender is not chat admin"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sender": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (403): Редактирование списка участников персонального чата невозможно
```json
{
"status": "error",
"reason": "chat_members_not_modifiable",
"errors": ["Сan't add users to personal chats"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
### Удаление юзеров из чата
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
* **user_huids** [Array[UUID]] - список удаляемых юзеров
#### Пример запроса
```json
{
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"user_huids": ["a465f0f3-1354-491c-8f11-f400164295cb"]
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": ["Chat not found"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Бот не является админом чата
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": ["Sender is not chat admin"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sender": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (403): Редактирование списка участников персонального чата невозможно
```json
{
"status": "error",
"reason": "chat_members_not_modifiable",
"errors": ["Сan't remove users from personal chats"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
### Добавление администратора в чат
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
* **user_huids** [Array[UUID]] - список юзеров чата которые назначаются администратором
#### Пример запроса
```json
{
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"user_huids": ["a465f0f3-1354-491c-8f11-f400164295cb"]
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": ["Chat not found"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Бот не является админом чата
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": ["Sender is not chat admin"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sender": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (400): Редактирование списка администраторов персонального чата невозможно
```json
{
"status": "error",
"reason": "chat_members_not_modifiable",
"errors": [],
"error_data": {}
}
```
### Включение стелс режима в чате
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
* **disable_web** [Boolean] (Default: false) - если true - отключает доступ к чату с веб-клиента (по умолчанию false)
* **burn_in** [Integer] (Default: null) - время сгорания для прочитавшего, в секундах (по-умолчанию null - выключено)
* **expire_in** [Integer] (Default: null) - время сгорания для всех участников чата, в секундах (по-умолчанию null - выключено)
#### Пример запроса
```json
{
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"disable_web": false,
"burn_in": 60,
"expire_in": 3200
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": ["Chat not found"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Бот не является админом чата
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": ["Sender is not chat admin"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sender": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
### Отключение стелс режима в чате
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
#### Пример запроса
```json
{
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": ["Chat not found"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Бот не является админом чата
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": ["Sender is not chat admin"],
"error_data": {
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sender": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
### Создание чата
#### Описание
Обрабатывается синхронно
В персональных чатах name игнорируется клиентами, можно указать любое, например "Personal chat"
Создателем чата будет являться бот, который инициировал запрос
Бот будет добавлен в список участников чата, даже если он явно не указан в списке при отправке запроса
Чтобы бот мог создавать чат, в панели администратора ему нужно задать свойство **allow_chat_creating** в значение **true**
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **name** [String] - имя чата
* **description** [String] (Default: null) - описание чата
* **chat_type** [String] - тип чата (chat|group_chat|channel)
* **members** [Array[UUID]] - список HUID участников чата
* **avatar** [String] (Default: null) - аватар чата в формате data URL + base64 data (RFC 2397)
* **shared_history** [Boolean] (Default: false) - если true, то созданный чат будет иметь признаки шаред чата. Для персональных чатов всегда false.
#### Пример запроса
```json
{
"name": "New Chat",
"description": "Simple group chat",
"chat_type": "group_chat",
"members": [
"dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"a465f0f3-1354-491c-8f11-f400164295cb"
],
"avatar": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=",
"shared_history": false
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (403): Боту запрещено создавать чаты
```json
{
"status": "error",
"reason": "chat_creation_is_prohibited",
"errors": ["This bot is not allowed to create chats"],
"error_data": {
"bot_id": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (422): Ошибка создания чата
```json
{
"status": "error",
"reason": "|specified reason|",
"errors": ["|specified errors|"],
"error_data": {}
}
```
### Закрепление сообщения в чате
#### Описание
Обрабатывается синхронно
Бот закрепляет указанное сообщение в чате. Для закрепления в каналах у бота должны быть права администратора.
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **chat_id** [UUID] - идентификатор чата
* **sync_id** [UUID] - идентификатор сообщения
#### Пример запроса
```json
{
"chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"sync_id": "465f0f3-1354-491c-8f11-f400164295cb"
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": "message_pinned"
}
```
#### Ошибка (403): Бот не может закрепить сообщение
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": [],
"error_data": {
"error_description": "Bot doesn't have permission for this operation in current chat",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"bot_id": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"error_description": "Chat with specified id not found",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (500): Messaging сервис вернул ошибку
```json
{
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"error_description": "Messaging service returns error. Check BotX container logs (level :warn or upper) for more info.",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"reason": "some_error"
}
}
```
### Открепление сообщения в чате
#### Описание
Обрабатывается синхронно
Бот открепляет указанное сообщение в чате. Для открепления в каналах у бота должны быть права администратора.
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **chat_id** [UUID] - идентификатор чата
#### Пример запроса
```json
{
"chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": "message_unpinned"
}
```
#### Ошибка (403): Бот не может открепить сообщение
```json
{
"status": "error",
"reason": "no_permission_for_operation",
"errors": [],
"error_data": {
"error_description": "Bot doesn't have permission for this operation in current chat",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"bot_id": "a465f0f3-1354-491c-8f11-f400164295cb"
}
}
```
#### Ошибка (404): Чат не найден
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"error_description": "Chat with specified id not found",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4"
}
}
```
#### Ошибка (500): Messaging сервис вернул ошибку
```json
{
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"error_description": "Messaging service returns error. Check BotX container logs (level :warn or upper) for more info.",
"group_chat_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4",
"reason": "some_error"
}
}
```
## Users API
### Список методов
| Метод | URL | Описание |
| ----- |:--------------------------------- | ---------------------------------------------------- |
| GET | ~~/api/v3/botx/users/by_email~~ | Поиск данных юзера по его почте (Deprecated) |
| POST | /api/v3/botx/users/by_email | Поиск данных юзеров по их почтам |
| GET | /api/v3/botx/users/by_huid | Поиск данных юзера по его huid |
| GET | /api/v3/botx/users/by_login | Поиск данных юзера по его ad логину и ad домену |
| GET | /api/v3/botx/users/by_other_id | Поиск данных юзера по дополнительному идентификатору |
| GET | /api/v3/botx/users/users_as_csv | Получение списка пользователей на CTS |
| PUT | /api/v3/botx/users/update_profile | Обновление профиля юзера |
### Поиск данных юзера по его почте (Deprecated)
:::warning
Данное API является устаревшим и в дальнейшем будет недоступно :zap:
Рекомендуется использовать POST /api/v3/botx/users/by_email
:::
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **email** [String] - почта юзера
#### Пример параметров запроса
```
?email=ad_user@cts.com
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"ad_login": "ad_user_login",
"ad_domain": "cts.com",
"name": "Bob",
"company": "Bobs Co",
"company_position": "Director",
"department": "Owners",
"emails": [
"ad_user@cts.com"
],
"other_id": "some_id",
"user_kind": "cts_user"
}
}
```
#### Ошибка (404): Данные юзера не найдены
```json
{
"status": "error",
"reason": "user_not_found",
"errors": [],
"error_data": {}
}
```
### Поиск данных юзеров по их почтам
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **emails** [Array[String]] - почты юзеров
#### Пример параметров запроса
```json
{
"emails": ["user1@cts.com", "user2@cts.com"]
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": [
{
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"ad_login": "ad_user_login1",
"ad_domain": "cts.com",
"name": "Bob",
"company": "Bobs Co",
"company_position": "Director",
"department": "Owners",
"emails": [
"ad_user@cts.com", "user1@cts.com"
],
"other_id": "some_id1",
"user_kind": "cts_user",
"active": true,
"created_at": "2023-03-26T14:36:08.740618Z",
"cts_id": "e0140f4c-4af2-5a2e-9ad1-5f37fceafbaf",
"description": "Director in Owners dep",
"ip_phone": 1271020,
"manager": "Alice",
"office": "SUN",
"other_ip_phone": null,
"other_phone": null,
"public_name": "Bobby",
"rts_id": "f46440a4-d930-58d4-b3f5-8110ab846ee3",
"updated_at": "2023-03-26T14:36:08.740618Z",
},
{
"user_huid": "a465f0f3-1354-491c-8f11-f400164295cb",
"ad_login": "ad_user_login2",
"ad_domain": "cts.com",
"name": "Alice",
"company": "Bobs Co",
"company_position": "CEO",
"department": "Owners",
"emails": [
"user2@cts.com"
],
"other_id": "some_id2",
"user_kind": "cts_user",
"active": true,
"created_at": "2023-03-28T14:36:08.740618Z",
"cts_id": "e0140f4c-4af2-5a2e-9ad1-5f37fceafbaf",
"description": "CEO",
"ip_phone": 156,
"manager": null,
"office": "SUN",
"other_ip_phone": null,
"other_phone": null,
"public_name": "Bobby",
"rts_id": "f46440a4-d930-58d4-b3f5-8110ab846ee3",
"updated_at": "2023-03-28T14:36:08.740618Z",
}
]
}
```
### Поиск данных юзера по его huid
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **user_huid** [UUID] - huid юзера
#### Пример параметров запроса
```
?user_huid=6fafda2c-6505-57a5-a088-25ea5d1d0364
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"ad_login": "ad_user_login1",
"ad_domain": "cts.com",
"name": "Bob",
"company": "Bobs Co",
"company_position": "Director",
"department": "Owners",
"emails": [
"ad_user@cts.com", "user1@cts.com"
],
"other_id": "some_id1",
"user_kind": "cts_user",
"active": true,
"created_at": "2023-03-26T14:36:08.740618Z",
"cts_id": "e0140f4c-4af2-5a2e-9ad1-5f37fceafbaf",
"description": "Director in Owners dep",
"ip_phone": 1271020,
"manager": "Alice",
"office": "SUN",
"other_ip_phone": null,
"other_phone": null,
"public_name": "Bobby",
"rts_id": "f46440a4-d930-58d4-b3f5-8110ab846ee3",
"updated_at": "2023-03-26T14:36:08.740618Z",
}
}
```
#### Ошибка (404): Данные юзера не найдены
```json
{
"status": "error",
"reason": "user_not_found",
"errors": [],
"error_data": {}
}
```
### Поиск данных юзера по его ad логину и ad домену
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **ad_login** [String] - ad логин пользователя
* **ad_domain** [String] - ад домен пользователя
#### Пример запроса
```
?ad_login=ad_user_login&ad_domain=cts.com
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"ad_login": "ad_user_login1",
"ad_domain": "cts.com",
"name": "Bob",
"company": "Bobs Co",
"company_position": "Director",
"department": "Owners",
"emails": [
"ad_user@cts.com", "user1@cts.com"
],
"other_id": "some_id1",
"user_kind": "cts_user",
"active": true,
"created_at": "2023-03-26T14:36:08.740618Z",
"cts_id": "e0140f4c-4af2-5a2e-9ad1-5f37fceafbaf",
"description": "Director in Owners dep",
"ip_phone": 1271020,
"manager": "Alice",
"office": "SUN",
"other_ip_phone": null,
"other_phone": null,
"public_name": "Bobby",
"rts_id": "f46440a4-d930-58d4-b3f5-8110ab846ee3",
"updated_at": "2023-03-26T14:36:08.740618Z",
}
}
```
#### Ошибка (404): Данные юзера не найдены
```json
{
"status": "error",
"reason": "user_not_found",
"errors": [],
"error_data": {}
}
```
### Поиск данных юзера по дополнительному идентификатору
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **other_id** [String] - дополнительный идентификатор
#### Пример параметров запроса
```
?other_id=some_id
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": {
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"ad_login": "ad_user_login1",
"ad_domain": "cts.com",
"name": "Bob",
"company": "Bobs Co",
"company_position": "Director",
"department": "Owners",
"emails": [
"ad_user@cts.com", "user1@cts.com"
],
"other_id": "some_id1",
"user_kind": "cts_user",
"active": true,
"created_at": "2023-03-26T14:36:08.740618Z",
"cts_id": "e0140f4c-4af2-5a2e-9ad1-5f37fceafbaf",
"description": "Director in Owners dep",
"ip_phone": 1271020,
"manager": "Alice",
"office": "SUN",
"other_ip_phone": null,
"other_phone": null,
"public_name": "Bobby",
"rts_id": "f46440a4-d930-58d4-b3f5-8110ab846ee3",
"updated_at": "2023-03-26T14:36:08.740618Z",
}
}
```
#### Ошибка (404): Данные юзера не найдены
```json
{
"status": "error",
"reason": "user_not_found",
"errors": [],
"error_data": {}
}
```
### Получение списка пользователей на CTS
#### Описание
Обрабатывается синхронно
Список пользователей выдаётся в виде csv-файла со следующим набором столбцов:
* **HUID** [UUID] - идентификатор пользователя
* **AD Login** [String] - AD-логин (Active Directory) пользователя
* **Domain** [String] - AD-домен пользователя
* **AD E-mail** [String] (Default: null) - AD-email пользователя
* **Name** [String] - имя пользователя
* **Sync source** [String] - источник синхронизации (`ad`, `admin`, `email`, `openid`)
* **Active** [Boolean] - флаг активности пользователя
* **Kind** [String] - тип пользователя (`cts_user`, `unregistered`, `botx`)
* **Company** [String] (Default: null) - имя компании пользователя
* **Department** [String] (Default: null) - отдел, в котором работает пользователь
* **Position** [String] (Default: null) - должность пользователя
#### Заголовки
* authorization - "Bearer <token>"
#### Параметры запроса
* **cts_user** [Boolean] (Default: true) - включить в результат пользователей с типом `cts_user`
* **unregistered** [Boolean] (Default: true) - включить в результат пользователей с типом `unregistered`
* **botx** [Boolean] (Default: false) - включить в результат пользователей с типом `botx`
#### Пример параметров запроса
```
?cts_user=true&unregistered=false
```
#### Пример успешного ответа
```
HUID,AD Login,Domain,AD E-mail,Name,Sync source,Active,Kind,Company,Department,Position
dbc8934f-d0d7-4a9e-89df-d45c137a851c,test_user_17,cts.example.com,,test_user_17,ad,true,cts_user,,,
5c1d8ec4-24c9-4dea-af13-075c52444f08,test11,cts.example.com,test11@domain.com,test11 edit,ad,true,cts_user,,,
2ffb8c03-380a-43c5-9caa-ae88d2f9032e,test-5,cts.example.com,test-5@domain.com,test-5,ad,true,cts_user,,,
```
#### Ошибка (400): Не выбран ни один из типов пользовалей
```json
{
"status": "error",
"reason": "no_user_kind_selected",
"errors": [],
"error_data": {}
}
```
### Обновление профиля юзера
#### Описание
Обрабатывается синхронно
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **user_huid** [String] - идентификатор юзера
* **name** [String] (Default: skip) - имя юзера
* **public_name** [String] (Default: skip) - публичное имя юзера
* **avatar** [String] (Default: skip) - аватар пользователя в формате data URL + base64 data (RFC 2397)
* **company** [String] (Default: skip) - компания
* **company_position** [String] (Default: skip) - должность
* **description** [String] (Default: skip) - описание/заметки
* **department** [String] (Default: skip) - отдел
* **office** [String] (Default: skip) - адрес офиса
* **manager** [String] (Default: skip) - руководитель
#### Пример параметров запроса
```json
{
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364",
"name": "John Bork",
"public_name": "Johny B.",
"avatar": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=",
"company": "Doge Co",
"company_position": "Chief",
"description": "Just boss",
"department": "Commercy",
"office": "Moscow",
"manager": "Bob"
}
```
#### Пример успешного ответа
```json
{
"status": "ok",
"result": true
}
```
#### Ошибка (404): Юзер не найден
```json
{
"status": "error",
"reason": "user_not_found",
"errors": [],
"error_data": {
"error_description": "User with specified id not found",
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364"
}
}
```
#### Ошибка (400): Неправильные данные для профиля
```json
{
"status": "error",
"reason": "invalid_profile",
"errors": [],
"error_data": {
"errors": {"field": "invalid"},
"error_description": "Invalid profile data",
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364"
}
}
```
#### Ошибка (503): Ошибка от сервиса ad_phonebook
```json
{
"status": "error",
"reason": "error_from_ad_phonebook_service",
"errors": [],
"error_data": {
"reason": "some_error",
"error_description": "AdPhonebook service returns error. Check BotX container logs (level :warn or upper) for more info.",
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364"
}
}
```
#### Ошибка (503): Непредвиденная ошибка
```json
{
"status": "error",
"reason": "unexpected_error",
"errors": [],
"error_data": {
"error_description": "Got unexpected error. Check BotX container logs (level :error or upper) for more info.",
"user_huid": "6fafda2c-6505-57a5-a088-25ea5d1d0364"
}
}
```
## [Smartapps API](/s/hDVrwP1Sy)
## Files API
### Список методов
| Метод | URL | Описание |
| ----- | ----------------------------------------- | ----------------------------------------------- |
| GET | /api/v3/botx/files/download | Скачивание файла |
| POST | /api/v3/botx/files/upload | Загрузка файла |
### Скачивание файла
#### Описание
* Обрабатывается синхронно.
#### Заголовки
* authorization - "Bearer <token>"
* content-type - "application/json"
#### Параметры запроса
* **group_chat_id** [UUID] - идентификатор чата
* **file_id** [UUID] - идентификатор файла
* **is_preview** [Boolean] (Default: false) - если true и файл имеет preview, то вернется содержимое preview, иначе оригинал
#### Пример запроса
```
?group_chat_id=84a12e71-3efc-5c34-87d5-84e3d9ad64fd
&file_id=e48c5612-b94f-4264-adc2-1bc36445a226
&is_preview=false
```
#### Успешный ответ (200)
```http
HTTP/1.1 200
Content-Type: image/jpeg
<image_binary>
```
#### Чат не найден (404)
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"error_description": "Chat with specified id not found"
}
}
```
#### Ошибка messaging сервиса при запросе чата (500)
```json
{
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"reason": "some_error",
"error_description": "Chat info fetching failed. Check BotX container logs (level :warn or upper) for more info."
}
}
```
#### Метаданные файла не найдены (404)
```json
{
"status": "error",
"reason": "file_metadata_not_found",
"errors": [],
"error_data": {
"file_id": "e48c5612-b94f-4264-adc2-1bc36445a226",
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"error_description": "File with specified file_id and group_chat_id not found in file service"
}
}
```
#### Файл сервис вернул ошибку при запросе метаданных файла (500)
```json
{
"status": "error",
"reason": "error_from_file_service",
"errors": [],
"error_data": {
"file_id": "e48c5612-b94f-4264-adc2-1bc36445a226",
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"reason": "some_error",
"error_description": "File metadata fetching failed. Check BotX container logs (level :warn or upper) for more info."
}
}
```
#### Файл удален (204)
```json
{
"status": "error",
"reason": "file_deleted",
"errors": [],
"error_data": {
"link": "/uploads/files/b9197d3a-d855-5d34-ba8a-eff3a975ab20/c6e39e617aee4613bd0d6a47738b6368.jpeg?v=1627067439978",
"error_description": "File at the specified link has been deleted"
}
}
```
#### Ошибка при скачивание файла (500)
```json
{
"status": "error",
"reason": "file_download_failed",
"errors": [],
"error_data": {
"link": "/uploads/files/b9197d3a-d855-5d34-ba8a-eff3a975ab20/c6e39e617aee4613bd0d6a47738b6368.jpeg?v=1627067439978",
"error_description": "Got error on file downloading. Check BotX container logs (level :warn or upper) for more info."
}
}
```
#### Ошибка при скачивание файла из s3 файл сервиса (500)
```json
{
"status": "error",
"reason": "error_from_s3_file_service",
"errors": [],
"error_data": {
"source_link": "/uploads/files/b9197d3a-d855-5d34-ba8a-eff3a975ab20/c6e39e617aee4613bd0d6a47738b6368.jpeg?v=1627067439978",
"location": "https://bucketexample.s3.amazonaws.com/E54SAFSA",
"error_description": "Got error on downloading file from s3 file service. Check BotX container logs (level :warn or upper) for more info."
}
}
```
#### Файл не имеет preview (400)
```json
{
"status": "error",
"reason": "file_without_preview",
"errors": [],
"error_data": {
"file_id": "e48c5612-b94f-4264-adc2-1bc36445a226",
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"error_description": "Preview was requested but file doesn't have preview"
}
}
```
### Загрузка файла
#### Описание
* Обрабатывается синхронно
* Содержимое файла и параметры передается в формате multipart/form-data с boundary
#### Заголовки
* authorization - "Bearer <token>"
* content-type: multipart/form-data; boundary=<boundary string>
#### Параметры запроса
* **group_chat_id** [UUID5] - идентификатор чата
* **file_name** [String] - имя файла. Берется из content
* **mime_type** [String] - mime тип файла. Берется из content
* **content** [Binary] - бинарное содержимое файла
* **meta** [Object] - метаданные файла
* **duration** [Integer] (Default: null) - длительность видео/аудио в секундах
* **caption** [String] (Default: null) - caption файла
#### Пример запроса
```http
POST /api/v3/files/upload HTTP/1.1
Content-Type: multipart/form-data; boundary=4d9aa92c
--4d9aa92c
Content-Disposition: form-data; name="content"; filename="image.jpeg"
Content-Type: image/jpeg
<image binary>
--4d9aa92c
Content-Disposition: form-data; name="group_chat_id"
d297a43f-e1c6-4e07-8081-e25c04364acc
--4d9aa92c
Content-Disposition: form-data; name="meta"
Content-Type: application/json
{
"duration": null,
"caption": "Мое видео"
}
--4d9aa92c--
```
#### Успешный ответ (200)
* **status** [String] - "ok"
* **result** [Object]
* **type** [String] - "image"
* **file** [String] - ссылка на файл
* **file_mime_type** [String] - mime type файла
* **file_name** [String] - имя файла
* **file_preview** [String] (Default: null) - ссылка на превью
* **file_preview_height** [Integer] (Default: null) - высота файла в px
* **file_preview_width** [Integer] (Default: null) - ширина файла в px
* **file_size** [Integer] - размер файла
* **file_hash** [String] - хэш файла
* **file_encryption_algo** [String] - "stream"
* **chunk_size** [Integer] - размер чанков
* **file_id** [UUID5] - идентификатор файла
* **caption** [String] (Default: null) - caption файла
* **duration** [Integer] (Default: null) - длительность аудио/видео
```json
{
"status": "ok",
"result": {
"type": "image",
"file": "https://link.to/file",
"file_mime_type": "image/png",
"file_name": "pass.png",
"file_preview": "https://link.to/preview",
"file_preview_height": 300,
"file_preview_width": 300,
"file_size": 1502345,
"file_hash": "Jd9r+OKpw5y+FSCg1xNTSUkwEo4nCW1Sn1AkotkOpH0=",
"file_encryption_algo": "stream",
"chunk_size": 2097152,
"file_id": "8dada2c8-67a6-4434-9dec-570d244e78ee",
"caption": "текст",
"duration": null
}
}
```
#### Чат не найден (404)
```json
{
"status": "error",
"reason": "chat_not_found",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"error_description": "Chat with specified id not found"
}
}
```
#### Ошибка messaging сервиса при запросе чата (500)
```json
{
"status": "error",
"reason": "error_from_messaging_service",
"errors": [],
"error_data": {
"group_chat_id": "84a12e71-3efc-5c34-87d5-84e3d9ad64fd",
"reason": "some_error",
"error_description": "Chat info fetching failed. Check BotX container logs (level :warn or upper) for more info."
}
}
```
#### Неправильный mimetype (500)
```json
{
"status": "error",
"reason": "flow_processing_error",
"errors": ["invalid mimetype", "unsupported file type"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info."
}
}
```
#### Неподдерживаемый тип файла (500)
```json
{
"status": "error",
"reason": "flow_processing_error",
"errors": ["unsupported file type"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info."
}
}
```
#### Сервис ключей (KDC) вернул ошибку при запросе ключа бота (500)
```json
{
"status": "error",
"reason": "flow_processing_error",
"errors": ["sender public key fetching failed"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info."
}
}
```
#### Сервис ключей (KDC) вернул ошибку при запросе ключей получателей (500)
```json
{
"status": "error",
"reason": "flow_processing_error",
"errors": ["recipients public keys fetching failed"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info."
}
}
```
#### Файл сервис вернул ошибку при загрузке файла (500)
```json
{
"status": "error",
"reason": "flow_processing_error",
"errors": ["uploading file to file service failed", "file service error: some_error"],
"error_data": {
"error_description": "Got error on flow processing. Check BotX container logs (level :info or upper) for more info."
}
}
```
## [Stickers API](/xmH5kv4mSCWRny5LEzS8oA)
## [OpenID API](/s/oAlnnwLB0#)
## [Metrics API](/s/s0luyL_Rj#)