3276 views
# Express - Платформа BotX: HTTP(s) BotX API ## Ограничения API ### Длина запроса Общая длина запроса (Content-Length) не должна превышать 133 мб При этом суммарный вес JSON полей запроса (исключая вес файла) не должен превышать 1мб ### Размер передаваемого файла Размер передаваемого файла не должен превышать 100 мб, что составляет ~133 мб в 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>" } ``` ## 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: nil) - 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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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": nil, "notification": { "status": "ok", "body": "Выберите пункт меню", "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_data": { "user_huid": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4", "name": "Gena the Croc", "mention_id": "a465f0f3-1354-491c-8f11-f400164295cb" } } ] }, "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#Загрузка-файла) ### Отправка внутренней бот нотификации #### Описание * Обрабатывается асинхронно * На запрос установлено ограничение интенсивности: 100 запросов в 15 минут * В ответ на запрос приходит **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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 | ### Редактирование события #### Описание * Редактирование содержимого события (результата команды или нотификации) * Можно редактировать только те события, что были отправлены текущим ботом * Обрабатывается асинхронно #### Логика обновления полей события * Если поле не указано в запросе, то оно не обновляется * Для полей 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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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, то выведется тело команды * **handler** [String] (Default: "bot") - если значение "client", то при нажатии на кнопку команда не должна отправляться боту, а должна обрабатываться самим клиентом * **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: nil) - файл в бинарном представление (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": nil, "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]] - список идентификаторов устройств (udid), получивших событие * **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 #### Описание Обрабатывается асинхронно #### Заголовки * 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 #### Описание Обрабатывается асинхронно #### Заголовки * 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" } ``` ## 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) - время сгорания для прочитавшего, в секундах (по-умолчанию nil - выключено * **expire_in** [Integer] (Default: null) - время сгорания для всех участников чата, в секундах (по-умолчанию nil - выключено) #### Пример запроса ```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" } } ``` ### Создание чата #### Описание Обрабатывается синхронно Создателем чата будет являться бот, который инициировал запрос Бот будет добавлен в список участников чата, даже если он явно не указан в списке при отправке запроса Чтобы бот мог создавать чат, в панели администратора ему нужно задать свойство **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: nil) - аватар чата в формате data URL + base64 data (RFC 2397) * **shared_history** [Boolean] (Default: false) - если true, то созданный чат будет иметь признаки шаред чата #### Пример запроса ```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 | Поиск данных юзера по его почте | | 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 | Поиск данных юзера по дополнительному идентификатору | | PUT | /api/v3/botx/users/update_profile | Обновление профиля юзера | ### Поиск данных юзера по его почте #### Описание Обрабатывается синхронно #### Заголовки * 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" } } ``` #### Ошибка (404): Данные юзера не найдены ```json { "status": "error", "reason": "user_not_found", "errors": [], "error_data": {} } ``` ### Поиск данных юзера по его 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_login", "ad_domain": "cts.com", "name": "Bob", "company": "Bobs Co", "company_position": "Director", "department": "Owners", "emails": [ "ad_user@cts.com" ], "other_id": "some_id" } } ``` #### Ошибка (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_login", "ad_domain": "cts.com", "name": "Bob", "company": "Bobs Co", "company_position": "Director", "department": "Owners", "emails": [ "ad_user@cts.com" ], "other_id": "some_id" } } ``` #### Ошибка (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_login", "ad_domain": "cts.com", "name": "Bob", "company": "Bobs Co", "company_position": "Director", "department": "Owners", "emails": [ "ad_user@cts.com" ], "other_id": "some_id" } } ``` #### Ошибка (404): Данные юзера не найдены ```json { "status": "error", "reason": "user_not_found", "errors": [], "error_data": {} } ``` ### Обновление профиля юзера #### Описание Обрабатывается синхронно #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **user_huid** [String] - идентификатор юзера * **name** [String] (Default: skip) - имя юзера * **public_name** [String] (Default: skip) - публичное имя юзера * **avatar** [Object] (Default: skip) - файл в base64 представление. * file_name [String] - имя файла * data [String] - 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": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=", "file_name": "avatar.png" }, "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 ### Список методов | Метод | URL | Описание | | ----- | ----------------------------------------- | ----------------------------------------------- | | POST | /api/v3/botx/smartapps/event | Отправка smartapp события | | POST | /api/v3/botx/smartapps/notification | Отправка smartapp нотификации | ### Отправка smartapp события #### Описание Обрабатывается асинхронно #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **ref** [UUID] (Default: null) - уникальный идентификатор запроса * **smartapp_id** [UUID] - ID смарт аппа * **group_chat_id** [UUID] - ID чата * **data** [Object] - пользовательские данные * **opts** [Object] - опции запроса * **smartapp_api_version** [Integer] - версия протокола smartapp <-> bot * **files** [Array[Object]] (Default: []) - массив файлов в base64 * **file_name** [String] - имя файла * **data** [String] - data URL + base64 data (RFC 2397) * **caption** [String] (Default: null) - текст под файлом * **file_id** [UUID5] (Default: null) - ID файла с которым он будет загружен и сохранен в File Service * **async_files** [Array[Object]] - метаданные файлов для отложенной обработки * **type** [String] - тип файла * **file** [String] - ссылка на файл * **file_mime_type** [String] - mimetype файла * **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** [UUID] - ID файла * **duration** [Integer] (Default: Null) - длительность видео/аудио * **caption** [String] (Default: Null) - подпись под файлом #### Пример запроса ```json { "ref": "6fafda2c-6505-57a5-a088-25ea5d1d0364", "smartapp_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c", "data": { "headers": { "key": "value" }, "body": "XawLhuWPa8ThvXzGo1R3SlnMxo0R8+H7JRC6Y5UkpHA=", "status": 200 }, "opts": {}, "smartapp_api_version": 1, "files": [ { "data": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=", "file_name": "card.png", "file_id": "cd517124-04e6-4dbd-a7ef-4c005cb472a3" } ], "async_files": [ { "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" } ] } ``` #### Пример успешного ответа ```json { "status": "ok", "result": "smartapp_event_pushed" } ``` ### Отправка smartapp нотификации #### Описание Обрабатывается асинхронно #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **group_chat_id** [UUID] - ID чата * **smartapp_counter** [Integer] - значение каунтера приложения * **opts** [Object] - опции запроса * **smartapp_api_version** [Integer] - версия протокола smartapp <-> bot * **body** [String] (Default: null) - текст оповещения * **meta** [Object] (Default: {}) - объект с доп. информацией #### Пример запроса ```json { "group_chat_id": "705df263-6bfd-536a-9d51-13524afaab5c", "smartapp_counter" : 42, "opts": {}, "smartapp_api_version": 1 } ``` #### Пример успешного ответа ```json { "status": "ok", "result": "smartapp_notification_pushed" } ``` ## Stickers API ### Список методов | Метод | URL | Описание | | ----- | ----------------------------------------- | ----------------------------------------------- | | GET | /api/v3/botx/stickers/packs | Получение списка наборов стикеров | | GET | /api/v3/botx/stickers/packs/:pack_id | Получение набора стикеров | | GET | /api/v3/botx/stickers/packs/:pack_id/stickers/:sticker_id | Получение стикера из набора стикеров | | POST | /api/v3/botx/stickers/packs | Создание набора стикеров | | POST | /api/v3/botx/stickers/packs/:pack_id/stickers | Добавление стикера в набор стикеров | | PUT | /api/v3/botx/stickers/packs/:pack_id | Редактирование набора стикеров | | DELETE | /api/v3/botx/stickers/packs/:pack_id | Удаление набора стикеров | | DELETE | /api/v3/botx/stickers/packs/:pack_id/stickers/:sticker_id | Удаление стикера из набора стикеров | ### Получение списка наборов стикеров #### Описание * Обрабатывается синхронно. * Для перемещения по списку используется пагинация. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **user_huid** [UUID] (Default: null) - уникальный идентификатор создателя набора(ов) стикеров * **limit** [Integer] (Default: null) - максимальное количество наборов в списке * **after** [String] (Default: null) - base64 строка с мета информацией для перемещения по списку. Генерируется на стороне сервера. Содержится в ответе на каждый запрос в объекте `pagination` (см. пример успешного ответа). #### Пример запроса ``` ?user_huid=84a12e71-3efc-5c34-87d5-84e3d9ad64fd&limit=10&after=ABCEoS5xPvxcNIfVhOPZrWT9AA0ACnVwZGF0ZWRfYXQAf____QAAAAA= ``` #### Пример успешного ответа (200) ```json { "status": "ok", "result": { "packs": [ { "id": "26080153-a57d-5a8c-af0e-fdecee3c4435", "name": "Sticker Pack", "preview": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/9df3143975ad4e6d93bf85079fbb5f1d.png?v=1614781425296", "public": true, "stickers_count": 2, "stickers_order": [ "a998f599-d7ac-5e04-9fdb-2d98224ce4ff", "25054ac4-8be2-5a4b-ae00-9efd38c73fb7" ], "inserted_at": "2020-11-28T12:56:43.672163Z", "updated_at": "2021-02-18T12:52:31.571133Z", "deleted_at": null, } ], "pagination": { "after": "ABAmCAFTpX1ajK8O_ezuPEQ1AA0ACnVwZGF0ZWRfYXQAf____gAAAAA=" } } } ``` ### Получение набора стикеров #### Описание Обрабатывается синхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **pack_id** [UUID] - уникальный идентификатор набора стикеров #### Пример запроса ``` /api/v3/botx/stickers/packs/26080153-a57d-5a8c-af0e-fdecee3c4435 ``` #### Пример успешного ответа (200) ```json { "status": "ok", "result": { "id": "26080153-a57d-5a8c-af0e-fdecee3c4435", "name": "Sticker Pack", "public": true, "preview": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/b4577728162f4d9ea2b35f25f9f0dcde.png?v=1626137130775", "stickers_order": [ "528c3953-5842-5a30-b2cb-8a09218497bc", "75bb24c9-7c08-5db0-ae3e-085929e80c54" ], "stickers": [ { "id": "528c3953-5842-5a30-b2cb-8a09218497bc", "emoji": "😀", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/e7a73cf1b6164b15bc46f21aacfa734f.png?v=1626137621017", "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null }, { "id": "75bb24c9-7c08-5db0-ae3e-085929e80c54", "emoji": "🤔", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/b4577728162f4d9ea2b35f25f9f0dcde.png?v=1626137130775", "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null } ], "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null } } ``` ### Получение стикера из набора стикеров #### Описание Обрабатывается синхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **pack_id** [UUID] - уникальный идентификатор набора стикеров * **sticker_id** [UUID] - уникальный идентификатор стикера в наборе стикеров #### Пример запроса ``` /api/v3/botx/stickers/packs/26080153-a57d-5a8c-af0e-fdecee3c4435/stickers/528c3953-5842-5a30-b2cb-8a09218497bc ``` #### Пример успешного ответа (200) ```json { "status": "ok", "result": { "id": "528c3953-5842-5a30-b2cb-8a09218497bc", "emoji": "😀", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/1a036cec0df042898540824717c5ac32.png?v=1607014055820", "preview": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/c9bfcd8eb4224f7a98de28bdcbffc2b2.png?v=1610438587839" } } ``` ### Создание набора стикеров #### Описание * Обрабатывается синхронно. * Создает только непубличные наборы стикеров (набор виден только на CTS с ботом). #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **name** [String] - название набора стикеров * **user_huid** [UUID] (Default: null) - huid создателя набора #### Пример запроса ```json { "name": "Sticker Pack" } ``` #### Пример успешного ответа (201) ```json { "status": "ok", "result": { "id": "26080153-a57d-5a8c-af0e-fdecee3c4435", "name": "Sticker Pack", "public": false, "preview": null, "stickers": [], "stickers_order": [], "inserted_at": "2021-07-10T00:27:55.616703Z", "updated_at": "2021-07-10T00:27:55.616703Z", "deleted_at": null } } ``` ### Добавление стикера в набор стикеров #### Описание * Обрабатывается синхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **emoji** [String] - эмодзи стикера * **image** [String] - изображение стикера в base64 формате #### Пример запроса ```json { "emoji": "🤔", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhE", } ``` #### Пример успешного ответа (201) ```json { "status": "ok", "result": { "id": "75bb24c9-7c08-5db0-ae3e-085929e80c54", "emoji": "🤔", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/b4577728162f4d9ea2b35f25f9f0dcde.png?v=1626137130775", "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null } } ``` ### Редактирование набора стикеров #### Описание Обрабатывается синхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **name** [String] - название набора стикеров * **preview** [UUID] - уникальный идентификатор стикера из набора, выбранного в качестве превью * **stickers_order** [Array[UUID]] - список идентификаторов стикеров набора в порядке их отображения. Для изменения порядка необходимо передавать весь список идентификаторов, в противном случае параметр игнорируется #### Пример запроса ```json { "name": "Sticker Pack 2.0", "preview": "75bb24c9-7c08-5db0-ae3e-085929e80c54", "stickers_order": ["75bb24c9-7c08-5db0-ae3e-085929e80c54", "528c3953-5842-5a30-b2cb-8a09218497bc"] } ``` #### Пример успешного ответа (200) ```json { "status": "ok", "result": { "id": "26080153-a57d-5a8c-af0e-fdecee3c4435", "name": "Sticker Pack 2.0", "public": true, "preview": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/b4577728162f4d9ea2b35f25f9f0dcde.png?v=1626137130775", "stickers_order": [ "75bb24c9-7c08-5db0-ae3e-085929e80c54", "528c3953-5842-5a30-b2cb-8a09218497bc" ], "stickers": [ { "id": "75bb24c9-7c08-5db0-ae3e-085929e80c54", "emoji": "🤔", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/b4577728162f4d9ea2b35f25f9f0dcde.png?v=1626137130775", "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null }, { "id": "528c3953-5842-5a30-b2cb-8a09218497bc", "emoji": "😀", "link": "/uploads/sticker_pack/26080153-a57d-5a8c-af0e-fdecee3c4435/e7a73cf1b6164b15bc46f21aacfa734f.png?v=1626137621017", "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2020-12-28T12:56:43.672163Z", "deleted_at": null } ], "inserted_at": "2020-12-28T12:56:43.672163Z", "updated_at": "2021-07-22T13:26:41.562143Z", "deleted_at": null } } ``` ### Удаление набора стикеров #### Описание Обрабатывается асинхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **pack_id** [UUID] - уникальный идентификатор набора стикеров #### Пример запроса ``` /api/v3/botx/stickers/packs/26080153-a57d-5a8c-af0e-fdecee3c4435 ``` #### Пример успешного ответа (202) ```json { "status": "ok", "result": "delete_sticker_pack_pushed" } ``` ### Удаление стикера из набора стикеров #### Описание Обрабатывается асинхронно. #### Заголовки * authorization - "Bearer <token>" * content-type - "application/json" #### Параметры запроса * **pack_id** [UUID] - уникальный идентификатор набора стикеров * **sticker_id** [UUID] - уникальный идентификатор стикера из набора стикеров #### Пример запроса ``` /api/v3/botx/stickers/packs/26080153-a57d-5a8c-af0e-fdecee3c4435/stickers/528c3953-5842-5a30-b2cb-8a09218497bc ``` #### Пример успешного ответа (202) ```json { "status": "ok", "result": "delete_sticker_from_pack_pushed" } ``` ## 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": "Мое видео" } ``` #### Успешный ответ (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." } } ```