Событие при появлении новых записей в очереди офлайн-событий onOfflineEvent

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

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

Scope: базовый

Кто может подписаться: любой пользователь

Событие ONOFFLINEEVENT сработает, когда в очереди офлайн-событий появятся новые записи.

Событие заменяет опрос очереди по таймеру: приложение получает сигнал и забирает накопленные записи методами event.offline.get или event.offline.list.

Подписывайтесь на ONOFFLINEEVENT только как на обычное событие — с URL обработчика в параметре handler метода event.bind. Подписка с event_type = offline возвращает ошибку ERROR_ARGUMENT с текстом Offline event cannot be registered for this event: само уведомление об очереди в очередь не складывается.

Подписаться может любой пользователь, но только из приложения: event.bind работает лишь с авторизацией OAuth 2.0 и отклоняет вызов вебхука. Забрать записи из очереди методами event.offline.* может только администратор и тоже только в контексте приложения. Подробнее в статье Офлайн-события.

События не будут отправляться в приложение, пока установка не завершена. Проверьте установку приложения

Что получает обработчик

Данные передаются в виде POST-запроса

{
    "event": "ONOFFLINEEVENT",
    "event_handler_id": "185",
    "data": [],
    "ts": "1466439714",
    "auth": {
        "access_token": "s6p6eclrvim6da22ft9ch94ekreb52lv",
        "expires_in": "3600",
        "scope": "crm,task",
        "domain": "some-domain.bitrix24.ru",
        "server_endpoint": "https://oauth.bitrix24.tech/rest/",
        "status": "F",
        "client_endpoint": "https://some-domain.bitrix24.ru/rest/",
        "member_id": "a223c6b3710f85df22e9377d6c4f7553",
        "refresh_token": "4s386p3q0tr8dy89xvmt96234v3dljg8",
        "application_token": "51856fefc120afa4b628cc82d3935cce"
    }
}

Параметры запроса

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

Название
тип

Описание

event*
string

Символьный код события — ONOFFLINEEVENT

event_handler_id*
integer

Идентификатор обработчика события

data*
array

Приходит пустым.

Подробнее ниже

ts*
timestamp

Дата и время отправки уведомления из общей очереди событий

auth*
object

Объект, содержащий параметры авторизации и данные о Битрикс24, на котором произошло событие.

Значение scope — список прав, выданных приложению. Событие базовое и не требует отдельного скоупа.

Структура описана ниже

Параметр data

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

Чтобы получить сами события, вызовите event.offline.get или event.offline.list. Состав записи очереди описан на страницах этих методов.

Параметр auth

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

Название
тип

Описание

access_token
string

Токен авторизации OAuth 2.0

expires_in
integer

Время в секундах до истечения срока действия токена

scope*
string

Скоуп, в рамках которого произошло событие

domain*
string

Адрес Битрикс24, на котором произошло событие

server_endpoint*
string

Адрес сервера авторизации Битрикс24, необходимый для обновления токенов OAuth 2.0

status*
string

Статус приложения, подписавшегося на это событие:

client_endpoint*
string

Общий путь для вызовов методов REST API для Битрикс24, на котором произошло событие

member_id*
string

Идентификатор Битрикс24, на котором произошло событие

refresh_token
string

Токен продления авторизации OAuth 2.0

application_token*
string

Токен для безопасной обработки событий

Токены авторизации не всегда передаются в обработчик события. Если хит, инициировавший событие, не удалось привязать к конкретному пользователю Битрикс24, токены не передаются. Обязательно проверяйте содержимое ключа auth в коде.

Рекомендуем хранить токены, полученные ранее при установке приложения. Используйте их при работе с интерфейсом приложения в виде встроек, виджетов и так далее.

Периодичность уведомлений

Битрикс24 не отправляет отдельное уведомление на каждую запись очереди. Минимальный интервал между уведомлениями задается параметром minTimeout в объекте options при подписке методом event.bind.

Это единственный параметр options, который поддерживает ONOFFLINEEVENT.

Название
тип

Описание

minTimeout
integer

Минимальный интервал между уведомлениями в секундах. По умолчанию — 1.

0 — обработчик получит одно уведомление на один запрос к Битрикс24, сколько бы записей этот запрос ни добавил в очередь.

Больше 0 — первое срабатывание отправляет уведомление сразу, следующее уйдет не раньше, чем через указанное число секунд

Тело запроса event.bind для подписки с интервалом 60 секунд:

{
    "event": "ONOFFLINEEVENT",
    "handler": "https://example.com/handler.php",
    "options": {
        "minTimeout": 60
    }
}

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

Предыдущая
Зарегистрировать ошибки обработки очереди
Следующая
Обзор методов и событий