Объекты и поля чат-ботов 2.0

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Пользователь, бот, чат, сообщение, файл и команда приходят в ответах методов im.v2 и imbot.v2, в данных событий и в webhook-уведомлениях.

Быстрый переход: User | Bot | Chat | Message | File | Command

Типы полей зависят от того, откуда пришел объект:

ответ метода или событие из Event.get в режиме fetch — типы сохраняются как есть
событие в режиме webhook — все скалярные значения приходят строками: integer → "123", boolean → "1"/"0". Поля со значением null и пустые массивы в данные события не попадают

В событиях онлайн-поля объекта User — idle, lastActivityDate, mobileLastDate, desktopLastDate — всегда равны false.

User

Пользователь системы. Возвращается в полях user и в коллекциях users.

Поле `Тип`	Описание
id `integer`	Уникальный идентификатор пользователя
active `boolean`	Активен ли пользователь в системе
name `string`	Полное имя
firstName `string\|null`	Имя. `null` у автора системных сообщений
lastName `string\|null`	Фамилия. `null` у автора системных сообщений
workPosition `string\|null`	Должность или `null`, если она не указана
color `string`	Цвет аватара-заглушки в формате HEX, например `#df532d`
avatar `string`	URL аватара. Пустая строка, если аватар не установлен
gender `string`	Пол: `M` — мужской, `F` — женский
birthday `string`	Дата рождения. Пустая строка, если не указана
extranet `boolean`	Является ли пользователь экстранет-пользователем
bot `boolean`	Является ли пользователь ботом
connector `boolean`	Является ли пользователь коннектором Открытых линий
externalAuthId `string`	Тип внешней авторизации: `default`, `bot`, `email`, `replica` и другие
status `string`	Статус пользователя. В ответах методов `imbot.v2` и в событиях всегда `online`
idle `string \| boolean`	Время начала бездействия в формате ISO 8601, или `false`
lastActivityDate `string \| boolean`	Дата последней активности в формате ISO 8601, или `false`
mobileLastDate `string \| boolean`	Дата последнего входа с мобильного в формате ISO 8601, или `false`
desktopLastDate `string \| boolean`	Дата последнего входа с десктопа в формате ISO 8601, или `false`
absent `string \| boolean`	Дата и время возвращения из отпуска в формате ISO 8601. Это следующий день после окончания отпуска. `false`, если пользователь не в отпуске. Другие виды отсутствия, например командировка, не учитываются
departments `integer[]`	Массив ID отделов
phones `object \| boolean`	Телефоны пользователя или `false`, если телефонов нет. В объекте только заполненные номера. Возможные ключи: `personal_mobile`, `work_phone`, `inner_phone`, `personal_phone`
type `string`	Тип пользователя, например `user` — сотрудник, `extranet` — внешний пользователь, `bot` — чат-бот
internalAccount `boolean`	Внутренняя учетная запись Битрикс24
intranetUser `boolean`	Пользователь интранета — сотрудник компании
website `string`	Персональный сайт
email `string`	Email

Пример объекта User

В примере показаны не все поля.

{
    "id": 1,
    "active": true,
    "name": "John Smith",
    "firstName": "John",
    "lastName": "Smith",
    "workPosition": "Developer",
    "color": "#df532d",
    "avatar": "",
    "gender": "M",
    "birthday": "",
    "extranet": false,
    "bot": false,
    "connector": false,
    "externalAuthId": "default",
    "status": "online",
    "idle": false,
    "lastActivityDate": "2025-01-15T10:29:00+03:00",
    "absent": false,
    "departments": [1, 5],
    "phones": false,
    "type": "user",
    "website": "",
    "email": "john@example.com"
}

Bot

Чат-бот. Возвращается в поле bot ответа imbot.v2.Bot.get, в массиве bots ответа imbot.v2.Bot.list, а также в данных событий.

Объект приходит в двух форматах: краткий содержит общие поля, расширенный — еще и поля, которые видит только владелец бота. В событиях режима webhook приходит третий формат с полями id, code и auth. Он описан в разделе Формат объекта bot.

Общие поля

Поле `Тип`	Описание
id `integer`	ID пользователя-бота
code `string`	Уникальный строковый код бота
type `string`	Тип бота. Описание типов — Типы ботов
isHidden `boolean`	Скрыт ли бот из списка контактов
isSupportOpenline `boolean`	Поддерживает ли бот работу с Открытыми линиями
isReactionsEnabled `boolean`	Включены ли реакции на сообщения бота
backgroundId `string\|null`	ID фона чата бота или `null`
language `string`	Язык бота по умолчанию, например `en`, `ru`

Дополнительные поля (только для владельца)

Поле `Тип`	Описание
moduleId `string`	ID модуля, которому принадлежит бот
eventMode `string`	Режим доставки событий: `webhook` или `fetch`
countMessage `integer`	Служебный счетчик, см. примечание под таблицей
countCommand `integer`	Служебный счетчик. Не равен числу зарегистрированных команд
countChat `integer`	Служебный счетчик
countUser `integer`	Служебный счетчик

Битрикс24 обновляет счетчики countMessage, countCommand, countChat и countUser не для всех действий и с задержкой. После сообщений и вызова команды значения могут остаться 0. Чтобы считать сообщения, команды или чаты бота, ведите учет на своей стороне по событиям.

Пример объекта Bot (расширенный формат)

{
    "id": 456,
    "code": "support_bot",
    "type": "bot",
    "isHidden": false,
    "isSupportOpenline": false,
    "isReactionsEnabled": true,
    "backgroundId": null,
    "language": "en",
    "moduleId": "rest",
    "eventMode": "fetch",
    "countMessage": 150,
    "countCommand": 3,
    "countChat": 12,
    "countUser": 45
}

Chat

Чат. Возвращается в поле chat ответов методов imbot.v2.Chat.get, imbot.v2.Chat.add, а также в данных событий.

Поле `Тип`	Описание
id `integer`	Уникальный идентификатор чата
dialogId `string`	Идентификатор диалога: `chat5` для групповых, `123` для личных
name `string`	Название чата
type `string`	Тип чата, например `private` — личный, `chat` — групповой, `open`, `channel`, `openChannel`, `copilot`, `generalChannel`
messageType `string`	Внутренний тип: `C` (chat), `O` (open), `P` (private) и другие
owner `integer`	ID владельца чата
color `string\|null`	Цвет чата в формате HEX
avatar `string`	URL аватара чата. Пустая строка, если не установлен
description `string`	Описание чата
extranet `boolean`	Содержит ли чат экстранет-пользователей
role `string`	Роль текущего пользователя: `owner`, `manager`, `member`, `guest`, `none`. Отсутствует в событиях
containsCollaber `boolean`	Содержит ли чат коллаберов
muteList `array`	ID текущего пользователя, если он отключил уведомления чата, иначе пустой массив. ID других участников в список не попадают. Отсутствует в событиях
entityType `string`	Тип объекта, к которому привязан чат, например `LINES` для Открытых линий
entityId `string`	Идентификатор объекта, к которому привязан чат
entityData1 `string`	Дополнительные данные объекта (поле 1)
entityData2 `string`	Дополнительные данные объекта (поле 2)
entityData3 `string`	Дополнительные данные объекта (поле 3)
entityLink `object`	Ссылка на объект, к которому привязан чат: `type` — тип объекта, `url` — адрес объекта, `id` — ID объекта. Если чат не привязан, все три поля — пустые строки
diskFolderId `integer\|null`	ID папки на Диске для файлов чата
permissions `object`	Права в чате. (подробное описание)
parentChatId `integer\|null`	ID родительского чата для тредов
parentMessageId `integer\|null`	ID родительского сообщения для тредов
isNew `boolean`	Является ли чат только что созданным
textFieldEnabled `boolean`	Включено ли поле ввода текста
backgroundId `string\|null`	ID фона чата или `null`
hasManageCapability `boolean`	Служебное поле интерфейса
canHaveThreads `boolean`	Можно ли в чате создавать треды

Объект permissions

Каждый ключ — группа действий в чате. Значение — минимальная роль, которой разрешены эти действия: member — участник, manager — администратор чата, owner — владелец чата, none — действия запрещены всем.

Поле `Тип`	Описание
manageUsersAdd `string`	Добавлять участников
manageUsersDelete `string`	Исключать участников
manageUi `string`	Менять название, описание, цвет и аватар чата
manageSettings `string`	Менять права, владельца и администраторов чата
manageMessages `string`	Писать и закреплять сообщения
manageMessagesAutoDelete `string`	Настраивать автоудаление сообщений
manageGuestInvites `string`	Приглашать гостей
manageDelete `string`	Удалять чат
canPost `string`	Повторяет значение `manageMessages`

Дополнительные поля (только в ответах методов)

Поля, которые возвращаются в ответах методов (например, imbot.v2.Chat.get), но не передаются в событиях.

Поле `Тип`	Описание
dateCreate `string\|null`	Дата создания чата в формате ISO 8601
lastMessageId `integer\|null`	ID последнего сообщения
lastId `integer`	ID последнего прочитанного сообщения. `0`, если прочитанных нет
managerList `array`	Массив ID менеджеров чата
messageCount `integer`	Количество сообщений в чате
userCounter `integer`	Количество участников чата
unreadId `integer`	ID первого непрочитанного сообщения. `0`, если непрочитанных нет
lastMessageViews `object`	Кто посмотрел последнее сообщение чата: `messageId` — ID этого сообщения, `firstViewers` — массив первых зрителей, `countOfViewers` — сколько пользователей его посмотрели
markedId `integer\|null`	ID отмеченного сообщения
public `object\|string`	Настройки публичного доступа

Пример объекта Chat

В примере показаны не все поля.

{
    "id": 5,
    "dialogId": "chat5",
    "name": "Support Chat",
    "type": "chat",
    "messageType": "C",
    "owner": 1,
    "color": "#ab7761",
    "avatar": "",
    "description": "",
    "extranet": false,
    "role": "member",
    "containsCollaber": false,
    "diskFolderId": 42,
    "textFieldEnabled": true,
    "backgroundId": null,
    "dateCreate": "2025-01-10T09:00:00+03:00",
    "lastMessageId": 789,
    "managerList": [1, 3],
    "messageCount": 42,
    "userCounter": 5,
    "unreadId": 0
}

Message

Сообщение. Возвращается в поле message ответов методов и данных событий.

Поле `Тип`	Описание
id `integer`	Уникальный идентификатор сообщения
chatId `integer`	ID чата
authorId `integer`	ID автора. `0` у системных сообщений в чате, например о создании чата или добавлении участника
date `string\|null`	Дата создания в формате ISO 8601
text `string`	Текст сообщения. Текст длиннее 20 006 символов обрезается до 20 000 символов, в конце добавляется `(...)`
isSystem `boolean`	Является ли сообщение системным
uuid `string\|null`	UUID сообщения, если его передали при отправке, или `null`
forward `object\|null`	Данные о пересылке, если сообщение переслано, или `null`. `id` — ID исходного сообщения в формате `<чат>/<сообщение>`, `userId` — ID автора исходного сообщения. Остальные поля описывают исходный чат: `chatTitle`, `chatType`, `parentChatId`, `parentMessageId`, `parentChatType`
params `object\|array`	Дополнительные параметры сообщения: вложения, клавиатура, файлы и другие. Если параметров нет, приходит пустой массив `[]`, а в событиях режима `webhook` поля нет. (подробное описание)
viewedByOthers `boolean`	Прочитано ли сообщение другими участниками

Объект params

В params приходят только ключи, заданные у сообщения. Основные:

Поле `Тип`	Описание
ATTACH `array`	Вложения — карточки со свойствами, ссылками, изображениями: массив объектов с полями `ID`, `BLOCKS`, `DESCRIPTION`, `COLOR`, `COLOR_TOKEN`. Блоки описаны в разделе Вложения
KEYBOARD `array`	Кнопки клавиатуры под сообщением: массив объектов с полями `TEXT`, `LINK`, `BG_COLOR_TOKEN`, `BOT_ID`, `TYPE`, `DISABLED` и другими
FILE_ID `array`	ID файлов сообщения: массив строк
REPLY_ID `string`	ID исходного сообщения строкой, если это сообщение — ответ
LIKE `array`	Массив ID пользователей, которые поставили реакцию «нравится»
IS_EDITED `string`	`Y`, если сообщение редактировали
IS_DELETED `string`	`Y`, если сообщение удалено

Дополнительные поля (только в ответах методов)

Поле `Тип`	Описание
unread `boolean`	Непрочитанное для текущего пользователя
viewed `boolean`	Просмотрено текущим пользователем

Пример объекта Message

В примере показаны не все поля.

{
    "id": 789,
    "chatId": 5,
    "authorId": 1,
    "date": "2025-01-15T10:30:00+03:00",
    "text": "Hello bot!",
    "isSystem": false,
    "uuid": null,
    "forward": null,
    "params": [],
    "viewedByOthers": false
}

File

Файл, прикрепленный к сообщению. Возвращается в поле file ответа метода imbot.v2.File.upload.

Поле `Тип`	Описание
id `integer`	ID файла на Диске
chatId `integer`	ID чата
date `string\|null`	Дата загрузки в формате ISO 8601
type `string`	Тип контента: `file`, `image`, `video`, `audio`
name `string`	Имя файла с расширением
extension `string`	Расширение файла в нижнем регистре
size `integer`	Размер файла в байтах
duration `integer\|null`	Длительность аудио или видео. У остальных файлов — `null`
image `object \| boolean`	Размеры превью для изображений: `{"height": 600, "width": 800}`, или `false`
authorId `integer`	ID пользователя, загрузившего файл
authorName `string`	Имя пользователя, загрузившего файл
isTranscribable `boolean`	Возможна ли транскрибация файла
isVideoNote `boolean`	Является ли файл видеозаметкой
isVoiceNote `boolean`	Является ли файл голосовым сообщением

Пример объекта File

{
    "id": 138,
    "chatId": 5,
    "date": "2025-01-15T10:30:00+03:00",
    "type": "file",
    "name": "report.pdf",
    "extension": "pdf",
    "size": 35341,
    "duration": null,
    "image": false,
    "authorId": 1,
    "authorName": "John Smith",
    "isTranscribable": false,
    "isVideoNote": false,
    "isVoiceNote": false
}

Command

Слэш-команда бота — команда, которую пользователь вызывает в чате через косую черту, например /help. Состав полей зависит от того, где пришел объект: в ответе на регистрацию или изменение команды, в списке команд или в событии вызова команды.

В ответах register и update

Поле command ответа imbot.v2.Command.register и imbot.v2.Command.update.

Поле `Тип`	Описание
id `integer`	ID команды
botId `integer`	ID бота-владельца команды
command `string`	Текст команды с ведущим слэшем, например `/help`
common `boolean`	Доступна ли команда во всех чатах (`true`) или только там, где есть бот (`false`)
hidden `boolean`	Скрыта ли команда из списка подсказок
extranetSupport `boolean`	Доступна ли команда для экстранет-пользователей

Пример объекта:

{
    "id": 78,
    "botId": 456,
    "command": "/help",
    "common": false,
    "hidden": false,
    "extranetSupport": false
}

В ответе list

Элементы массива commands ответа imbot.v2.Command.list. В список входят и встроенные команды Битрикс24, например /me: у них id — строка вида def0, а botId — 0.

Поле `Тип`	Описание
id `integer\|string`	ID команды. У встроенных команд — строка
botId `integer`	ID бота-владельца команды. `0` у встроенных команд
command `string`	Текст команды с ведущим слэшем
category `string`	Имя бота-владельца или раздел встроенных команд
common `string`	Доступна ли команда во всех чатах: `Y` или `N`
context `string`	Контекст команды. У команд, зарегистрированных через REST, — пустая строка
title `string`	Заголовок команды на языке Битрикс24
params `string`	Описание параметров команды на языке Битрикс24
extranet `string`	Доступна ли команда для экстранет-пользователей: `Y` или `N`

Пример элемента массива:

{
    "id": 78,
    "botId": 456,
    "command": "/help",
    "category": "Support Bot",
    "common": "N",
    "context": "",
    "title": "Показать помощь",
    "params": "запрос",
    "extranet": "N"
}

В событии вызова команды

В событии ONIMBOTV2COMMANDADD объект command содержит поля id, command, params и context. В params — аргументы, которые пользователь передал при вызове, в context — способ вызова. Поля описаны в разделе Объект command.

Продолжите изучение

Была ли статья полезна?

Быстрый старт

Миграция с imbot на imbot.v2

Объекты и поля чат-ботов 2.0

UserUser

Пример объекта UserПример объекта User

BotBot

Общие поляОбщие поля

Дополнительные поля (только для владельца)Дополнительные поля (только для владельца)

Пример объекта Bot (расширенный формат)Пример объекта Bot (расширенный формат)

ChatChat

Объект permissionsОбъект permissions

Дополнительные поля (только в ответах методов)Дополнительные поля (только в ответах методов)

Пример объекта ChatПример объекта Chat

MessageMessage

Объект paramsОбъект params

Дополнительные поля (только в ответах методов)Дополнительные поля (только в ответах методов)

Пример объекта MessageПример объекта Message

FileFile

Пример объекта FileПример объекта File

CommandCommand

В ответах register и updateВ ответах register и update

В ответе listВ ответе list

В событии вызова командыВ событии вызова команды

Продолжите изучениеПродолжите изучение

Была ли статья полезна?

User

Пример объекта User

Bot

Общие поля

Дополнительные поля (только для владельца)

Пример объекта Bot (расширенный формат)

Chat

Объект permissions

Дополнительные поля (только в ответах методов)

Пример объекта Chat

Message

Объект params

Дополнительные поля (только в ответах методов)

Пример объекта Message

File

Пример объекта File

Command

В ответах register и update

В ответе list

В событии вызова команды

Продолжите изучение