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

Описание объектов, которые возвращаются в ответах методов im.v2 и imbot.v2, а также в данных событий и webhook-уведомлениях.

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

Типы полей зависят от контекста:

— в ответах методов и FETCH-событиях Event.get типы сохраняются как есть
— в webhook-событиях все скалярные значения приходят строками из-за сериализации через http_build_query: integer → "123", boolean → "1"/"0", null → ""
— в событиях онлайн-поля объекта User idle, lastActivityDate, mobileLastDate, desktopLastDate всегда равны false

User

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

Поле `Тип`	Описание
id `integer`	Уникальный идентификатор пользователя
active `boolean`	Активен ли пользователь в системе
name `string`	Полное имя
firstName `string`	Имя
lastName `string`	Фамилия
workPosition `string`	Должность
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`	Статус: `online`, `dnd`
idle `string\\|false`	Время начала бездействия в формате ISO 8601, или `false`
lastActivityDate `string\\|false`	Дата последней активности в формате ISO 8601, или `false`
mobileLastDate `string\\|false`	Дата последнего входа с мобильного в формате ISO 8601, или `false`
desktopLastDate `string\\|false`	Дата последнего входа с десктопа в формате ISO 8601, или `false`
absent `string\\|false`	Дата начала отсутствия в формате ISO 8601, или `false`
departments `integer[]`	Массив ID отделов
phones `object\\|false`	Объект с телефонами (`personalPhone`, `workPhone` и др.) или `false`
type `string`	Тип: `employee`, `extranet`, `email`, `collaber`, `bot`
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": "employee",
            "website": "",
            "email": "john@example.com"
        }

Bot

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

Имеет два формата: краткий (публичный) и расширенный (только для владельца бота).

Общие поля

Поле `Тип`	Описание
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 модуля, которому принадлежит бот
appId `string`	ID приложения, зарегистрировавшего бота
eventMode `string`	Режим доставки событий: `webhook` или `fetch`
countMessage `integer`	Количество обработанных сообщений
countCommand `integer`	Количество зарегистрированных команд
countChat `integer`	Количество чатов, в которых состоит бот
countUser `integer`	Количество уникальных пользователей

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

{
            "id": 456,
            "code": "support_bot",
            "type": "bot",
            "isHidden": false,
            "isSupportOpenline": false,
            "isReactionsEnabled": true,
            "backgroundId": null,
            "language": "en",
            "moduleId": "rest",
            "appId": "custom123abc",
            "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`	Тип: `chat`, `open`, `channel`, `openChannel`, `copilot`, `thread`, `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 пользователей, отключивших уведомления. Отсутствует в событиях — зависит от конкретного пользователя
entityType `string`	Тип объекта, например `LINES` для Открытых линий
entityId `string`	Идентификатор элемента
entityData1 `string`	Дополнительные данные объекта (поле 1)
entityData2 `string`	Дополнительные данные объекта (поле 2)
entityData3 `string`	Дополнительные данные объекта (поле 3)
entityLink `object`	Данные ссылки на внешний объект
diskFolderId `integer\\|null`	ID папки на Диске для файлов чата
permissions `object`	Права доступа для текущего пользователя
parentChatId `integer\\|null`	ID родительского чата для тредов
parentMessageId `integer\\|null`	ID родительского сообщения для тредов
isNew `boolean`	Является ли чат только что созданным
textFieldEnabled `string`	Включено ли поле ввода текста: `Y` или `N`
backgroundId `string\\|null`	ID фона чата или `null`

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

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

Поле `Тип`	Описание
dateCreate `string\\|null`	Дата создания чата в формате ISO 8601
lastMessageId `integer\\|null`	ID последнего сообщения
lastId `integer\\|null`	ID последнего прочитанного сообщения
managerList `array`	Массив ID менеджеров чата
messageCount `integer`	Количество сообщений в чате
userCounter `integer`	Количество участников чата
unreadId `integer\\|null`	ID первого непрочитанного сообщения
lastMessageViews `string`	JSON-строка с данными просмотров последнего сообщения
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": "Y",
            "backgroundId": null,
            "dateCreate": "2025-01-10T09:00:00+03:00",
            "lastMessageId": 789,
            "managerList": [1, 3],
            "messageCount": 42,
            "userCounter": 5,
            "unreadId": null
        }

Message

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

Поле `Тип`	Описание
id `integer`	Уникальный идентификатор сообщения
chatId `integer`	ID чата
authorId `integer`	ID автора. `0` для системных сообщений
date `string\\|null`	Дата создания в формате ISO 8601
text `string`	Текст сообщения. Максимальная длина — 20 000 символов. Более длинные сообщения обрезаются с добавлением суффикса `(...)`
isSystem `boolean`	Является ли сообщение системным
uuid `string`	UUID для дедупликации
forward `object\\|null`	Информация о пересылке: `{id, userId, chatId, date}` или `null`
params `object`	Дополнительные параметры: attach, keyboard, файлы и др.
viewedByOthers `boolean`	Прочитано ли сообщение другими участниками

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

Поле `Тип`	Описание
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": "",
            "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`	Размер файла в байтах
image `object\\|false`	Размеры превью для изображений: `{"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,
            "image": false,
            "authorId": 1,
            "authorName": "John Smith",
            "isTranscribable": false,
            "isVideoNote": false,
            "isVoiceNote": false
        }

Command

Слэш-команда бота. Возвращается в ответах методов imbot.v2.Command.register, imbot.v2.Command.update, imbot.v2.Command.list.

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

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

{
            "id": 78,
            "botId": 456,
            "command": "/help",
            "common": false,
            "hidden": false,
            "extranetSupport": false,
            "title": "Show help",
            "params": "[query]",
            "category": "Support Bot",
            "context": "chat"
        }

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

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

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

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

UserUser

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

BotBot

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

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

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

ChatChat

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

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

MessageMessage

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

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

FileFile

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

CommandCommand

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

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

User

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

Bot

Общие поля

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

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

Chat

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

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

Message

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

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

File

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

Command

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

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