Chats in Bitrix24: Overview of Methods

A chat in Bitrix24 helps you:

• communicate one-on-one
• discuss tasks in a group
• work with notifications, files, and messages within a single messenger interface

Chats are managed by the im.* methods. Individual scenarios — participants, messages, notifications, search, files, and special operations — are placed in subsections.

Quick navigation: all methods

User documentation: Chats in Bitrix24: Interface and Capabilities

How to Choose a SubsectionHow to Choose a Subsection

If You Need To	Open the Subsection
Change the title, color, avatar, or owner of a chat	Chat Update
Add, retrieve, or remove participants	Chat Participants
Send, modify, and read messages	Messages
Format a message, build an attachment, a keyboard, or a context menu	Formatting, Attachments, Keyboards, Context Menu
Send notifications and manage their read status	Notifications
Upload and download chat files	Files
Search chats, employees, and departments	Search
Retrieve user data and manage the status	Users
Retrieve the composition of company departments	Departments
Pin, hide, and mute chats	Special Operations
Understand the mechanisms of the previous generation of chat applications	Deprecated

Chat IdentifiersChat Identifiers

A group chat and a private dialog differ by the DIALOG_ID identifier:

Format	What It Means	Example
XXX	A private dialog, where XXX is the user identifier	47
chatXXX	A group chat, where XXX is the chat identifier	chat2935
sgXXX	A workgroup or project chat, where XXX is the group identifier	sg17

Some methods accept not DIALOG_ID but a numeric CHAT_ID — the same value without the chat prefix.

Chats linked to CRM, tasks, the calendar, and Open Channels are found by the ENTITY_TYPE and ENTITY_ID pair with the im.chat.get method.

Authorization and LimitsAuthorization and Limits

• the im.* and im.v2.* methods work in the im scope. The exception is the imbot.app.* methods from the Deprecated subsection — they require the imbot scope
• the notification sending methods im.notify, im.notify.personal.add, and im.notify.system.add cannot be called with session authorization — call them via a webhook or with an application token
• when calling via a webhook, the TAG and SUB_TAG tags are passed together with CLIENT_ID
• the size of the serialized ATTACH attachment is limited to 60,000 characters
• in the search methods, the search phrase must be at least two characters, and LIMIT is 50 at most
• the chat avatar is passed as a Base64 string, and the maximum image size is 5000×5000 pixels
• the content of a file uploaded to a chat is passed as a Base64 string, with a maximum size of 100 MB

How to Get StartedHow to Get Started

1. Create a chat with the im.chat.add method or obtain an existing identifier through im.chat.get
2. Retrieve the basic dialog data with the im.dialog.get method and, if necessary, the list of recent chats through im.recent.list
3. Add participants to the chat with the im.chat.user.add method
4. Configure the chat if needed: change the title, color, avatar, or owner with the methods of the Chat Update subsection
5. Send a message through im.message.add or a notification through im.notify

Interaction with Other ObjectsInteraction with Other Objects

User. Most methods operate on behalf of the current user or use the identifiers USER_ID, USERS. You can obtain a user identifier with the user.get method. You can work with users using the methods of the Users subsection.

Company departments. The methods for searching and working with departments use the department identifier ID. You can obtain a department identifier with the get department list method or the search departments by name method.

Files. A chat file is stored on Drive and linked to a message. How to upload and download a file is described in the Files subsection.

CRM, tasks, and the calendar. A chat can be linked to an external object. The link is set by the ENTITY_TYPE and ENTITY_ID pair when creating the chat with the im.chat.add method, and you can find the linked chat by this pair with the im.chat.get method.

Chatbots. The same operations on behalf of a bot are performed by the methods of the Chatbots section.

Current API VersionCurrent API Version

For new integrations, use the im.* methods from this section and the im.v2 methods wherever the scenario has already been migrated to the new generation of the API.

What is replaced by what:

Deprecated Path	Current Replacement
im.disk.folder.get + upload through Drive methods + im.disk.file.commit	im.v2.File.upload — a single call instead of a chain
im.disk.file.save, im.disk.file.delete	There is no replacement yet, use these methods
im.search.last.add, im.search.last.get, im.search.last.delete	There is no replacement: the methods work, but the result is not displayed in the M1 chat interface
im.user.status.idle.start, im.user.status.idle.end	There is no replacement: the methods work, but the result is not displayed in the M1 chat interface
The previous generation of chat applications — the Deprecated subsection	Chatbots and messenger widgets

The user events of the messenger are collected in the im.v2: Events section.

The remaining im.* methods from this section are current and have no deprecated variants.

WidgetsWidgets

You can embed an application into the chat interface. An embedding adds an action next to the input field, an item in the chat sidebar, an action in the context menu of a message, or your own section in the messenger navigation menu.

• Item in the panel above the input field IM_TEXTAREA
• Item in the chat sidebar IM_SIDEBAR
• Item in the context menu of a message IM_CONTEXT_MENU
• Item in the messenger navigation menu IM_NAVIGATION

To register an embedding point, use the method placement.bind and pass the required code in the PLACEMENT parameter. All placements of the section, with the setup order and the call context, are collected in the overview Widgets in Messenger: Overview of Embedding Points.

Overview of MethodsOverview of Methods

Scope: im

Who can execute the method: depending on the method

Main Chat MethodsMain Chat Methods

Method	Description
im.chat.add	Creates a chat
im.chat.get	Retrieves the chat identifier
im.dialog.get	Retrieves chat data
im.recent.get	Retrieves a shortened list of recent chats
im.recent.list	Retrieves a list of chats
im.counters.get	Retrieves message and notification counters
im.revision.get	Retrieves API revisions for the IM module

Chat UpdateChat Update

Method	Description
im.chat.setOwner	Changes the chat owner
im.chat.updateTitle	Changes the chat title
im.chat.updateAvatar	Changes the chat avatar
im.chat.updateColor	Changes the chat color

Chat ParticipantsChat Participants

Method	Description
im.chat.user.add	Adds participants to the chat
im.chat.user.list	Retrieves participant identifiers of the chat
im.dialog.users.list	Retrieves the list of participants
im.chat.user.delete	Removes participants from the chat
im.chat.leave	Allows the current user to leave the chat

MessagesMessages

Method	Description
im.message.add	Adds a message
im.message.update	Modifies a sent message
im.message.delete	Deletes a message
im.message.like	Changes the "like" status of a message
im.message.share	Creates a chat, task, post, or calendar event based on a message
im.message.command	Executes a chatbot command
im.dialog.messages.get	Retrieves the list of recent messages
im.dialog.messages.search	Searches for messages in the chat
im.dialog.read	Marks messages as "read"
im.dialog.unread	Marks messages as "unread"
im.dialog.writing	Sends the "User is typing" status

NotificationsNotifications

Method	Description
im.notify	Sends a notification
im.notify.personal.add	Sends a personal notification
im.notify.system.add	Sends a system notification
im.notify.get	Returns user notifications
im.notify.schema.get	Returns the schema of notification types
im.notify.read.list	Marks a list of notifications as read
im.notify.read	Marks a notification as read or returns it to unread
im.notify.read.all	Marks all notifications as read
im.notify.answer	Replies to a notification with a quick response
im.notify.confirm	Interacts with notification buttons
im.notify.delete	Deletes notifications
im.notify.history.search	Searches through notification history

SearchSearch

Method	Description
im.search.chat.list	Searches chats by name
im.search.department.list	Searches departments
im.search.user.list	Searches users

Methods of the Previous Version of the ChatMethods of the Previous Version of the Chat

Method	Description
im.search.last.add	Adds search to history
im.search.last.get	Retrieves search history
im.search.last.delete	Deletes search from history

DepartmentsDepartments

Method	Description
im.department.get	Retrieves information about a department
im.department.managers.get	Retrieves a list of department managers
im.department.employees.get	Retrieves a list of department employees
im.department.colleagues.list	Retrieves a list of colleagues of the current user

UsersUsers

Method	Description
im.user.get	Retrieves user data
im.user.list.get	Retrieves data about a list of users
im.user.status.set	Sets the user's status in the chat
im.user.status.get	Retrieves the user's set status

Methods of the Previous Version of the ChatMethods of the Previous Version of the Chat

Method	Description
im.user.status.idle.start	Sets the automatic status "Away"
im.user.status.idle.end	Disables the automatic status "Away"

Special OperationsSpecial Operations

Method	Description
im.recent.pin	Pins the chat at the top of the list
im.recent.unread	Sets or removes the "unread" label on the chat
im.dialog.read.all	Marks all chats of the user as "read"
im.chat.mute	Disables notifications from the chat
im.recent.hide	Removes the chat from the recent list

FilesFiles

Method	Description
im.v2.File.upload	Uploads a file to the chat
im.v2.File.download	Returns a link to download the file
im.disk.file.save	Saves a file to your Drive
im.disk.file.delete	Deletes a file from the chat folder

Methods of the Previous Generation of the APIMethods of the Previous Generation of the API

Method	Description
im.disk.file.commit	Adds a file to the chat. Replaced by the im.v2.File.upload method
im.disk.folder.get	Retrieves the folder for storing chat files. The folder is no longer needed to upload a file

Previous Generation of Chat ApplicationsPrevious Generation of Chat Applications

The methods work in the imbot scope and are kept only to support existing integrations. For new development, use chatbots and messenger widgets.

Method	Description
imbot.app.register	Registers a chat application
imbot.app.update	Updates the data of a chat application
imbot.app.unregister	Deletes a chat application

Working with Messenger EventsWorking with Messenger Events

Method	Description
im.v2.Event.subscribe	Subscribes the current user to event logging
im.v2.Event.get	Returns accumulated events
im.v2.Event.unsubscribe	Stops event logging