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 — using the v2 messenger method im.v2.Chat.Message.tailViewers. The chat is determined from the message, so no dialogId is needed. Views come in pages, from newest to oldest by default.

Parameters

Parameter Type Required Default Description
messageId (path) number yes — Message ID, a positive integer — from the chat feed (GET /v1/chats/:dialogId/messages) or from the response of sending
lastId (query) number no — Cursor: the id of the last view on the previous page. The bound is exclusive
order (query) string no desc desc — from newest views to oldest, asc — from oldest to newest
limit (query) number no 50 Views per page. From 1 to 200: an out-of-range value is clamped and echoed in meta.requestedLimit and meta.appliedLimit

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
success boolean Always true on success
data.views array Views on the page
data.views[].id number View ID — the lastId cursor for the next page
data.views[].messageId number Message ID
data.views[].userId number ID of the user who viewed the message
data.views[].dateView string View time (ISO 8601)
data.users array Profiles of the users in views
data.hasNextPage boolean false — no more views in the chosen direction
meta.requestedLimit number The passed limit value, present when it falls outside the range from 1 to 200
meta.appliedLimit number The applied limit value

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
400 INVALID_PARAMS messageId is not a positive integer, or the request has a parameter outside the allowed set (lastId, order, limit), a repeated parameter or an invalid value. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 returned the NOT_FOUND code; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. A missing message lands here too: MESSAGE_NOT_FOUND
403 BITRIX_ACCESS_DENIED The user has no access to the chat of the message — Bitrix24 refused with the ACCESS_DENIED code
403 WRITE_BLOCKED_READONLY_KEY A READONLY or PORTAL_READONLY key is refused before the Bitrix24 call because this operation may add the caller to the chat
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The 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. Because the call may add the caller to the chat, READONLY and PORTAL_READONLY keys receive 403 WRITE_BLOCKED_READONLY_KEY before Bitrix24 is called. The operation does not mark the message read. The user's Bitrix24 access and the im scope still apply.

Paging. The next page is the same request with lastId equal to the id of the last view in data.views, as long as data.hasNextPage is true.

See also