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

Recent dialogs

GET /v1/chats/recent

Returns the list of the current user's recent dialogs, sorted by the date of the last message. Each item contains brief information about the dialog, the last message, and the unread counter.

Parameters

Parameter Type Required Default Description
skipOpenLines string no — Exclude Open Channels conversations. Accepts true, Y, or y
skipChat string no — Exclude group chats. Accepts true, Y, or y
skipDialog string no — Exclude private dialogs. Accepts true, Y, or y
unreadOnly string no — Only dialogs with unread messages. Accepts true, Y, or y
onlyOpenLines string no — Only Open Channels conversations. Accepts true, Y, or y
onlyCopilot string no — Only chats with the AI assistant. Accepts true, Y, or y
onlyChannel string no — Only channels. Accepts true, Y, or y
lastMessageDate string no — Date of the last message for pagination (ISO 8601)
limit number no — Number of items in the response. Maximum 200
offset number no 0 Offset for pagination

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/recent?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/recent?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Recent dialogs:', data.items)

JavaScript — OAuth application

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

Response fields

Field Type Description
data object Result object
data.items array Array of recent dialogs
data.items[].id string Dialog identifier (chatXXX for a group chat or a numeric ID for a private dialog)
data.items[].chatId number Numeric chat ID
data.items[].type string Dialog type: chat, openlines, copilot, channel
data.items[].title string Dialog title
data.items[].avatar object Dialog avatar
data.items[].avatar.url string Avatar image URL. Empty string if the avatar is not set
data.items[].avatar.color string Avatar color in hexadecimal format, for example #4ba984
data.items[].message object Last message in the dialog
data.items[].message.id number Message ID
data.items[].message.text string Message text
data.items[].message.authorId number Message author ID
data.items[].message.date string Message date (ISO 8601)
data.items[].message.file boolean Whether the message contains a file
data.items[].message.attach boolean Whether the message contains an attachment
data.items[].message.sticker string | null Message sticker or null
data.items[].message.status string Message status (for example, received)
data.items[].lastId number ID of the last read message
data.items[].unread boolean Whether there are unread messages
data.items[].counter number Number of unread messages
data.items[].pinned boolean Dialog is pinned
data.items[].dateUpdate string Date of the last dialog update (ISO 8601)
data.items[].dateLastActivity string Date of the last activity (ISO 8601)
data.items[].chat object Extended chat information
data.items[].chat.id number Numeric chat ID
data.items[].chat.name string System chat name
data.items[].chat.type string Chat type: chat, general, openlines, copilot, channel, mail, crm, and others
data.items[].chat.owner number Chat owner ID
data.items[].chat.userCounter number Number of members
data.items[].chat.role string Role of the current user: OWNER, MANAGER, MEMBER
data.items[].chat.entityType string Type of the linked entity (CRM, TASKS, MAIL, GENERAL, and others)
data.items[].chat.entityId string ID of the linked entity
data.hasMorePages boolean true if there is a next page
data.hasMore boolean Duplicates hasMorePages. Kept for backward compatibility

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chat456",
        "chatId": 456,
        "type": "chat",
        "title": "Development team",
        "avatar": {
          "url": "",
          "color": "#4ba984"
        },
        "message": {
          "id": 1201,
          "text": "Task update is ready",
          "authorId": 1,
          "date": "2026-06-03T16:51:12+00:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 1195,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-03T16:51:12+00:00",
        "dateLastActivity": "2026-06-03T16:51:12+00:00",
        "chat": {
          "id": 456,
          "name": "Development team",
          "type": "chat",
          "owner": 1,
          "userCounter": 5,
          "role": "OWNER",
          "entityType": "",
          "entityId": ""
        }
      },
      {
        "id": "chat123",
        "chatId": 123,
        "type": "crm",
        "title": "Deal chat",
        "avatar": {
          "url": "",
          "color": "#f76187"
        },
        "message": {
          "id": 980,
          "text": "Contract approved",
          "authorId": 7,
          "date": "2026-06-02T14:08:10+00:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 0,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-02T14:08:10+00:00",
        "dateLastActivity": "2026-06-02T14:08:10+00:00",
        "chat": {
          "id": 123,
          "name": "Deal chat",
          "type": "crm",
          "owner": 1,
          "userCounter": 2,
          "role": "MEMBER",
          "entityType": "CRM",
          "entityId": "DEAL|42"
        }
      }
    ],
    "hasMorePages": true,
    "hasMore": true
  }
}

Error response example

403 — no im scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Errors

HTTP Code Description
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
422 BITRIX_ERROR Bitrix24 returned an error (details in message)
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of general API errors — Errors.

Known specifics

  • The skipOpenLines and onlyOpenLines flags are mutually exclusive: enabling both leads to a result in which none of the Open Channels chats make it into the list.
  • The lastMessageDate parameter is used for pagination: pass the dateLastActivity value of the last item of the current page to get the next batch. Also pass offset to avoid duplicate records at the page boundary.
  • The response contains a data.copilot field with the configuration of the Bitrix24 account's AI assistant. The structure is used to display roles in the Bitrix24 interface and is not part of the list of dialogs.

See also