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

Chat changes since a moment

GET /v1/chats/sync

Returns what changed in the current user's chats since the given moment: new and removed chats, new, edited and deleted messages, pins. Use it to bring a local copy of the chats up to date after a break without re-reading the whole list.

Parameters

Parameter Type Required Default Description
ParameterlastDate (query) Typestring Requiredyes Default— DescriptionThe moment to read changes from. Format YYYY-MM-DDTHH:MM:SS with an offset or Z, without fractional seconds. For the next page, navigationData.lastServerDate of the previous one
ParameterlastId (query) Typeinteger Requiredno Default— DescriptionnavigationData.lastId of the previous page, 0 or more. Not passed on the first page
Parameterlimit (query) Typeinteger Requiredno Default50 DescriptionChange log entries per page, 1 to 200. A smaller value is raised to 1 and a larger one is clamped to 200, both echoed in meta

Other parameters and repeated parameters are rejected with 400 INVALID_PARAMS.

Pagination. Request the first page with lastDate set to the moment up to which your local copy is current. While navigationData.hasMore is true, request the next one with lastDate equal to navigationData.lastServerDate and lastId equal to navigationData.lastId. Save the lastServerDate and lastId pair of the last page: the next sync starts from it.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/sync?lastDate=2026-09-24T10:00:00Z&limit=200" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/sync?lastDate=2026-09-24T10:00:00Z&limit=200" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
let lastDate = '2026-09-24T10:00:00Z'
let lastId
const added = new Set()
for (;;) {
  const url = new URL('https://vibecode.bitrix24.com/v1/chats/sync')
  url.searchParams.set('lastDate', lastDate)
  url.searchParams.set('limit', '200')
  if (lastId !== undefined) url.searchParams.set('lastId', String(lastId))
  const res = await fetch(url, { headers: { 'X-Api-Key': 'YOUR_API_KEY' } })
  const { data } = await res.json()
  if (Array.isArray(data)) throw new Error('Incremental sync is unavailable; refresh the full recent-chat list')
  for (const id of Object.values(data.messageSync.addedMessages)) added.add(id)
  lastDate = data.navigationData.lastServerDate
  lastId = data.navigationData.lastId
  if (!data.navigationData.hasMore) break
}

JavaScript — OAuth application

javascript 
let lastDate = '2026-09-24T10:00:00Z'
let lastId
const added = new Set()
for (;;) {
  const url = new URL('https://vibecode.bitrix24.com/v1/chats/sync')
  url.searchParams.set('lastDate', lastDate)
  url.searchParams.set('limit', '200')
  if (lastId !== undefined) url.searchParams.set('lastId', String(lastId))
  const res = await fetch(url, {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  })
  const { data } = await res.json()
  if (Array.isArray(data)) throw new Error('Incremental sync is unavailable; refresh the full recent-chat list')
  for (const id of Object.values(data.messageSync.addedMessages)) added.add(id)
  lastDate = data.navigationData.lastServerDate
  lastId = data.navigationData.lastId
  if (!data.navigationData.hasMore) break
}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.chatSync.addedRecent Typeobject DescriptionChats that appeared in the dialog list: key and value are the chat ID
Fielddata.chatSync.addedChats Typeobject DescriptionChats that appeared or changed for the user: key and value are the chat ID
Fielddata.chatSync.deletedChats Typeobject DescriptionChats removed from the user's dialog list: key and value are the chat ID
Fielddata.chatSync.completeDeletedChats Typeobject DescriptionChats deleted from the Bitrix24 account: key and value are the chat ID
Fielddata.chatSync.readAllChats Typeboolean DescriptionArrives as true if the user read all chats during this period: reset the unread counters in the local copy
Fielddata.messageSync.addedMessages Typeobject DescriptionNew messages: key and value are the message ID
Fielddata.messageSync.updatedMessages Typeobject DescriptionEdited messages: key and value are the message ID
Fielddata.messageSync.completeDeletedMessages Typeobject DescriptionDeleted messages: key and value are the message ID
Fielddata.pinSync.addedPins Typeobject DescriptionNew pinned messages: key and value are the pin ID
Fielddata.pinSync.deletedPins Typeobject DescriptionRemoved message pins: key and value are the pin ID
Fielddata.userSync Typeobject DescriptionUser changes: updatedUsers and deletedUsers
Fielddata.chats Typearray DescriptionChat cards for the chats from chatSync
Fielddata.messages Typearray DescriptionMessages from messageSync
Fielddata.pins Typearray DescriptionMessage pins from pinSync: id, messageId, chatId, authorId, dateCreate
Fielddata.recentItems Typearray DescriptionDialog list rows for the chats from chatSync
Fielddata.users Typearray DescriptionUsers mentioned in the changes
Fielddata.dialogIds Typeobject DescriptionMapping of chat ID to dialog ID: key is the chat ID, value is the dialogId
Fielddata.navigationData.lastServerDate Typestring DescriptionlastDate for the next page: the moment of the last change log entry on this page
Fielddata.navigationData.lastId Typenumber DescriptionlastId for the next page
Fielddata.navigationData.hasMore Typeboolean Descriptiontrue if there is a next page
Fieldmeta.requestedLimit Typenumber DescriptionThe limit passed. It arrives together with appliedLimit, only when the value was outside the range of 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe applied limit, only when it was clamped to a bound

Response example

The main fields are shown:

JSON 
{
  "success": true,
  "data": {
    "chatSync": {
      "addedRecent": { "264431": 264431 },
      "addedChats": { "264431": 264431 },
      "deletedChats": { "264418": 264418 },
      "completeDeletedChats": []
    },
    "messageSync": {
      "addedMessages": { "609001": 609001 },
      "updatedMessages": [],
      "completeDeletedMessages": []
    },
    "pinSync": {
      "addedPins": [],
      "deletedPins": []
    },
    "userSync": {
      "updatedUsers": [],
      "deletedUsers": []
    },
    "messages": [
      {
        "id": 609001,
        "chatId": 264431,
        "authorId": 1,
        "date": "2026-09-24T21:10:22+00:00",
        "text": "The draft plan is ready"
      }
    ],
    "chats": [
      {
        "id": 264431,
        "dialogId": "chat264431",
        "name": "Release preparation",
        "type": "chat"
      }
    ],
    "dialogIds": { "264431": "chat264431" },
    "navigationData": {
      "lastServerDate": "2026-09-24T21:10:22+00:00",
      "hasMore": false,
      "lastId": 182091
    }
  }
}

Error response example

400 — a date without an offset:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`lastDate` must be a datetime YYYY-MM-DDTHH:MM:SS with a UTC offset (+03:00) or Z and no fractional seconds — `navigationData.lastServerDate` of the previous page."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionNo lastDate, lastDate not in the YYYY-MM-DDTHH:MM:SS format with an offset or Z, or with a nonexistent date or time (2026-02-30, 24:00), lastId less than 0, a non-numeric limit, a parameter other than lastDate, lastId and limit, or a repeated parameter. Checked before the Bitrix24 call
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the Bitrix24 code is in error.b24Code
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

An empty collection arrives as an array. When a change group has no entries, an empty array arrives instead of an object: "updatedMessages": []. Read such fields with Object.values, which handles both forms the same way.

The incremental log does not guarantee four weeks of history. Some Bitrix24 change records remain for only about a day. After a long interruption, especially one approaching a day, re-read recent dialogs and the needed message history in full before trusting a new delta.

Sync can be turned off on a Bitrix24 account. Then data is an empty array, not an object with the fields above. In that case, re-read the list in full.

These are not real-time events. The endpoint answers "what has changed since a given time"; to receive new messages as they appear, use event polling.

See also