Chat Participants: Overview of Methods

Group chats facilitate communication among multiple users simultaneously. The composition of participants is managed by the im.chat.user.* method group, joined by im.dialog.users.list and im.chat.leave. The subsection is part of the Chats in Bitrix24 section.

The methods of this subsection are current and have no deprecated counterparts. If the same operations have to be performed on behalf of a chatbot, use the imbot.v2.Chat.User.* methods from the Chats imbot.v2 subsection.

Quick navigation: all methods

User documentation: Chats in Bitrix24: Interface and Capabilities

How to Get StartedHow to Get Started

1. Retrieve the chat identifier CHAT_ID with the im.chat.add or im.chat.get method
2. Retrieve the user identifiers with the user.get method
3. Add the participants with the im.chat.user.add method and decide whether to show them the conversation history
4. Check the chat composition with the im.chat.user.list or im.dialog.users.list method
5. If necessary, remove a participant with the im.chat.user.delete method or leave the chat with the im.chat.leave method

Linking Chat Participants to Other ObjectsLinking Chat Participants to Other Objects

User. To add participants to a chat, pass a list of their identifiers in the USERS parameter. To exclude a participant, specify their identifier in the USER_ID parameter. You can obtain a user's identifier using the user.get method.

Chat. Users are linked to the chat by the chat identifier CHAT_ID. You can obtain the chat identifier through the create chat method or the get chat identifier method. The im.chat.user.* methods and im.chat.leave accept a numeric CHAT_ID, whereas im.dialog.users.list works with DIALOG_ID: chatXXX — a group chat, sgXXX — a group or project chat, XXX — the user identifier for a private chat.

Chat owner. The owner appears automatically when the chat is created. The role can be passed to another participant with the im.chat.setOwner method from the Chat Update subsection.

User data. The methods of this subsection return identifiers and participant cards in the messenger format. The full employee profile is returned by the methods of the Users section, and the messenger data — by the methods of the Users in Chats subsection. You can find an employee by name with the im.search.user.list method.

How to Choose a MethodHow to Choose a Method

If You Need To	Method
Add users to a chat	im.chat.user.add
Retrieve only the participant identifiers	im.chat.user.list
Retrieve participant cards with names and statuses, with pagination	im.dialog.users.list
Remove a participant from a chat	im.chat.user.delete
Leave a chat on behalf of the current user	im.chat.leave

Overview of MethodsOverview of Methods

Scope: im

Who can execute the method: depends on the method

All the methods of this subsection are available to a chat participant. Participants can be added and removed by a participant with the corresponding permission in the chat, and im.dialog.users.list — by any user with access to the chat. If the permission is missing, the method returns the ACCESS_DENIED_EXTEND or ACCESS_ERROR error.

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