Skip to content

index.md

Latest commit

 

History

History
284 lines (216 loc) · 16.5 KB

index.md

File metadata and controls

284 lines (216 loc) · 16.5 KB
Raw

Chats in Bitrix24: Overview of Methods

{% note tip "" %}

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

{% endnote %}

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 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 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 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 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 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 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.

Widgets

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.

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 {#T}.

Overview of Methods {#all-methods}

Scope: im

Who can execute the method: depending on the method

Main 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 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 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 || |#

Messages

#| || 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 || |#

Notifications

#| || 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 || |#

Search

#| || 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 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 || |#

Departments

#| || 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 || |#

Users

#| || 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 Chat

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

Special 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 || |#

Files

#| || 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 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 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 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 || |#