# 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"
}
]
}
}
```