Инструкция для разработчиков чат-ботов

Функциональность	Permission
Отправить текстовое сообщение	conversation.messages.create
Отправить сообщение с файлом	conversation.messages.attachments.upload
Ответить на сообщение	conversation.messages.reply
Копировать сообщение	conversation.messages.copy
Редактировать свое сообщение	conversation.messages.own.update
Редактировать чужое сообщение	conversation.messages.other.update
Переслать сообщение из чата	conversation.messages.repost
Удалить свое сообщение	conversation.messages.own.delete
Удалить чужое сообщение	conversation.messages.other.delete
Комментировать сообщение	conversation.messages.comment
Сохранить файл на устройство	conversation.messages.attachments.download
Видеть индикатор "Печатает..."	conversation.indicators.subscribe
Изменить чат (название, аватар)	conversation.update
Удалить чат	conversation.delete
Покинуть чат (отписаться от треда)	conversation.leave
Очистить историю чата (для всех)	conversation.messages.clear
Добавить участника в чат (в рамках своего теннанта)	conversation.members.add
Удалить участника из чата	conversation.members.remove (Пользователь1 может удалять) + member.remove (Пользователь2 может быть удален)
Назначить участника администратором чата	conversation.members.role.switch (Пользователь1 может управлять ролями других пользователей) + member.role.switch (Пользователю2 можно менять роль)
Отозвать у администратора роль администратора
Скопировать/получить ссылку-приглашение в чат	conversation.join_link.get
Присоединиться в чат по ссылке-приглашению (в рамках своего теннанта) / Подписаться на тред	conversation.join
Упоминать отдельного участника чата	conversation.messages.mentions.create
Упоминать всех участников чата
Управлять уведомлениями (включить/отключить)	conversation.settings.notifications.switch
Позвонить в чат	conversation.event.call
Присоединиться к конференции чата	conversation.event.join
Добавить/убрать реакцию на сообщение	conversation.messages.react
Посмотреть пользователей, поставивших реакции на сообщение	conversation.messages.reactions.list
Посмотреть участников чата / совершить поиск по участникам чата	conversation.members.list
Открыть профиль (чата, участников чата)	conversation.profile.view
Поиск сообщений в чате по тексту	conversation.messages.search

Входные параметры	Параметр	Описание	Тип	Обязательность
	email	Адрес почты пользователя	string	*
	password	Пароль пользователя	string	*

Выходные параметры	Параметр	Описание	Тип	Обязательность
	access_token	Токен доступа ТУЗ	string	*
	user	Данные ТУЗ		*
	id	Идентификатор ТУЗ	uuid	*
	email	Адрес почты	string	*
	initials	Инициалы	string
	name	ФИО	string
	avatar_http_path	Путь к изображению (аватару)	string
	position	Должность	string
	roles	Роли	string[]	*
	is_profile_filled_in	Признак заполненности профиля	boolean

Коды состояния HTTP	Список возвращаемых кодов с кратким описанием: 200 Ok – запрос успешно выполнен, 400 Bad Request – неверно заполнены параметры запроса, 500 Internal Server Error – внутренняя ошибка сервера.

❗ В заголовке Authorization необходимо передавать токен Bearer, полученный в ответ на запрос POST https://bots-api.dion.vc/platform/v1/token.
Входные параметры	Параметр	Описание	Тип	Обязательность
Входные параметры	client_public_key	Публичный ключ клиента закодированный в base64.	string	*
Пример запроса Request URL: https://{host}/chats/v1/sessions Request Method: POST { "client_public_key":"BAOmKqgpq96uQ7VdcZMWOJ0Q95T8SvVMnyFWIQoq35H5kPFT0KpBctPJsMoCEvikV3fmXz4FTxTbV+RB3NJE25I=" }
Выходные параметры	Параметр	Описание	Тип	Обязательность
	server_public_key	Публичный ключ сервера в base64.	string	*
	session_id	Идентификатор крипто-сессии. Необходимо передавать в заголовке dc-crypto-session-id всех запросов из раздела "Доступные методы для работы в Dion.Чаты".	string	*
	valid_after	Время начала действия сессии.	string	*
	valid_before	Время окончания действия сессии.	string	*
Пример ответа { "session_id": "a654f474-b30f-46d5-9ce1-3c3962cbc072", "server_public_key": "BOyEDT4aiklkGEqlQRkl+MIaOynTHxkFmZEUfXSjtzS9isWGBgLpWX7U2ULXAzlC6F9X4VqzkqetdX1I5nJGkM4=", "valid_after": "2025-09-24T06:02:16.118887Z", "valid_before": "2025-09-24T16:03:16.118888Z" }
Коды состояния HTTP	Список возвращаемых кодов с кратким описанием: 201 Created – сессия создана, 400 Bad Request – неверно заполнены параметры запроса, 401 Unauthorized – недостаточно прав доступа или не указаны учетные данные, 500 Internal Server Error – внутренняя ошибка сервера.

Входные параметры (перед шифрованием)	❗ В заголовке Authorization необходимо передавать токен Bearer, полученный в ответ на запрос POST https://bots-api.dion.vc/platform/v1/token. ❗ В заголовке dc-crypto-session-id необходимо передавать идентификатор крипто-сессии, полученный методом POST /chats/v1/sessions. ❗ В заголовке dc-encoded-data-over-json необходимо передавать значение true.
	Параметр	Описание	Тип	Обязательность
	body
	name	Отображаемое имя/название бота Ограничения по длине строки: 3-255 символов	string	*
	description	Описание бота Ограничения по длине строки: 3-64 символов	string	*
	settings	Список настроек/возможностей бота Возможные значения: dm – боту можно писать в личный чат, он ответит, join_groups – бота можно добавлять в групповые чаты/чаты после конференций, join_channels – бота можно добавлять в каналы.	string[]	*
	commands	Команды, которые знает бот: Ограничения на количество команд: 0-20	object[]	*
	command	Название команды. Должно начинаться с "/" Ограничения по длине строки: 1-32 символов Ограничения по символам: доступны только английские буквы, цифры и символ подчеркивания "_"	string	*
	description	Описание команды: Ограничения по длине строки: 1-64 символа	string	*
Пример запроса (перед шифрованием)	Request URL: https://{host}/chats/v1/me Request Method: POST { "name": "BotFather", "description": "", "settings": ["dm", "join_groups"], "commands": [] }
Пример запроса (после шифрования)	Request URL: https://{host}/chats/v1/me Request Method: POST { "encrypted": "3Q3Y5sriqEv8yhCQF4XGxDxOTieoGztg1IWkpBS55c2PFDjJJgtcI2uPyfD 7WuxCBLP3aSKmqpGtu4RykZBZp27iZTsm1RSOpm+Tc1cNKg/DPXXfFyOIJvbC1Mq KGpS3V0HwXx5X/CpNpajp30lItPLNfktso6oqCeIisKxHuBeuz29sOemEd2oHUQTKo1 kD3L70N9yxZ7YS3ZTMJrcFYyuH43ur+qHWRT/+f3u/V3Qf9+JihwsHdayrneAjVxvXS W1ygjM+SXCleNhs+ZJ0vi0W3jBh6s4w4gU2nm3fCCq4ycGLnrUecOQffCLj7mJ9orm dX3Phknb++RIrcAGut1mSDHrS8JqU" }

Выходные параметры (после дешифрования)	Параметр	Описание	Тип	Обязательность
	id	Идентификатор ТУЗ бота	string	*
	name	Отображаемое имя/название бота	string	*
	description	Описание бота	string	*
	settings	Список настроек/возможностей бота Возможные значения: write_dm – боту можно писать в личный чат, он ответит, join_groups – бота можно добавлять в групповые чаты/чаты после конференций, join_channels – бота можно добавлять в каналы.	string[]	*
	commands	Команды, которые знает бот	object[]	*
	command	Название команды. Начинается с "/"	string	*
	description	Описание команды	string	*
Пример ответа (до дешифрования)	{ "encrypted":"h8uio7AgDTKrinSGD8XvKCDL/BJEtheQYgCWk4Tcze6Zpy/x USnohyJH1wJ1R9LElN7NKY7ZTus7LIUp4xwN9qsQzyR5zhwnnW+fmD/ WpgMaxNunKU5Ygj8BGUP0YDS0pFXZYn+rO2GyGDTEUuowkejDF52Ke0 kd/22vHFQMLyf+D7jBQajpNe24ZGzpgK9SSJpyC5o9X+ttRC7xTlyqY81Q PoW0Miyxr2BjrNYmBOCofnm6WfFrbXBTn1yh+u/GSkB4abx78Tx1+ELCq rtYGYfKh8Kh3EcrLItWeqHHZQDP5OofyGLYT25IjbtstUeGbXeyst/QxdoFAx 0ngItIPgtMcwoynODihTO5WxhMLO8a0R9y25lS73fJ395mjKyV3dek7DZR X2o9wcu1VgDwc/JYA1ou6O6VWGxdsfCo42Ubk5vAgF1YltdSvlc=" }
Пример ответа (после дешифрования)	{ "id": "9ed94dc4-99ee-49b5-a586-050b4fe51f5d", "name": "BotFather", "description": "", "settings": ["dm", "join_groups"], "commands": [] }
Особенности работы	В запросе: settings – набор свойств/умений/возможностей, которыми обладает бот. Если бот не умеет что-то делать, в массиве передавать параметр не нужно. Если массив пустой, значит бот ничего не умеет делать – нельзя добавлять его в группы, нельзя писать ему и т.д. В параметре command передаются команды, с которыми умеет работать бот. Если массив пустой, значит бот не знает ни одной команды.
Коды состояния HTTP	Список возвращаемых кодов с кратким описанием: 200 Ok – запрос успешно выполнен, 400 Bad Request – неверно заполнены параметры запроса, 401 Unauthorized – недостаточно прав доступа или не указаны учетные данные, 428 Precondition Required – ошибка криптографической сессии, 500 Internal Server Error – внутренняя ошибка сервера.

Входные параметры	❗В заголовке "Authorization" необходимо передавать токен Bearer, полученный в ответ на запрос POST https://bots-api.dion.vc/platform/v1/token.
	Параметр	Описание	Тип	Обязательность
	body
	client_public_key	Публичный ключ клиент закодированный в base64.	string	*
Пример запроса	Request URL: https://{host}/chats/v1/sessions Request Method: POST { "client_public_key":"BAOmKqgpq96uQ7VdcZMWOJ0Q95T8SvVMnyFWIQoq35H5kPFT0KpBctPJsMoCEvikV3fmXz4FTxTbV+RB3NJE25I=" }

Выходные параметры	Параметр	Описание	Тип	Обязательность
	server_public_key	Публичный ключ сервера	string	*
	session_id	Идентификатор крипто-сессии. Необходимо передавать в заголовке dc-crypto-session-id всех запросов из раздела "Доступные методы для работы в Dion.Чаты".	string	*
	valid_after	Время начала действия сессии.	string	*
	valid_before	Время окончания действия сессии.	string	*
Пример ответа	{ "session_id": "a654f474-b30f-46d5-9ce1-3c3962cbc072", "server_public_key": "BOyEDT4aiklkGEqlQRkl+MIaOynTHxkFmZEUfXSjtzS9isWGBgLpWX7U2ULXAzlC6F9X4VqzkqetdX1I5nJGkM4=", "valid_after": "2025-09-24T06:02:16.118887Z", "valid_before": "2025-09-24T16:03:16.118888Z" }
Коды состояния HTTP	Список возвращаемых кодов с кратким описанием: 201 Created – сессия создана, 400 Bad Request – неверно заполнены параметры запроса, 401 Unauthorized – недостаточно прав доступа или не указаны учетные данные, 500 Internal Server Error – внутренняя ошибка сервера.

Входные параметры	❗В заголовке Authorization необходимо передавать токен Bearer, полученный в ответ на запрос POST https://bots-api.dion.vc/platform/v1/token. ❗В заголовке dc-crypto-session-id необходимо передавать идентификатор крипто-сессии, полученный методом POST /chats/v1/sessions. ❗В заголовке dc-encoded-data-over-json необходимо передавать значение true.
	Параметр	Описание	Тип	Обязательность
	query-параметры
	cursor	Курсор для указания начальной точки следующих входящих событий бота (брать из ответа next_cursor).	string

Выходные параметры	Параметр	Описание	Тип	Обязательность
	events	Массив последних событий относительно заданного параметра cursor. Размер массива ограничен – максимально 100 событий. События отсортированы по времени создания (от ранних к поздним).	object[]	*
	type	Тип входящего события. Принимает одно из следующих значений: member_added – добавлен пользователь, message_modified – сообщение отредактировано, message_created – написано новое сообщение, message_deleted – сообщение удалено, message_modification_failed – при редактировании сообщения (своего) произошла ошибка, message_creation_failed – при создании сообщения (своего) произошла ошибка, message_deletion_failed – при удалении сообщения (своего) произошла ошибка.	string	*
	event_id	Идентификатор события	string	*
	payload	Полезные данные по событию. Возможное содержимое payload каждого события см. ниже.	object	*
	next_cursor	Курсор для указания в запросе на получение следующих событий. Значение "" (пустая строка) параметра означает, что больше событий для бота нет.	string	*

¶ payload различных событий
payload для type=message_created
№	Параметр	Тип	Обязательность
2.3	members_count	int	*
1	message	object	*
1.2	author	object	*
1.2.4	cover	object	*
1.3	repost_from_author	object
1.9	formatted_content	object	*
2	conversation	object	*
2.4	params	object	*
2.6	parent_conversation	object
2.9	cover	object	*
3	parent_message	object
4	reply_to_message	object
1.4	attachments	object[]	*
2.2	companion	object User
1.1	message_id	string	*
1.5	thread_id	string
1.6	intermediate_id	string	*
1.7	conversation_id	string	*
1.8	message_type	string	*
1.10	created_at	string	*
1.11	updated_at	string	*
2.1	conversation_id	string	*
2.7	name	string	*
2.8	conversation_type	string	*
2.10	created_at	string	*
2.11	updated_at	string	*
5	initiator_id	string	*
2.5	permissions	string[]	*
1.2.1	id		*
1.2.2	name		*
1.2.3	type		*

payload для type=message_modified
№	Параметр	Тип	Обязательность
1	message	object	*
2	conversation	object	*
3	reply_to_message	object
4	initiator_id	string	*

payload для type=message_deleted
№	Параметр	Тип	Обязательность
1	message	object	*
2	conversation	object	*
3	reply_to_message	object
4	initiator_id	string	*

payload для type=member_added
№	Параметр	Описание	Тип	Обязательность
1	conversation	Чат, в который добавили. Структура совпадает со структурой conversation для message_created.	object	*
2	member	Пользователь, которого добавили в чат.	object	*
2.1	user_id	Идентификатор пользователя	string	*
2.2	role	Роль пользователя в чате. Одно из следующих: OWNER – владелец чата, ADMIN – администратор чата, DEFAULT – обычный участник чата.	string	*
2.3	permissions	Список возможных действий (разрешений), которые можно сделать с данным участником.	string[]	*
2.4	email	Адрес почты	string	*
2.5	position	Должность	string	*
2.6	name	Имя	string	*
2.7	cover	Объект аватара	object	*
2.8	status	Статус учетной записи	string	*
2.9	presence	Объект состояния/активности пользователя	object	*
2.10	type	Тип пользователя. Одно из следующих значений: REGULAR – обычный пользователь, BOT – бот, GUEST – гость.	string	*
2.11	description		string	*
3	reason	Причина добавления	object
4	initiator_id	Идентификатор инициатора события	string

payload для type=message_creation_failed
№	Параметр	Описание	Тип	Обязательность
1	conversation_id	Идентификатор чата, в который отправляли сообщение.	string	*
2	formatted_content	Структурированное содержание сообщения. Описание см. ниже.	object
3	attachments_ids	Массив идентификаторов вложений.	string[]
4	intermediate_id	Локальный идентификатор сообщения, сгенерированный на клиенте для дальнейшего маппинга.	string	*
5	reply_to_message_id	Идентификатор сообщения, на которое отвечали.	string
6	error	Объект ошибки	object	*
6.5	code	Внутренний код ошибки	string	*
6.6	message	Сообщение ошибки	string	*

payload для type=message_modification_failed
№	Параметр	Описание	Тип	Обязательность
1	message_id	Идентификатор редактируемого сообщения.	string	*
2	formatted_content	Структурированное содержание сообщения. Описание см. ниже.	object
3	attachments_ids	Массив идентификаторов вложений	string[]	*
4	error	Объект ошибки	object	*
4.1	code	Внутренний код ошибки	string	*
4.2	message	Сообщение ошибки	string

payload для type=message_deletion_failed
№	Параметр	Описание	Тип	Обязательность
1	message_id	Идентификатор редактируемого сообщения	string	*
2	error	Объект ошибки	object	*
2.1	code	Внутренний код ошибки	string	*
2.2	message	Сообщение ошибки	string	*

Пример ответа (до дешифрования)	{ "encrypted":"h8uio7AgDTKrinSGD8XvKCDL/BJEtheQYgCWk4 Tcze6Zpy/xUSnohyJH1wJ1R9LElN7NKY7ZTus7LIU p4xwN9qsQzyR5zhwnnW+fmD/WpgMaxNunKU5Ygj8BGUP0 YDS0pFXZYn+rO2GyGDTEUuowkejDF52Ke0kd/ 22vHFQMLyf+D7jBQajpNe24ZGzpgK9SSJpyC5o9X+ttRC7x TlyqY81QPoW0Miyxr2BjrNYmBOCofnm6WfFrbXBTn1yh+u/ GSkB4abx78Tx1+ELCqrtYGYfKh8Kh3EcrLItWeqHHZQDP5Oo fyGLYT25IjbtstUeGbXeyst/QxdoFAx0ngItIPgtMcwoynODihTO 5WxhMLO8a0R9y25lS73fJ395mjKyV3dek7DZRX2o9wcu1Vg Dwc/JYA1ou6O6VWGxdsfCo42Ubk5vAgF1YltdSvlc=" }
Пример ответа (после дешифрования)	{ "events": [ { "event_id": 1, "type": "member_added", "payload": { "conversation": {}, "user": {}, "reason": "string", "initiator": {}, "date": "string" } }, { "event_id": 2, "type": "message_created", "payload": { "message": {}, "conversation": {}, "parent_message": {}, "reply_to_message": {} } }, { "event_id": 3, "type": "message_modification_failed", "payload": { "conversation_id": "string", "error": {} } } ] }
Особенности работы	Пустой массив в параметре events не означает, что больше для бота событий нет, необходимо ориентироваться на значение параметра next_cursor.
Коды состояния HTTP	200 OK – успешный ответ, 400 Bad Request – неверно заполнены параметры запроса, 401 Unauthorized – недостаточно прав доступа или не указаны учетные данные, 428 Precondition Required – ошибка криптографической сессии, 500 Internal Server Error – внутренняя ошибка сервера.

¶ Авторизация чат-бота

¶ Получение токена доступа

¶ Создание криптографической сессии POST /chats/v1/sessions

¶ Шифрование и дешифрование данных

¶ Активация/изменение бота в Dion.Чаты

¶ Получение обновлений от сервера

¶ Доступные методы для работы в Dion.Чаты

¶ Создание криптографической сессии POST /chats/v1/sessions

¶ Получение обновлений GET /chats/v1/events

¶ payload различных событий

¶ Активация чат-бота в Dion.Чаты / Изменение настроек чат-бота POST /chats/v1/me

¶ Получить информацию о пользователе GET /chats/v1/users/:user_id

¶ Отправить сообщения в чат POST /chats/v1/messages

¶ Получить информацию о сообщении GET /chats/v1/messages/:message_id

¶ Загрузить файл POST /v1/attachments

¶ Удалить сообщение DELETE /chats/v1/messages/:message_id

¶ Скачать файл GET /v1/attachments/:attachment_id

¶ Получить информацию о чате GET /chats/v1/conversations/:conversation_id

¶ Структурированное содержание сообщения (formatted_content)

¶ Блок rich_text

¶ Подблоки для форматирования текста

¶ text

¶ user

¶ broadcast

¶ link

¶ code_block

¶ command

¶ Примеры форматирования

¶ Список permissions по чату

¶ Список permissions по участнику

Поле	Тип	Обязательно в запросе	Обязательно в ответе	Описание
type	string	+	+	Тип блока, всегда text.
text	string	+	+	Текст
fallback	string		+	Поле для отображения значения по умолчанию, содержит ~~значение поля text~~ пустую строку ""
style	object			Объект, содержащий информацию о стиле (принимают булевы значения): жирный – bold, курсив – italic, зачеркнутый – strike, подчеркнутый – underline.

	JSON (содержимое поля messages.formatted_content)	Отображение
Упоминание участника чата со стилем underline	`{` `"type": "rich_text",` `"elements": [` `{` `"type": "text",` `"text": "Привет, ",` `"fallback": "Привет, ",` `"style": {` `"underline": true` `}` `},` `{` `"type": "user",` `"id": "<user_id>",` `"fallback": "Сеньор Помидор"` `},` `{` `"type": "text",` `"text": "!",` `"fallback": "!"` `}` `]` `}`	Привет, Сеньор Помидор!
Гиперссылка (test)	`{` `"type": "rich_text",` `"elements": [` `{` `"type": "text",` `"text": "some link ",` `"fallback": "some link "` `},` `{` `"type": "link",` `"url": "https://jsonformatter.org/",` `"text": "test",` `"fallback": "https://jsonformatter.org/"` `}` `]` `}`	some link test
Обычный текст + стили	`{` `"type": "rich_text",` `"elements": [` `{` `"type": "text",` `"text": "на 1й строке текст без пробелов и он обычный\n",` `"fallback": "на 1й строке текст без пробелов и он обычный\n"` `},` `{` `"type": "text",` `"text": " на 2й строке сначала 2 пробела, строка вся курсивом",` `"style": {` `"italic": true` `},` `"fallback": " на 2й строке сначала 2 пробела, строка вся курсивом"` `},` `{` `"type": "text",` `"text": "\n",` `"fallback": "\n"` `},` `{` `"type": "text",` `"text": " здесь уже 3 пробела и строка жирная",` `"style": {` `"bold": true` `},` `"fallback": " здесь уже 3 пробела и строка жирная"` `},` `{` `"type": "text",` `"text": "\n",` `"fallback": "\n"` `},` `{` `"type": "text",` `"text": " здесь 5 пробелов и строка зачеркнутая",` `"style": {` `"strike": true` `},` `"fallback": " здесь 5 пробелов и строка зачеркнутая"` `},` `{` `"type": "text",` `"text": "\n",` `"fallback": "\n"` `},` `{` `"type": "text",` `"text": " 2 пробела снова и вся строка подчеркнута",` `"style": {` `"underline": true` `},` `"fallback": " 2 пробела снова и вся строка подчеркнута"` `},` `{` `"type": "text",` `"text": "здесь строка в стиле кода",` `"style": {` `"code": true` `},` `"fallback": "здесь строка в стиле кода"` `}` `]` `}`	"на 1й строке текст без пробелов и он обычный на 2й строке сначала 2 пробела, строка вся курсивом здесь уже 3 пробела и строка жирная ~~здесь 5 пробелов и строка зачеркнутая~~ 2 пробела снова и вся строка подчеркнута здесь строка в стиле кода"
Команда "/sayHello" бота BotFather	`{` `"elements": [` `{` `"fallback": "BotFather/sayHello",` `"id": "9ed94dc4-99ee-49b5-a586-050b4fe51f5d",` `"name": "BotFather",` `"command": "/sayHello",` `"type": "command"` `},` `{` `"fallback": " Криш",` `"style": {` `"bold": true,` `"italic": false,` `"strike": false,` `"underline": false` `},` `"text": " Криш",` `"type": "text"` `}` `],` `"type": "rich_text"` `}`	BotFather/sayHello Криш

Функциональность	Permission
Удалить данного участника из чата	member.remove
Дать/забрать роль админа у данного участника	member.role.switch