Get the List of Participants im.dialog.users.list

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

Scope: im

Who can execute the method: a user with access to the chat

The method im.dialog.users.list returns detailed information about the participants in the dialog with pagination support.

Method Parameters

Required parameters are marked with *

Name
type

Description

DIALOG_ID*
string

Identifier of the chat in the format:

  • chatXXX — chat
  • sgXXX — group or project chat
  • XXX — identifier of the personal chat user

The chat identifier can be obtained using the im.chat.get method. The user identifier can be retrieved using the user.get and user.search methods

SKIP_EXTERNAL
string

Exclude system users:

  • Y — exclude
  • N — do not exclude

Default: N

SKIP_EXTERNAL_EXCEPT_TYPES
string

A list of types of system users to keep in the selection, separated by commas.

For example: bot, email

LIMIT
integer

Number of items per page. Default: 50. Maximum value: 200

LAST_ID
integer

Identifier of the last user from the selection LIMIT.

Used for sequential loading of the list

OFFSET
integer

Offset for pagination. Default: 0

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"DIALOG_ID":"chat2935","SKIP_EXTERNAL":"Y","LIMIT":20,"OFFSET":0}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.dialog.users.list
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"DIALOG_ID":"chat2935","SKIP_EXTERNAL":"Y","LIMIT":20,"OFFSET":0,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/im.dialog.users.list
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of each DialogUser returned in result[]
        type DialogUser = {
          id: number
          active: boolean
          name: string
          first_name: string
          last_name: string
          work_position: string | null
          color: string
          avatar: string
          avatar_hr: string
          gender: string
          birthday: string
          extranet: boolean
          network: boolean
          bot: boolean
          connector: boolean
          external_auth_id: string
          status: string
          idle: ISODate | false
          last_activity_date: ISODate
          mobile_last_date: ISODate | false
          desktop_last_date: ISODate | false
          absent: ISODate | false
          departments: number[]
          phones: { work_phone?: string; personal_mobile?: string; personal_phone?: string } | false
          bot_data: object | null
          type: string
          website: string
          email: string
        }
        
        try {
          const response = await $b24.actions.v2.call.make<DialogUser[]>({
            method: 'im.dialog.users.list',
            params: {
              DIALOG_ID: 'chat13',
              SKIP_EXTERNAL: 'Y',
              LIMIT: 20,
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info(`Retrieved ${result.length} dialog users:`, result.map(u => u.name))
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function fetchDialogUsers() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'im.dialog.users.list',
                params: {
                  DIALOG_ID: 'chat13',
                  SKIP_EXTERNAL: 'Y',
                  LIMIT: 20,
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info(`Retrieved ${result.length} dialog users:`, result.map(u => u.name))
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', fetchDialogUsers)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.im.dialog.users.list(
                dialog_id="chat2935",
                skip_external=True,
                limit=20,
                offset=0,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'im.dialog.users.list',
                    [
                        'DIALOG_ID' => 'chat2935',
                        'SKIP_EXTERNAL' => 'Y',
                        'LIMIT' => 20,
                        'OFFSET' => 0
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error retrieving dialog users list: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'im.dialog.users.list',
            {
                DIALOG_ID: 'chat2935',
                SKIP_EXTERNAL: 'Y',
                LIMIT: 20,
                OFFSET: 0
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error());
                }
                else
                {
                    console.log(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'im.dialog.users.list',
            [
                'DIALOG_ID' => 'chat2935',
                'SKIP_EXTERNAL' => 'Y',
                'LIMIT' => 20,
                'OFFSET' => 0
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "im.dialog.users.list", b24.Params{
        	"DIALOG_ID":     "chat2935",
        	"SKIP_EXTERNAL": "Y",
        	"LIMIT":         20,
        	"OFFSET":        0,
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("im.dialog.users.list: %w", err)
        }
        
        var items []struct {
        	ID           b24.ID `json:"id"`
        	Active       bool   `json:"active"`
        	Name         string `json:"name"`
        	FirstName    string `json:"first_name"`
        	LastName     string `json:"last_name"`
        	WorkPosition string `json:"work_position"`
        }
        if err := json.Unmarshal(res.Result, &items); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        for _, it := range items {
        	fmt.Println(it.ID, it.Active)
        }
        
        // Total and Next are filled in by list methods; for a full
        // list traversal, use client.Core().Pages and Scan.
        if res.Total != nil {
        	fmt.Println("total:", *res.Total)
        }
        

Response Handling

HTTP Status: 200

{
            "result": [
                {
                "id": 1269,
                "active": true,
                "name": "Alexander Smith",
                "first_name": "Alexander",
                "last_name": "Smith",
                "work_position": "Sales Department Head",
                "color": "#58cc47",
                "avatar": "https://cdn-com.bitrix24.com/avatars/alexander-smith.png",
                "avatar_hr": "https://cdn-com.bitrix24.com/avatars/alexander-smith@2x.png",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "network": false,
                "bot": false,
                "connector": false,
                "external_auth_id": "socservices",
                "status": "online",
                "idle": false,
                "last_activity_date": "2026-03-02T17:45:59+02:00",
                "mobile_last_date": false,
                "desktop_last_date": false,
                "absent": false,
                "departments": [1],
                "phones": {
                    "personal_mobile": "+19165554419"
                },
                "bot_data": null,
                "type": "user",
                "website": "",
                "email": "a.smith@example.com"
                },
                {
                "id": 99,
                "active": true,
                "name": "Catherine Peterson",
                "first_name": "Catherine",
                "last_name": "Peterson",
                "work_position": "Business Analyst",
                "color": "#58cc47",
                "avatar": "https://cdn-com.bitrix24.com/avatars/catherine-peterson.png",
                "avatar_hr": "https://cdn-com.bitrix24.com/avatars/catherine-peterson@2x.png",
                "gender": "F",
                "birthday": "",
                "extranet": false,
                "network": false,
                "bot": false,
                "connector": false,
                "external_auth_id": "socservices",
                "status": "online",
                "idle": false,
                "last_activity_date": "2026-03-02T17:44:31+02:00",
                "mobile_last_date": false,
                "desktop_last_date": false,
                "absent": false,
                "departments": [121],
                "phones": false,
                "bot_data": null,
                "type": "user",
                "website": "",
                "email": "c.peterson@mail.com"
                },
                {
                "id": 1271,
                "active": true,
                "name": "Dmitry Harris",
                "first_name": "Dmitry",
                "last_name": "Harris",
                "work_position": "Senior Developer",
                "color": "#df532d",
                "avatar": "https://cdn-com.bitrix24.com/avatars/dmitry-harris.png",
                "avatar_hr": "https://cdn-com.bitrix24.com/avatars/dmitry-harris@2x.png",
                "gender": "M",
                "birthday": "",
                "extranet": false,
                "network": false,
                "bot": false,
                "connector": false,
                "external_auth_id": "socservices",
                "status": "online",
                "idle": false,
                "last_activity_date": "2026-03-02T17:45:02+02:00",
                "mobile_last_date": false,
                "desktop_last_date": false,
                "absent": false,
                "departments": [1],
                "phones": false,
                "bot_data": null,
                "type": "user",
                "website": "",
                "email": "d.harris@mail.com"
                }
            ],
            "total": 3,
            "time": {
                "start": 1772477165,
                "finish": 1772477165.266759,
                "duration": 0.26675891876220703,
                "processing": 0,
                "date_start": "2026-03-02T17:46:05+02:00",
                "date_finish": "2026-03-02T17:46:05+02:00",
                "operating_reset_at": 1772477765,
                "operating": 0
            }
        }
        

Returned Data

Name
type

Description

result
array

An array of objects with dialog participant data

total
integer

Total number of participants available to the current user

next
integer

Offset for the next page of results.

Returned if there is a next page

time
time

Information about the request execution time

Result Object

Name
type

Description

id
integer

User identifier

active
boolean

User activity status

name
string

User's full name

first_name
string

User's first name

last_name
string

User's last name

work_position
string

User's position. Can be null

color
string

User's color in HEX format

avatar
string

Link to the avatar. If empty, the avatar is not set

avatar_hr
string

Link to the high-resolution avatar

gender
string

User's gender

birthday
string

Birthday in DD-MM format or an empty string

extranet
boolean

Indicator of an external extranet user

network
boolean

Indicator of a Bitrix24.Network user

bot
boolean

Indicator of a bot

connector
boolean

Indicator of an Open Channels user

external_auth_id
string

External authorization code

status
string

User status

idle
datetime

Date when the user stepped away from the computer. If not set, false

last_activity_date
datetime

Date of the user's last activity

mobile_last_date
datetime

Date of the last activity in the mobile application. If not set, false

desktop_last_date
datetime

Date of the last activity in the desktop application. If not set, false

absent
datetime

Date of the user's absence. If not set, false

departments
array

List of user department identifiers

phones
object

Contact user phones. Can be false

bot_data
object

Bot data. For a regular user, it can be null

type
string

User type

website
string

User's website

email
string

User's email

Phones Object

Name
type

Description

work_phone
string

Work phone

personal_mobile
string

Mobile phone

personal_phone
string

Home phone

Error Handling

HTTP Status: 400, 403

{
            "error": "DIALOG_ID_EMPTY",
            "error_description": "Dialog ID can't be empty"
        }
        

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code

Description

Value

DIALOG_ID_EMPTY

Dialog ID can't be empty

The DIALOG_ID was not provided or is invalid

ACCESS_ERROR

You do not have access to the specified dialog

No access to the specified dialog

ACCESS_ERROR

You don't have access to this chat

No access to the specified chat

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning