Objects and Fields of Chatbots 2.0

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Description of the objects returned in the responses of the im.v2 and imbot.v2 methods, as well as in event data and webhook notifications.

Quick navigation: User | Bot | Chat | Message | File | Command

Field types depend on the context:

— in method responses and FETCH events of Event.get, types are preserved as they are
— in webhook events, all scalar values come as strings due to serialization via http_build_query: integer → "123", boolean → "1"/"0", null → ""
— in online events, the fields of the User object idle, lastActivityDate, mobileLastDate, desktopLastDate are always equal to false

User

A user of the system. Returned in the user fields and in the users collections.

Field `Type`	Description
id `integer`	Unique identifier of the user
active `boolean`	Is the user active in the system
name `string`	Full name
firstName `string`	First name
lastName `string`	Last name
workPosition `string`	Job title
color `string`	Avatar placeholder color in HEX format, e.g., `#df532d`
avatar `string`	Avatar URL. Empty string if no avatar is set
gender `string`	Gender: `M` — male, `F` — female
birthday `string`	Date of birth. Empty string if not specified
extranet `boolean`	Is the user an extranet user
bot `boolean`	Is the user a bot
connector `boolean`	Is the user a connector of Open Channels
externalAuthId `string`	Type of external authorization: `default`, `bot`, `email`, `replica`, etc.
status `string`	Status: `online`, `dnd`
idle `string\\|false`	Start time of inactivity in ISO 8601 format, or `false`
lastActivityDate `string\\|false`	Date of last activity in ISO 8601 format, or `false`
mobileLastDate `string\\|false`	Date of last mobile login in ISO 8601 format, or `false`
desktopLastDate `string\\|false`	Date of last desktop login in ISO 8601 format, or `false`
absent `string\\|false`	Date of start of absence in ISO 8601 format, or `false`
departments `integer[]`	Array of department IDs
phones `object\\|false`	Object with phone numbers (`personalPhone`, `workPhone`, etc.) or `false`
type `string`	Type: `employee`, `extranet`, `email`, `collaber`, `bot`
website `string`	Personal website
email `string`	Email

Example of User Object

{
            "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+01:00",
            "absent": false,
            "departments": [1, 5],
            "phones": false,
            "type": "employee",
            "website": "",
            "email": "john@example.com"
        }

Bot

Chatbot. Returned in the bot field of the responses from the methods imbot.v2.Bot.get, imbot.v2.Bot.list, as well as in event data.

It has two formats: brief (public) and extended (for the bot owner only).

Common Fields

Field `Type`	Description
id `integer`	ID of the bot user
code `string`	Unique string code of the bot
type `string`	Type of bot. Description of types — Bot Types
isHidden `boolean`	Is the bot hidden from the contact list
isSupportOpenline `boolean`	Does the bot support working with Open Channels
isReactionsEnabled `boolean`	Are reactions to bot messages enabled
backgroundId `string\\|null`	ID of the bot chat background or `null`
language `string`	Default language of the bot, e.g., `en`, `de`

Additional Fields (for owner only)

Field `Type`	Description
moduleId `string`	ID of the module to which the bot belongs
appId `string`	ID of the application that registered the bot
eventMode `string`	Event delivery mode: `webhook` or `fetch`
countMessage `integer`	Number of processed messages
countCommand `integer`	Number of registered commands
countChat `integer`	Number of chats the bot is in
countUser `integer`	Number of unique users

Example of Bot Object (extended format)

{
            "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. Returned in the chat field of the responses from the methods imbot.v2.Chat.get, imbot.v2.Chat.add, as well as in event data.

Field `Type`	Description
id `integer`	Unique identifier of the chat
dialogId `string`	Identifier of the dialog: `chat5` for group chats, `123` for personal chats
name `string`	Name of the chat
type `string`	Type: `chat`, `open`, `channel`, `openChannel`, `copilot`, `thread`, `generalChannel`
messageType `string`	Internal type: `C` (chat), `O` (open), `P` (private), etc.
owner `integer`	ID of the chat owner
color `string\\|null`	Color of the chat in HEX format
avatar `string`	URL of the chat avatar. Empty string if not set
description `string`	Description of the chat
extranet `boolean`	Does the chat contain extranet users
role `string`	Role of the current user: `owner`, `manager`, `member`, `guest`, `none`
containsCollaber `boolean`	Does the chat contain collaborators
muteList `array`	List of user IDs who have disabled notifications. Absent in events — depends on the specific user
entityType `string`	Type of the object, e.g., `LINES` for Open Channels
entityId `string`	Identifier of the element
entityData1 `string`	Additional data of the object (field 1)
entityData2 `string`	Additional data of the object (field 2)
entityData3 `string`	Additional data of the object (field 3)
entityLink `object`	Data link to an external object
diskFolderId `integer\\|null`	ID of the folder on Drive for chat files
permissions `object`	Access permissions for the current user
parentChatId `integer\\|null`	ID of the parent chat for threads
parentMessageId `integer\\|null`	ID of the parent message for threads
isNew `boolean`	Is the chat newly created
textFieldEnabled `string`	Is the text input field enabled: `Y` or `N`
backgroundId `string\\|null`	ID of the chat background or `null`

Additional Fields (only in method responses)

Fields that are returned in method responses (e.g., imbot.v2.Chat.get), but are not passed in events.

Field `Type`	Description
dateCreate `string\\|null`	Date of chat creation in ISO 8601 format
lastMessageId `integer\\|null`	ID of the last message
lastId `integer\\|null`	ID of the last read message
managerList `array`	Array of chat manager IDs
messageCount `integer`	Number of messages in the chat
userCounter `integer`	Number of participants in the chat
unreadId `integer\\|null`	ID of the first unread message
lastMessageViews `string`	JSON string with data on views of the last message
markedId `integer\\|null`	ID of the marked message
public `object\\|string`	Public access settings

Example of Chat Object

{
            "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+01:00",
            "lastMessageId": 789,
            "managerList": [1, 3],
            "messageCount": 42,
            "userCounter": 5,
            "unreadId": null
        }

Message

Message. Returned in the message field of method responses and event data.

Field `Type`	Description
id `integer`	Unique identifier of the message
chatId `integer`	ID of the chat
authorId `integer`	ID of the author. `0` for system messages
date `string\\|null`	Creation date in ISO 8601 format
text `string`	Text of the message. Maximum length — 20,000 characters. Longer messages are truncated with the suffix `(...)`
isSystem `boolean`	Is the message a system message
uuid `string`	UUID for deduplication
forward `object\\|null`	Information about forwarding: `{id, userId, chatId, date}` or `null`
params `object`	Additional parameters: attach, keyboard, files, etc.
viewedByOthers `boolean`	Has the message been read by other participants

Additional Fields (only in method responses)

Field `Type`	Description
unread `boolean`	Unread for the current user
viewed `boolean`	Viewed by the current user

Example of Message Object

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

File

File attached to a message. Returned in the file field of the response from the method imbot.v2.File.upload.

Field `Type`	Description
id `integer`	ID of the file on Drive
chatId `integer`	ID of the chat
date `string\\|null`	Upload date in ISO 8601 format
type `string`	Content type: `file`, `image`, `video`, `audio`
name `string`	File name with extension
extension `string`	File extension in lowercase
size `integer`	File size in bytes
image `object\\|false`	Preview sizes for images: `{"height": 600, "width": 800}`, or `false`
authorId `integer`	ID of the user who uploaded the file
authorName `string`	Name of the user who uploaded the file
isTranscribable `boolean`	Is transcription of the file possible
isVideoNote `boolean`	Is the file a video note
isVoiceNote `boolean`	Is the file a voice message

Example of File Object

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

Command

Slash command of the bot. Returned in the responses from the methods imbot.v2.Command.register, imbot.v2.Command.update, imbot.v2.Command.list.

Field `Type`	Description
id `integer`	Unique identifier of the command
botId `integer`	ID of the bot that owns the command
command `string`	Command text with leading slash, e.g., `/help`
common `boolean`	Is the command available in all chats (`true`) or only where the bot is present (`false`)
hidden `boolean`	Is the command hidden from the suggestions list
extranetSupport `boolean`	Is the command available for extranet users
title `string`	Title of the command in the portal language. Only in method responses
params `string`	Description of the command parameters in the portal language. Only in method responses
category `string`	Name of the bot that owns the command. Only in method responses
context `string`	Context of the command call. Only in method responses

Example of Command Object

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

Continue Learning

Quick Start

Migration from imbot to imbot.v2

Objects and Fields of Chatbots 2.0

UserUser

Example of User ObjectExample of User Object

BotBot

Common FieldsCommon Fields

Additional Fields (for owner only)Additional Fields (for owner only)

Example of Bot Object (extended format)Example of Bot Object (extended format)

ChatChat

Additional Fields (only in method responses)Additional Fields (only in method responses)

Example of Chat ObjectExample of Chat Object

MessageMessage

Additional Fields (only in method responses)Additional Fields (only in method responses)

Example of Message ObjectExample of Message Object

FileFile

Example of File ObjectExample of File Object

CommandCommand

Example of Command ObjectExample of Command Object

Continue LearningContinue Learning

User

Example of User Object

Bot

Common Fields

Additional Fields (for owner only)

Example of Bot Object (extended format)

Chat

Additional Fields (only in method responses)

Example of Chat Object

Message

Additional Fields (only in method responses)

Example of Message Object

File

Example of File Object

Command

Example of Command Object

Continue Learning