2275 views
# Express - Платформа BotX: HTTP(s) Bot API v3 ## HTTP(S) интерфейс бота (v3) :::warning Данное API является устаревшим и более не поддерживается :zap: ::: Для использования ботом 3й версии протокола необходимо в панели администратора, на странице бота, указать значение 3 у аттрибута "Версия протокола" | Метод | URL | Описание | | ----- | -------- | --------------------------------- | | POST | /command | Обработка команд | | GET | /status | Получение статуса и списка команд | ### Обработка команд #### Описание Обрабатывается асинхронно. #### Параметры запроса * **sync_id** [UUID] - идентификатор сообщения в системе Express * **source_sync_id** [UUID](Default: nil) - идентификатор исходного сообщения (сообщения в котором находились элементы интерфейса) в системе Express * **command** [Object] * **body** [String] - тело команды * **command_type** [String] - тип команды (user|system) * **data** [Object] - данные команды полученные на основе введеных пользователем данных через элементы UI или при нажатие на кнопку * **metadata** [Object] - метаданные заложенные в объекте сообщения от бота * **file** [Object] * **data** [String] - содержимое файла в base64 * **file_name** [String] - имя файла * **caption** [String] (Default: null) - текст под файлом * **from** [Object] * **user_huid** [UUID] - huid юзера который отправил команду * **group_chat_id** [UUID] - id чата в который отправили команда * **chat_type** [String] - тип чата (chat или group_chat) * **ad_login** [String] - логин юзера который отправил команду * **ad_domain** [String] - домен юзера который отправил команду * **username** [String] - имя юзера который отправил команду * **is_admin** [Boolean] - является ли юзер админом чата * **is_creator** [Boolean] - является ли юзер создателем чата * **manufacturer** [String] - имя бренда производителя * **device** [String] - название девайса * **device_software** [String] - ОС девайса * **device_meta** [Object] * **pushes** [Boolean] - разрешение приложению на отправку пушей * **timezone** [String] - таймзона пользователя * **permissions** [Object] - различные разрешения приложения (использование микрофона, камеры и тд) * **platform** [String] - название клиентской платформы (web|android|ios|desktop) * **platform_package_id** [String] - идентификатор пакета с данными приложения и устройства * **app_version** [String] - версия приложения Express * **locale** [String] - локаль текущей сессии * **host** [String] - имя хоста с которого пришла команда * **bot_id** [UUID] - идентификатор бота в системе Express * **proto_version** [Integer] - версия протокола (BotX -> Bot) используемая при отправке команды * **entities** [Array[Object]] - особые сущности переданные в сообщение. Например: меншны, хэштеги, ссылки, форварды * **type** [String] - тип сущности * **data** [Object] - объект с данными сущности #### Пример запроса ```json { "sync_id": "a465f0f3-1354-491c-8f11-f400164295cb", "command": { "body": "/doit #6", "command_type": "user", "data": {}, "metadata": {"account_id": 94} }, "file": { "data": "data:image/png;base64,eDnXAc1FEUB0VFEFctII3lRlRBcetROeFfduPmXxE/8=", "file_name": "card.png", "caption": "card #4" }, "from": { "user_huid": "ab103983-6001-44e9-889e-d55feb295494", "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "ad_login": "example_login", "ad_domain": "example.com", "username": "Bob", "is_admin": true, "is_creator": true, "chat_type": "group_chat", "host": "cts.ccteam.ru" }, "bot_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4", "entities": [ { "type": "mention", "data": { "mention_type": "contact", "mention_id": "c06a96fa-7881-0bb6-0e0b-0af72fe3683f", "mention_data": { "user_huid": "ab103983-6001-44e9-889e-d55feb295494", "name": "Вася Иванов", "conn_type": "cts" } } } ] } ``` #### HTTP статус ответа 202 #### Параметры ответа ##### Успешный ответ Не имеет значения ##### Ошибка (Бот отключен) * reason - причина ошибка. Значение должно быть: "bot_disabled" * error_data - объект с данными об ошибке. Должен включать в себя ключ "status_message". #### Пример ответа ##### Успешный ответ http status: 202 ```json { "result": "accepted" } ``` ##### Ошибка (Бот отключен) http status: 503 ```json { "reason": "bot_disabled", "error_data": {"status_message": "please stand by"}, "errors": [] } ``` #### Системные команды BotX отправляет системные команды после некоторых операций. Системные команды имеют зарезервированное пространство имен "system:". ##### chat_created * Событие отправляется при создание чата * Название: **"system:chat_created"** * Параметры: см. пункт "Обработка команд" * Вложенные Данные (поле command["data"]): * group_chat_id [UUID5] - uuid чата * chat_type [String] - тип чата * name [String] - имя чата * creator [UUID5] - huid создателя чата * members [Array[Object]] * huid [UUID5] - huid участника * name [String] - имя участника * user_kind [String] - тип участника * admin [Boolean] - является/не является админом * Пример: ```json { "sync_id": "a465f0f3-1354-491c-8f11-f400164295cb", "command": { "body": "system:chat_created", "data": { "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "chat_type": "group_chat", "name": "Meeting Room", "creator": "ab103983-6001-44e9-889e-d55feb295494", "members": [ { "huid": "ab103983-6001-44e9-889e-d55feb295494", "name": "Bob", "user_kind": "user", "admin": true }, { "huid": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4", "name": "Funny Bot", "user_kind": "botx", "admin": false } ] }, "command_type": "system" }, "file": nil, "from": { "user_huid": nil, "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "ad_login": nil, "ad_domain": nil, "username": nil, "chat_type": "group_chat", "host": "cts.ccteam.ru" }, "bot_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" } ``` ##### added_to_chat * Событие отправляется при добавление мемберов в чат * Название: **"system:added_to_chat"** * Параметры: см. пункт "Обработка команд" * Вложенные Данные (поле command["data"]): * added_members [Array[UUID5]] - список добавленных мемберов * Пример: ```json { "sync_id": "a465f0f3-1354-491c-8f11-f400164295cb", "command": { "body": "system:added_to_chat", "data": { "added_members": [ "ab103983-6001-44e9-889e-d55feb295494", "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" ] }, "command_type": "system" }, "file": nil, "from": { "user_huid": nil, "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "ad_login": nil, "ad_domain": nil, "username": nil, "chat_type": "group_chat", "host": "cts.ccteam.ru" }, "bot_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" } ``` ##### deleted_from_chat * Событие отправляется при удалении администратором участников чата * Название: **"system:deleted_from_chat"** * Параметры: см. пункт "Обработка команд" * Вложенные Данные (поле command["data"]): * deleted_members [Array[UUID5]] - список идентификаторов удаленных пользователей * Пример: ```json { "sync_id": "a465f0f3-1354-491c-8f11-f400164295cb", "command": { "body": "system:deleted_from_chat", "data": { "deleted_members": [ "ab103983-6001-44e9-889e-d55feb295494", "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" ] }, "command_type": "system" }, "file": nil, "from": { "user_huid": nil, "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "ad_login": nil, "ad_domain": nil, "username": nil, "chat_type": "group_chat", "host": "cts.ccteam.ru" }, "bot_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" } ``` ##### left_from_chat * Событие отправляется при выходе участников из чата * Название: **"system:left_from_chat"** * Параметры: см. пункт "Обработка команд" * Вложенные Данные (поле command["data"]): * "left_members": [[Array[UUID5]] - список идентификаторов покинувших чат пользователей * Пример: ```json { "sync_id": "a465f0f3-1354-491c-8f11-f400164295cb", "command": { "body": "system:left_from_chat", "data": { "left_members": [ "ab103983-6001-44e9-889e-d55feb295494", "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" ] }, "command_type": "system" }, "file": nil, "from": { "user_huid": nil, "group_chat_id": "8dada2c8-67a6-4434-9dec-570d244e78ee", "ad_login": nil, "ad_domain": nil, "username": nil, "chat_type": "group_chat", "host": "cts.ccteam.ru" }, "bot_id": "dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4" } ``` #### Типы Entities ##### mention * Пример: ```json { "type": "mention", "data": { "mention_type": "contact", "mention_id": "c06a96fa-7881-0bb6-0e0b-0af72fe3683f", "mention_data": { "user_huid": "ab103983-6001-44e9-889e-d55feb295494", "name": "Вася Иванов", "conn_type": "cts" } } } ``` * Описание data полей * **mention_type** [String] - тип mention (contact|chat|channel|user) * **mention_id** [UUID] - id mention используемого при подстановке в текст * **mention_data** [Object] При mention_type contact|user * **user_huid** [UUID] - huid контакта * **name** [String] - имя контакта * **conn_type** [String] - тип соединения контакта При mention_type chat|channel * **group_chat_id** [UUID] - id чата * **name** [String] - имя чата ##### forward * Пример: ```json { "type": "forward", "data": { "group_chat_id": "918da23a-1c9a-506e-8a6f-1328f1499ee8", "sender_huid": "c06a96fa-7881-0bb6-0e0b-0af72fe3683f", "forward_type": "chat", "source_chat_name": "Simple Chat", "source_sync_id": "a7ffba12-8d0a-534e-8896-a0aa2d93a434", "source_inserted_at": "2020-04-21T22:09:32.178Z" } } ``` * Описание data полей * **group_chat_id** [UUID] - id чата откуда переслали сообщение * **sender_huid** [UUID] - huid автора сообщения * **forward_type** [String] - chat|channel * **source_chat_name** [String] (Optional) - имя чата откуда переслали сообщение * **source_sync_id** [UUID] (Optional) - sync_id пересылаемого сообщения * **source_inserted_at** [DateTime] - ts пересылаемого сообщения ### Получение статуса и списка команд #### Описание Метод для получения статуса и списка команд бота. #### Заголовки * Authorization - "Bearer {token}" #### Параметры запроса * bot_id [UUID] - идентификатор бота в системе Express * user_huid [UUID] - идентификатор юзера, который запрашивает статус * ad_login [String](Default: null) - логин пользователя в Active Directory * ad_domain [String](Default: null) - домен пользователя в Active Directory * is_admin [Boolean](Default: null) - флаг, является ли пользователь админом в чате * chat_type [String] - тип чата в котором запрашивается статус #### Пример параметров запроса ``` ?bot_id=dcfa5a7c-7cc4-4c89-b6c0-80325604f9f4 &user_huid=ab103983-6001-44e9-889e-d55feb295494 &ad_login=exlogin &ad_domain=exdomain &is_admin=true &chat_type=chat ``` #### HTTP статус ответа 200 #### Параметры ответа * **status** [String] - "ok"|"error" * **result** [Object] * **enabled** [Boolean] (Default: true) - бот включен/выключен * **status_message** [String] (Default: null) - текущий статус бота * **commands** [Array[Object]] (Default: []) - список команд бота * **description** [String] - описание команды * **body** [String] - тело команды * **name** [String] - имя команды #### Пример ответа ```json { "status": "ok", "result": { "enabled": true, "status_message": "it's work!", "commands": [ { "description": "Add Comment", "name": "Comment", "body": "/comment #text" }, { "description": "Move to Doing", "name": "Doing", "body": "/doing" }, { "description": "Move to Doit", "name": "Doit", "body": "/doit" } ] } } ```