Chat Search: Overview of Methods

The im.search.* method group finds group chats, departments, and employees by a search phrase. The subsection is part of the Chats in Bitrix24 section.

Quick navigation: all methods

User documentation: Chats in Bitrix24: Design and features

What to Search For and With Which MethodWhat to Search For and With Which Method

What You Need to Find	Method	How It Searches
A group chat	im.search.chat.list	By the beginning of words in the chat title and in the names of participants. The separate FIND_LINES parameter searches Open Channel chats
A company department	im.search.department.list	By the beginning of words in the full name of the department, including the names of the parent departments
An employee	im.search.user.list	By the beginning of words in the first name, last name, position, and department
A message inside a chat	im.dialog.messages.search	By the message text within one chat. A method of the Messages subsection
A notification in the history	im.notify.history.search	By the text, type, date, and tag of the notification. A method of the Notifications subsection
A chat in the recent list	im.recent.list	Without a search phrase: the method returns the whole list of recent chats

Limits and Response FormatLimits and Response Format

The rules below apply to the three search methods — im.search.chat.list, im.search.department.list, and im.search.user.list. The search history methods im.search.last.* have neither a search phrase nor pagination.

• the search runs against the beginning of words, not an arbitrary substring: "Proj" finds "Project Chat", while "roject" does not
• im.search.chat.list and im.search.user.list require at least two characters: for a shorter phrase they return the FIND_SHORT error
• im.search.department.list behaves differently: it returns the FIND_SHORT error only if the FIND parameter is not provided at all. An empty or very short phrase switches the filter off, and the method returns the whole list of departments — check the phrase length on your side
• when both FIND and FIND_LINES are provided, im.search.chat.list gives priority to FIND and does not search Open Channels
• the selection is paginated: the offset is set by OFFSET, and the page size by LIMIT. The response contains total, and next if there is a next page
• the response fields are returned in snake_case
• the response shapes differ: im.search.chat.list and im.search.department.list return result as an array, while im.search.user.list returns an object where the key of each element equals the user identifier. For all three, an empty selection comes back as an empty array

Relationship with Other ObjectsRelationship with Other Objects

Chat. The search method returns the id of a chat. Substitute it into DIALOG_ID in the chatXXX format to send a message with the im.message.add method, or into CHAT_ID of the methods of the Chat Participants subsection. The data of the found chat is returned by im.dialog.get.

User. The found id of an employee is suitable for a private dialogue: pass it into DIALOG_ID as a number. The same identifier is accepted by the methods of the Users in Chats subsection and by the USERS parameter of the im.chat.user.add method.

Department. The found id of a department is accepted by the methods of the Departments subsection — they return the managers and employees of the department. The identifier is passed as an array: ID: [107].

Overview of MethodsOverview of Methods

Scope: im
Who can execute the method: any user

Current MethodsCurrent Methods

The methods are recommended for new development.

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

Deprecated MethodsDeprecated Methods

The im.search.last.* methods store the history of a user's search queries. They are deprecated: designed for the previous version of the chat and kept only to support existing integrations. In the current M1 chat version, the methods work, but the results are not displayed in the interface — more about the current version in the article Bitrix24 Chat: new messenger. There is no replacement for them.

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