Получить события бота imbot.v2.Event.get

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: imbot

Кто может выполнять метод: владелец зарегистрированного бота

Метод imbot.v2.Event.get возвращает события бота, например новые сообщения и вызовы команд. Он нужен ботам с eventMode: "fetch", которые сами забирают события запросами.

Если у бота есть публичный URL, события можно получать в режиме webhook — как выбрать режим, описано в обзоре Режимы доставки событий. В режиме webhook события бота не записываются. Метод вернет пустой массив result.events, а при withUserEvents: true — только события пользователя.

Записанные события хранятся 24 часа. Более старые Битрикс24 удаляет, даже если бот их не получил.

События бота может получать только приложение, которое зарегистрировало бота, или вебхук с тем же botToken. У бота одна очередь: события, которые подтвердил один агент, другой уже не получит. Поэтому для нескольких независимых агентов регистрируйте отдельного бота на каждого.

Параметры метода

Обязательные параметры отмечены *

Название `Тип`	Описание
botId* `integer`	ID бота
botToken `string`	Уникальный токен авторизации бота — тот, что указали при регистрации, или новый после смены токена методом imbot.v2.Bot.update. Обязателен, если метод вызывают через входящий вебхук, для OAuth не нужен
offset `integer`	Подтверждает и удаляет из очереди все события с ID меньше указанного значения. Передавайте `nextOffset` из предыдущего ответа. При первом вызове параметр не нужен. По умолчанию `0`. Если передать значение больше `nextOffset`, метод удалит и события, которые вы еще не получили
limit `integer`	Максимальное количество возвращаемых событий (1–1000). По умолчанию `100`. Значение вне диапазона метод заменяет ближайшей границей
withUserEvents `boolean`	Включить события пользователя (`ONIMV2`) в ответ вместе с событиями бота (`ONIMBOTV2`). По умолчанию `false`. Работает, если: у приложения есть scope `im` в дополнение к `imbot` пользователь, от чьего имени выполнен вызов, подписан через im.v2.Event.subscribe Метод возвращает события только этого пользователя. Один `offset` подтверждает события бота и пользователя. Очередь событий пользователя общая с im.v2.Event.get: события, подтвержденные в этом методе, `im.v2.Event.get` уже не вернет

Примеры кода

Как использовать примеры в документации

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"botToken":"my_bot_token","offset":1000,"limit":50}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Event.get

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"offset":1000,"limit":50,"auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/imbot.v2.Event.get

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type EventGetResult = {
  events: Array<{
    eventId: number
    type: string
    date: string
    data: Record<string, unknown>
  }>
  nextOffset: number
  hasMore: boolean
}

try {
  const response = await $b24.actions.v2.call.make<EventGetResult>({
    method: 'imbot.v2.Event.get',
    params: {
      botId: 456,
      botToken: 'my_bot_token',
      offset: 1000,
      limit: 50,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Events:', result.events.length, '| nextOffset:', result.nextOffset, '| hasMore:', result.hasMore)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function getEvents() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'imbot.v2.Event.get',
        params: {
          botId: 456,
          botToken: 'my_bot_token',
          offset: 1000,
          limit: 50,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Events:', result.events.length, '| nextOffset:', result.nextOffset, '| hasMore:', result.hasMore)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', getEvents)
</script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.imbot.v2.event.get(
        bot_id=456,
        bot_token="my_bot_token",
        offset=1000,
        limit=50,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

try {
    $response = $b24Service
        ->core
        ->call(
            'imbot.v2.Event.get',
            [
                'botId' => 456,
                'botToken' => 'my_bot_token',
                'offset' => 1000,
                'limit' => 50,
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'result: ' . print_r($result, true);
} catch (Throwable $exception) {
    error_log($exception->getMessage());
    echo 'Error: ' . $exception->getMessage();
}

BX24.callMethod(
    'imbot.v2.Event.get',
    {
        botId: 456,
        botToken: 'my_bot_token',
        offset: 1000,
        limit: 50,
    },
    function(result) {
        if (result.error()) {
            console.error(result.error().ex);
        } else {
            console.log(result.data());
        }
    }
);

require_once('crest.php');

$result = CRest::call(
    'imbot.v2.Event.get',
    [
        'botId' => 456,
        'botToken' => 'my_bot_token',
        'offset' => 1000,
        'limit' => 50,
    ]
);

if (!empty($result['error'])) {
    echo 'Error: ' . $result['error_description'];
} else {
    foreach ($result['result']['events'] as $event) {
        echo $event['type'] . ': ' . $event['eventId'] . "\n";
    }
}

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "imbot.v2.Event.get", b24.Params{
	"botId":    456,
	"botToken": "my_bot_token",
	"offset":   1000,
	"limit":    50,
}, b24.WithIdempotent())
if err != nil {
	return fmt.Errorf("imbot.v2.Event.get: %w", err)
}

var item struct {
	NextOffset int  `json:"nextOffset"`
	HasMore    bool `json:"hasMore"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.NextOffset, item.HasMore)

Обработка ответа

HTTP-статус: 200

{
    "result": {
        "events": [
            {
                "eventId": 1001,
                "type": "ONIMBOTV2MESSAGEADD",
                "date": "2024-10-11T09:58:12+03:00",
                "data": {
                    "message": {
                        "id": 193,
                        "chatId": 112,
                        "authorId": 129,
                        "date": "2024-10-11T09:58:12+03:00",
                        "text": "Привет! Какой статус у заказа 1024?",
                        "isSystem": false,
                        "params": []
                    },
                    "chat": {
                        "id": 112,
                        "dialogId": "129",
                        "type": "private",
                        "name": ""
                    },
                    "user": {
                        "id": 129,
                        "name": "Мария Иванова",
                        "bot": false
                    },
                    "language": "ru",
                    "additionalMessages": [],
                    "bot": {
                        "id": 456,
                        "code": "support_bot",
                        "type": "bot",
                        "eventMode": "fetch"
                    }
                }
            }
        ],
        "nextOffset": 1002,
        "hasMore": false
    },
    "time": {
        "start": 1728630000.123,
        "finish": 1728630000.234,
        "duration": 0.111,
        "processing": 0.045,
        "date_start": "2024-10-11T10:00:00+03:00",
        "date_finish": "2024-10-11T10:00:00+03:00"
    }
}

В примере объекты message, chat, user и bot сокращены. Полный состав полей — в описании события ONIMBOTV2MESSAGEADD.

Возвращаемые данные

Название `Тип`	Описание
result `object`	Результат операции
result.events `object[]`	Массив событий
result.events[].eventId `integer`	ID события
result.events[].type `string`	Тип события. Список типов описан ниже
result.events[].date `datetime`	Дата и время события
result.events[].data `object`	Данные события. Состав полей зависит от `type`, ссылки на описание каждого типа — в таблице ниже
result.nextOffset `integer`	ID, с которого начнется следующая порция. Передайте его в `offset` следующего вызова, чтобы подтвердить полученные события. Если новых событий нет, равно переданному `offset`
result.hasMore `boolean`	`true`, если метод вернул столько событий, сколько задано в `limit`: в очереди могут остаться еще. Вызовите метод снова с `offset`, равным `nextOffset`
time `time`	Информация о времени выполнения запроса

Типы событий

Тип	Описание
ONIMBOTV2MESSAGEADD	Новое сообщение боту
ONIMBOTV2MESSAGEUPDATE	Сообщение отредактировано
ONIMBOTV2MESSAGEDELETE	Сообщение удалено
ONIMBOTV2JOINCHAT	Бота добавили в чат
ONIMBOTV2DELETE	Бота удалили. В режиме `fetch` событие не приходит: очередь удаляется вместе с ботом
ONIMBOTV2CONTEXTGET	Боту пришел контекст при открытии диалога
ONIMBOTV2COMMANDADD	Вызвана слэш-команда
ONIMBOTV2REACTIONCHANGE	Реакция изменена

Сообщения бот получает, если они адресованы ему: в личном чате, с упоминанием @bot или ответом на его сообщение. Боты типа personal и supervisor получают все сообщения пользователей в групповых чатах, где состоят, кроме сообщений других ботов.

Подробное описание формата данных каждого события: Форматы событий imbot.v2.

Обработка ошибок

HTTP-статус: 400

{
    "error": "BOT_NOT_FOUND",
    "error_description": "Bot not found"
}

Название `тип`	Описание
error `string`	Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только `error_description`
error_description `string`	Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Код	Описание	Значение
`BOT_TOKEN_NOT_SPECIFIED`	Bot token not specified (botToken is required for webhook auth)	Не указан `botToken`. Обязателен при авторизации через вебхук
`BOT_ID_REQUIRED`	botId is required	Не указан `botId` или он меньше 1
`BOT_NOT_FOUND`	Bot not found	Бот не найден
`BOT_OWNERSHIP_ERROR`	Bot was installed by another rest application	Бот зарегистрирован другим приложением или с другим `botToken`
`SCOPE_ERROR`	Scope 'im' is required to fetch user events	Передан `withUserEvents: true`, но у приложения нет scope `im`
`AUTH_ERROR`	Authorization required for user events	Не удалось определить текущего пользователя
`USER_NOT_SUBSCRIBED`	User is not subscribed. Call im.v2.Event.subscribe first	Передан `withUserEvents: true`, но пользователь не подписан на события через im.v2.Event.subscribe
`100`	Invalid value {abc} to match with parameter {offset}. Should be value of type int.	В `offset` или `limit` передано не число

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит
`401`	`NO_AUTH_FOUND` Wrong authorization data	В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука
`401`	`INVALID_REQUEST` Https required	Методы вызываются только по протоколу HTTPS
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на `provided by the access token`
`401`	`expired_token` The access token provided has expired	Срок действия access-токена истек
`401`	`user_access_error` The user does not have access to the application	Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям
`403`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение

Была ли статья полезна?

Обзор методов

Форматы событий

Получить события бота imbot.v2.Event.get

Параметры методаПараметры метода

Примеры кодаПримеры кода

Обработка ответаОбработка ответа

Возвращаемые данныеВозвращаемые данные

Типы событийТипы событий

Обработка ошибокОбработка ошибок

Возможные коды ошибокВозможные коды ошибок

Статусы и коды системных ошибокСтатусы и коды системных ошибок

Продолжите изучениеПродолжите изучение