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

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

GET /v1/chats/events

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

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

Параметры

Параметр Тип Обяз. По умолч. Описание
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
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 Код Описание
400 MISSING_PARAMS Параметр offset не передан или пустой
400 INVALID_OFFSET Значение offset не является целым неотрицательным числом (дробные, отрицательные, ведущие нули, посторонние символы)
400 INVALID_LIMIT Значение limit вне диапазона 1–1000 или не является целым числом
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст ошибки в message)
502 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 секунд между запросами. При пустом ответе не увеличивайте частоту — события будут доставлены при следующем вызове. Подробнее о лимитах — Лимиты и оптимизация.

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

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()

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