Для AI-агентов: markdown этой страницы — /docs-content/chats/events/poll.md индекс документации — /llms.txt

Получить события

GET /v1/chats/events

Возвращает накопленные пользовательские события мессенджера начиная с указанной позиции. Параметр offset обязателен — передайте 0 при первом вызове, затем nextOffset из каждого ответа.

Требует предварительной подписки. Без активной подписки события не накапливаются, ответ будет пустым.

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрoffset (query) Типnumber Обяз.да По умолч.— ОписаниеНачальная позиция. Первый вызов: 0. Следующие вызовы: значение nextOffset из предыдущего ответа
Параметрlimit (query) Типnumber Обяз.нет По умолч.100 ОписаниеМаксимальное количество событий за один вызов (1–1000)

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/events?offset=0&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/events?offset=0&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/events?offset=0&limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Событий:', data.events.length, 'Следующий offset:', data.nextOffset)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/events?offset=0&limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеКонтейнер результата
Полеdata.events Типarray ОписаниеМассив событий
Полеdata.events[].eventId Типnumber ОписаниеИдентификатор события. Используется как offset в следующем запросе
Полеdata.events[].type Типstring ОписаниеТип события (ONIMV2MESSAGEADD, ONIMV2JOINCHAT и др.)
Полеdata.events[].date Типstring ОписаниеДата и время события (ISO 8601)
Полеdata.events[].data Типobject ОписаниеДанные события, поля в camelCase. Состав зависит от type. Поля события ONIMV2MESSAGEADD описаны в разделе User-события
Полеdata.nextOffset Типnumber ОписаниеЗначение для параметра offset в следующем запросе
Полеdata.hasMore Типboolean Описаниеtrue — есть ещё события за пределами текущего ответа

Пример ответа

Есть новые события:

JSON 
{
  "success": true,
  "data": {
    "events": [
      {
        "eventId": 101,
        "type": "ONIMV2JOINCHAT",
        "date": "2026-06-05T10:00:00+03:00",
        "data": {
          "dialogId": "chat100",
          "chat": {
            "id": 100,
            "name": "Чат проекта",
            "type": "open"
          },
          "user": {
            "id": 42,
            "name": "Иван Иванов"
          }
        }
      },
      {
        "eventId": 103,
        "type": "ONIMV2MESSAGEADD",
        "date": "2026-06-05T10:01:30+03:00",
        "data": {
          "message": {
            "id": 500,
            "chatId": 100,
            "text": "Всем привет!"
          },
          "chat": {
            "id": 100,
            "name": "Чат проекта"
          },
          "user": {
            "id": 42,
            "name": "Иван Иванов"
          }
        }
      }
    ],
    "nextOffset": 104,
    "hasMore": false
  }
}

Пустой ответ (новых событий нет):

JSON 
{
  "success": true,
  "data": {
    "events": [],
    "nextOffset": 104,
    "hasMore": false
  }
}

Пример ответа при ошибке

400 — не передан обязательный параметр offset:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Query parameter `offset` is required. Pass `0` for the first call, then `nextOffset` from each response to advance the cursor."
  }
}

Ошибки

HTTP Код Описание
HTTP200 КодWarning: 299 ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning.
HTTP400 только при включённом строгом режиме КодUNSUPPORTED_FILTER ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные.
HTTP400 КодMISSING_PARAMS ОписаниеПараметр offset не передан или пустой
HTTP400 КодINVALID_OFFSET ОписаниеЗначение offset не является целым неотрицательным числом (дробные, отрицательные, ведущие нули, посторонние символы)
HTTP400 КодINVALID_LIMIT ОписаниеЗначение limit вне диапазона 1–1000 или не является целым числом
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа im
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 вернул ошибку (текст ошибки в message)
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ошибку сервера

Полный список общих ошибок API — Ошибки.

Типы событий

Поле type каждого события — один из кодов:

Событие Описание
СобытиеONIMV2MESSAGEADD ОписаниеНовое сообщение в подписанном чате
СобытиеONIMV2MESSAGEUPDATE ОписаниеСообщение отредактировано
СобытиеONIMV2MESSAGEDELETE ОписаниеСообщение удалено
СобытиеONIMV2JOINCHAT ОписаниеУчастник зашёл в чат
СобытиеONIMV2REACTIONCHANGE ОписаниеРеакция на сообщение изменена

Известные особенности

Токен обязателен. Для личного ключа vibe_api_… достаточно заголовка X-Api-Key. Для OAuth-ключа vibe_app_… обязательно добавлять Authorization: Bearer <session_token> — без него запрос вернёт 401 TOKEN_MISSING. Получение токена для OAuth-приложения — см. Ключи и авторизация.

Курсор на стороне клиента. В отличие от опроса событий бота, этот эндпоинт не хранит позицию offset в базе данных — управление курсором на стороне вызывающего кода. При первом вызове передавайте offset=0, при последующих — значение nextOffset из предыдущего ответа.

Цепочка запросов:

GET /v1/chats/events?offset=0   → { nextOffset: 104, hasMore: true }
GET /v1/chats/events?offset=104 → { nextOffset: 112, hasMore: false }
GET /v1/chats/events?offset=112 → { events: [], hasMore: false }

Рекомендуемый интервал опроса: 2–5 секунд между запросами. При пустом ответе не увеличивайте частоту — события будут доставлены при следующем вызове. Подробнее о лимитах — Лимиты и оптимизация.

Опрос не удерживает машину в сети. Если цикл ниже работает на сервере Black Hole, отключите на нём авто-сон. Таймер простоя считает входящие обращения к серверу, а опрос делает только исходящие вызовы — с точки зрения таймера сервер простаивает и через час засыпает вместе с процессом, который опрашивает. Отключается вызовом PATCH /v1/infra/servers/:id/sleep со значением sleepAfterMinutes: null.

Цикл опроса (готовый пример):

javascript 
const API_KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function pollChatEvents() {
  // Сначала подписаться — без подписки события не накапливаются
  await fetch(`${BASE}/chats/events/subscribe`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY },
  })

  let offset = 0

  while (true) {
    try {
      const res = await fetch(`${BASE}/chats/events?offset=${offset}`, {
        headers: { 'X-Api-Key': API_KEY },
      })
      const { data } = await res.json()

      for (const event of data.events ?? []) {
        await handleEvent(event)
      }

      if (data.nextOffset !== undefined) {
        offset = data.nextOffset
      }

      if (!data.hasMore) {
        await new Promise(r => setTimeout(r, 3000))
      }
    } catch (err) {
      console.error('Ошибка опроса:', err.message)
      await new Promise(r => setTimeout(r, 5000))
    }
  }
}

async function handleEvent(event) {
  switch (event.type) {
    case 'ONIMV2MESSAGEADD':
      console.log('Новое сообщение:', event.data.message?.text)
      break
    case 'ONIMV2JOINCHAT':
      console.log('Участник зашёл в чат:', event.data.chat?.name)
      break
    case 'ONIMV2MESSAGEDELETE':
      console.log('Сообщение удалено:', event.data.message?.id)
      break
    default:
      console.log('Событие:', event.type)
  }
}

pollChatEvents()

Смотрите также