For AI agents: markdown of this page — /docs-content-en/chats/messages/viewers.md documentation index — /llms.txt

Who viewed a message

GET /v1/chats/messages/:messageId/viewers

Returns the views of a message — who saw it and when. The chat is determined from the message, so no dialogId is needed.

Parameters

Parameter Type Required Default Description
ParametermessageId (path) Typenumber Requiredyes Default— DescriptionMessage ID, a positive integer — from the chat feed (GET /v1/chats/:dialogId/messages) or from the send response
ParameterlastId (query) Typenumber Requiredno Default— DescriptionCursor: the id of the last view on the previous page. The bound is exclusive
Parameterorder (query) Typestring Requiredno Defaultdesc Descriptiondesc — from newest views to oldest, asc — from oldest to newest
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionViews per page. From 1 to 200: an out-of-range value is clamped; the passed and applied values are in meta.requestedLimit and meta.appliedLimit
ParameterincludeViewedCount (query) Typestring Requiredno Default— DescriptionY requests the total message view count in the optional viewedCount field, independently of page size. N does not request it. Omitting the parameter preserves the existing response

Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/messages/1002/viewers?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/messages/1002/viewers?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1002/viewers?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Viewed by:', data.views.map((v) => v.userId))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1002/viewers?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Viewed by:', data.views.map((v) => v.userId))

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.views Typearray DescriptionViews on the current page
Fielddata.views[].id Typenumber DescriptionView ID — the lastId cursor for the next page
Fielddata.views[].messageId Typenumber DescriptionMessage ID
Fielddata.views[].userId Typenumber DescriptionID of the user who viewed the message
Fielddata.views[].dateView Typestring DescriptionView time (ISO 8601)
Fielddata.users Typearray DescriptionProfiles of the users in views
Fielddata.hasNextPage Typeboolean Descriptionfalse — no more views in the chosen direction
Fielddata.viewedCount Typenumber DescriptionTotal message view count. Optional when includeViewedCount=Y, if Bitrix24 supplies the count
Fieldmeta.requestedLimit Typenumber DescriptionThe passed limit value, present when it falls outside the range from 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe applied limit value — only when it was clamped to a bound

Response example

JSON 
{
  "success": true,
  "data": {
    "views": [
      {
        "id": 9001,
        "messageId": 1002,
        "userId": 5,
        "dateView": "2026-09-20T10:05:00+00:00"
      }
    ],
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "John Smith",
        "firstName": "John",
        "lastName": "Smith",
        "type": "user"
      }
    ],
    "hasNextPage": false
  }
}

Error response example

422 — the message does not exist in the Bitrix24 account:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "MESSAGE_NOT_FOUND",
    "b24Code": "MESSAGE_NOT_FOUND"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionmessageId is not a positive integer, or the request has a parameter outside the allowed set (lastId, order, limit, includeViewedCount), a repeated parameter or an invalid value. includeViewedCount accepts only Y and N. Checked before any call to Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned the NOT_FOUND code. The Bitrix24 code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The Bitrix24 code is in error.b24Code. A missing message lands here too: MESSAGE_NOT_FOUND
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user has no access to the message's chat — Bitrix24 refused with the ACCESS_DENIED code
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA READONLY key is refused before the Bitrix24 call because this operation may add the caller to the chat
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

The call may make you a member. Like message context, it may conditionally add the caller to the chat. For this reason, READONLY keys receive 403 WRITE_BLOCKED_READONLY_KEY before Bitrix24 is called. The call itself does not mark the message as read. The user's Bitrix24 permissions and the im scope requirement still apply.

See also