Chats in Bitrix24: Overview of Methods

The chat feature in Bitrix24 helps to:

• communicate one-on-one
• discuss tasks in groups
• manage notifications, files, and messages within a single messenger interface

To work with chats, use the methods im.*. This section includes methods for managing chats and subsections for specific scenarios: participants, messages, notifications, search, files, and special operations.

For new developments, keep in mind that some scenarios have already been migrated to im.v2. This is particularly important for working with files and messenger events.

Quick navigation: all methods and events

User documentation: Chats in Bitrix24: interface and capabilities

Main Components of ChatMain Components of Chat

A chat in Bitrix24 can be viewed as an object composed of several blocks:

• dialog type and identifiers
• chat settings and design
• participants and roles
• messages and history
• files
• notifications and special actions

Dialog Type and IdentifiersDialog Type and Identifiers

Group chats and personal dialogs differ by the identifier DIALOG_ID:

• XXX — personal chat with a user, where XXX is the user identifier
• chatXXX — group chat
• sgXXX — chat for a group or project

Group chats are created using the method im.chat.add. In the TYPE parameter, you can choose:

• CHAT — closed chat
• OPEN — open chat

If you need to find an existing chat associated with an external object, use im.chat.get. For chats linked to CRM, tasks, calendars, open channels, and other objects, use the parameters ENTITY_TYPE and ENTITY_ID.

Chat Settings and DesignChat Settings and Design

When creating a chat, you can specify the name, description, color, avatar, and initial message through im.chat.add.

If you do not provide a TITLE when creating the chat, the system will generate a name automatically. In working scenarios, assign a clear name and, if necessary, link the chat to an external object.

After creating the chat, you can modify its design and owner using methods from the Chat Update section.

Participants and RolesParticipants and Roles

The chat owner is automatically assigned upon chat creation. The user who invoked im.chat.add is added to the chat as the owner.

The owner identifier, the role of the current user, the list of managers, and action restrictions in the chat are returned by the methods im.dialog.get, im.recent.get, and im.recent.list.

To work with participants, use the methods from the Chat Participants section:

• im.chat.user.add — add participants
• im.chat.user.delete — remove participants
• im.chat.user.list — get participant identifiers
• im.dialog.users.list — get detailed participant list

You can transfer ownership to another participant using the method im.chat.setOwner.

Messages and HistoryMessages and History

The primary workflow for messaging begins with methods from the Messages section.

To send messages, use im.message.add, to read history — im.dialog.messages.get, and to search through history — im.dialog.messages.search.

The read status and service actions for messaging are managed by the methods im.dialog.read, im.dialog.unread, and im.dialog.writing.

FilesFiles

You can send files in the chat. To work with files in new integrations, use the methods from the im.v2 section of Files.

Use the methods from the group im.disk.* only for existing integrations with the old scenario.

Notifications and Special ActionsNotifications and Special Actions

A notification in the messenger is a message containing information from the system or a user. Notifications are handled by the group of methods im.notify.*.

Methods for service actions with chats and recent dialog lists can be found in the Special Operations section. You can pin a chat, mark it as read, and hide it from the recent list.

How to Get StartedHow to Get Started

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

Interaction with Other ObjectsInteraction with Other Objects

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

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

Files. Old file upload scenarios use methods im.disk.*, while new scenarios have been moved to im.v2. Details are collected in the Files section.

Current API VersionCurrent API Version

For new integrations, use the current sections im.* and new methods im.v2, if the scenario has already been migrated to the new generation of the API.

• For files, use im.v2.File.upload and im.v2.File.download.
• For user events in the messenger, use the section im.v2: events.
• Methods from the sections Files, Search, and Users contain notes about scenarios from the previous version of the chat, which operate with limitations in the M1 interface.

WidgetsWidgets

You can embed an application into the chat interface. By embedding, you can add an action next to the input field, a separate item in the chat sidebar, or an action in the context menu of a message.

• 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

To register an embedding point, use the method placement.bind and pass the required code in the PLACEMENT parameter.

Overview of Methods and EventsOverview of Methods and Events

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.updateAvatar	Changes the chat avatar
im.chat.updateColor	Changes the chat color
im.chat.updateTitle	Changes the chat title

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 an object based on a message
im.message.command	Executes a chat-bot 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	Responds to a notification with a quick reply
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
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
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 "read" status for 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.commit	Adds a file to the chat
im.disk.file.save	Saves a file to your drive
im.disk.file.delete	Deletes a file from the chat folder
im.disk.folder.get	Retrieves the folder for storing chat files

New API EventsNew API 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