Не приходят уведомления в Битрикс24: диагностика push, почты и мессенджера

Не приходят уведомления в Битрикс24: с чего начать диагностику

Когда к нам приходят с жалобой «уведомления не приходят», первым делом мы уточняем: какие именно уведомления. В Битрикс24 уведомление — это не одна сущность, а минимум четыре независимых канала доставки, и ломается всегда конкретный канал, а не «уведомления вообще». Административная плашка (CAdminNotify::Add) живёт внутри веб-интерфейса и не зависит от сети. Уведомление в мессенджер (CIMNotify::Add) проходит через модуль im. Push на телефон уходит через CPullStack::AddByUsers и модуль Push&Pull. Почта — отдельная история с sendmail, SMTP и очередью отправки.

По нашему опыту, в проектах с активной интеграцией через REST и в коробочных установках с закрытым контуром чаще всего «молчит» именно Push&Pull: сервер очередей не достучался до внешних доменов, и push не доходит, хотя в веб-интерфейсе сообщение видно. Второй по частоте случай — почта: SMTP-авторизация слетела после смены пароля у внешнего провайдера, а уведомления просто копятся в очереди. Диагностику мы всегда строим от канала к модулю, а не наоборот: сначала определяем, какой именно канал не сработал, потом смотрим его модуль, потом настройки сервера, и только в конце — логи. Так не приходится гадать и трогать то, что работает.

Ниже — рабочий порядок проверки, матрица «канал → модуль → где смотреть» и принцип, который экономит нам часы на каждом обращении.

Порядок диагностики, которого мы придерживаемся в проектах:

1. Определить канал — админская плашка, мессенджер, push или почта. Спросить пользователя, где именно он ждёт уведомление.
2. Проверить модуль канала — im для мессенджера, pull и push для пушей, main для почты. Убедиться, что модуль установлен и активен.
3. Посмотреть настройки сервера — доступ к внешним доменам для пушей, параметры sendmail/SMTP для почты, состояние сервера очередей.
4. Воспроизвести отправку вручную — через CIMNotify::Add, CPullStack::AddByUsers или тестовое письмо из «Проверки системы».
5. Открыть логи — журнал событий, лог ошибок PHP, очередь отправки почты. Искать ошибку именно того канала, который не сработал.

Подробнее: ускорить битрикс.

Подробнее: BitrixVM показывает исходный код.

Уведомления Битрикс24 не работают: проверка системы и логи

Встроенная «Проверка системы» — первый инструмент, к которому стоит идти, когда уведомления молчат. Она живёт в админке по пути Настройки > Инструменты > Проверка системы и умеет тестировать SMTP-соединение и отправку почты: проверяет, что сервер вообще способен дотянуться до почтового релея и передать ему письмо. Полезно, но это только половина картины. Тест отвечает на вопрос «может ли PHP отправить письмо», а не на вопрос «дошло ли письмо до пользователя и по какой причине оно застряло».

Именно поэтому без логов диагностика превращается в перебор настроек: администратор по очереди меняет SMTP-хост, порт, шифрование, отправителя, перезапускает агенты — и не понимает, что из этого помогло, а что просто совпало. Логи дают факты. Журнал событий покажет, что происходило с модулями и агентами, лог отправки почты — что реально ушло наружу, а очередь postfix — что застряло на самом сервере. Дальше разберём три шага проверки и два частых сценария, когда тест зелёный, а результата нет.

1. Открыть Настройки > Инструменты > Проверка системы и запустить тест SMTP-сервера и отправки почты — это даст базовый ответ, работает ли канал отправки вообще.
2. Проверить статус модулей Push&Pull, intranet, im и mail через админку: модули должны быть установлены и активны, иначе часть уведомлений просто не генерируется.
3. Посмотреть журнал событий и лог отправки почты — в коробке это bitrix/modules/main/tools/sendmail.php, либо настройки модуля mail с включённым логированием исходящих писем.

# Очередь postfix и лог отправки на сервере коробки
mailq | tail -n 30
# если очередь растёт — письма не уходят наружу

tail -n 100 /var/log/mail.log
# ищем строки с нашим отправителем и статусами deferred / bounced

grep -i "deferred\|bounced\|rejected" /var/log/mail.log | tail -n 50
# здесь видно, на каком этапе релей отказывается принимать письмо

postqueue -p
# альтернативный способ посмотреть очередь на Debian/Ubuntu

Что делать, если тест SMTP проходит, а письма не доходят

Самая частая причина — расхождение между «соединение установлено» и «письмо доставлено». Тест SMTP проверяет только рукопожатие с релеем, а не то, что релей принял письмо и передал его дальше. На практике мы сначала смотрим лог отправки: есть ли запись о конкретном письме, какой у него статус. Если письмо ушло, но не дошло — проблема на стороне внешнего сервиса или в спам-фильтрах получателя.

Дальше проверяем отправителя. Если в настройках модуля mail указан адрес вида noreply@localhost или ящик, не совпадающий с доменом сайта, большинство релеев и почтовых сервисов отбросят такое письмо или положат в спам. В коробке почту можно настроить тремя способами: локальный sendmail/postfix на Linux, внешний SMTP без авторизации на Windows, либо внешний SMTP с авторизацией через замену функции отправки. От выбранного способа зависит, где именно искать причину — в очереди локального агента или в логах внешнего сервиса.

Полезно сравнить поведение двух режимов: «Встроенная почта» и «SMTP». Если встроенная почта работает, а SMTP — нет, вопрос в параметрах внешнего сервера (порт, шифрование, логин). Если наоборот — проблема в локальном агенте. Такой перебор за две итерации обычно отсекает половину гипотез.

Что делать, если модуль Push&Pull активен, но пушей нет

Модуль Push&Pull отвечает за мгновенную доставку событий в задачи, календари, ленту, группы и RPA. Если он активен, но пуши не приходят, первым делом проверяем сервер очередей — его настройки в админке можно сбросить кнопкой «По умолчанию», и это часто лечит зависшие соединения. После сброса модуль пересоздаёт подключение к очереди, и часть «залипших» подписок оживает.

Второй момент — доступ к внешним доменам. В коробке для работы пушей нужен доступ к cloud-messaging.bitrix24.com, для коннекторов — к im.bitrix.info, для ботов — к marta.bitrix.info. Если сервер стоит в закрытом контуре и эти адреса недоступны, модуль активен, но доставить пуш физически некуда. Проверяется просто: с сервера должен открываться исходящий HTTPS к этим хостам.

Третий момент — версии модулей. По опыту подрядчиков, для корректной работы интеграций в коробке рекомендуются REST API не ниже 16.6.5, intranet не ниже 16.6.4, главный модуль не ниже 16.5.11. Это не официальная норма, а практическое наблюдение: на более старых сборках часть событий мессенджера просто не генерируется.

Настройка уведомлений Битрикс24: каналы, шаблоны и типы событий

Многие думают, что «уведомления включены у всех» — значит, они настроены. в Битрикс24 настройки уведомлений размазаны по трём уровням, и на каждом живёт свой набор параметров. Персональные настройки — в профиле конкретного сотрудника: там он сам решает, что хочет получать, а что нет. Административные — в модулях main, im и mail: здесь включаются каналы доставки, шаблоны писем, лимиты и глобальные переключатели. И наконец разработческий уровень — это события и методы API, через которые ваш код вообще формирует уведомление: CIMNotify::Add, CAdminNotify::Add, im.notify.system.add и события мессенджера.

Почему это важно различать? Потому что симптом «уведомления не приходят» может жить на любом из трёх уровней, и лечится каждый по-своему. Если сотрудник сам выключил себе email-оповещения в профиле — никакая админская настройка не поможет. Если администратор не заполнил шаблон письма — уведомление уйдёт пустым. Если разработчик забыл NOTIFY_TAG — пользователь увидит десять отдельных строк вместо одной сгруппированной. Дальше разберём все три уровня по порядку — от того, что доступно рядовому сотруднику, до того, что настраивает только админ или разработчик.

Персональные настройки пользователя: что может отключить сам сотрудник

Каждый сотрудник в своём профиле (Профиль → Настройки → Уведомления) управляет каналами по типам событий. Типовых каналов три: живая лента, email и push на мобильное приложение (через модуль Push&Pull). Для каждого типа события — новое сообщение в чате, упоминание, задача, комментарий в ленте — сотрудник выбирает, куда доставлять и доставлять ли вообще.

Здесь кроется первая ловушка диагностики: человек мог отключить канал сам и забыть. Прежде чем лезть в админку и логи, стоит проверить профиль конкретного пользователя — не выключен ли у него email или push. Это частая причина жалоб «у меня не работает, а у коллег работает».

Ещё нюанс: настройки в профиле не отменяют серверные — они лишь фильтруют то, что уже сформировано. Если модуль mail не настроен, никакой персональный переключатель письма не доставит.

Административные настройки модулей: где включать каналы и шаблоны

Админский уровень — это уже про инфраструктуру. В модуле main настраивается почта: способ отправки (встроенный sendmail/postfix на Linux, внешний SMTP без авторизации на Windows или внешний SMTP с авторизацией через подмену функции отправки). Ровно здесь же — шаблоны писем, которые подставляются в уведомления по типу события.

В модуле im живут настройки мессенджера и push-уведомлений. Модуль Push&Pull отвечает за мгновенную доставку: именно он решает, сколько сообщений уходит в одном пакете и как группируются оповещения. Настройки сервера очередей при необходимости сбрасываются кнопкой «По умолчанию» в административном интерфейсе.

По опыту подрядчиков, для закрытого контура «коробки» уведомления требуют доступа к внешним доменам: cloud-messaging.bitrix24.com — для пушей, im.bitrix.info — для коннекторов, marta.bitrix.info — для ботов. Без этих доступов часть каналов молча не работает, хотя формально «включена».

Теперь — как уведомление формируется из кода. Ниже два рабочих примера: обычное уведомление пользователю и админская плашка.

<?php
use Bitrix\Main\Loader;

Loader::includeModule('im');

$arNotify = [
    'TO_USER_ID'  => 42,
    'FROM_USER_ID' => 1,
    'NOTIFY_TYPE' => IM_NOTIFY_FROM,
    'NOTIFY_MODULE' => 'custom.module',
    'NOTIFY_TAG' => 'ORDER|STATUS_CHANGED|42',
    'NOTIFY_MESSAGE' => 'Заказ №1234 перешёл в статус «Оплачен».',
];

CIMNotify::Add($arNotify);

Ключевое здесь — NOTIFY_TAG. Он собирает все уведомления с одинаковым тегом в одну группу у пользователя. Без тега каждое сообщение встанет отдельной строкой.

<?php
use Bitrix\Main\Loader;

Loader::includeModule('main');

CAdminNotify::Add([
        'MESSAGE' => 'Не заполнены реквизиты компании. Перейти к настройкам',
        'TAG'     => 'COMPANY_REQUISITES',
        'MODULE_ID' => 'main',
        'ENABLE_CLOSE' => 'Y',
        'NOTIFY_TYPE' => 'E', // красная предупреждающая плашка
]);

Параметр NOTIFY_TYPE => 'E' меняет цвет плашки с зелёного на красный — визуальный сигнал «требует внимания». По умолчанию плашка зелёная и закрывается администратором из интерфейса.

Push-уведомления Битрикс24: как работает модуль Push&Pull

Многие думают, что push в Битрикс24 — это «ещё один канал» рядом с почтой и чатом. это отдельная транспортная история: чтобы пуш дошёл до телефона, должен работать модуль Push&Pull, а сам он ходит во внешний сервис cloud-messaging.bitrix24.com. Когда модуль выключен или сервер не видит этот домен — пуши не приходят, сколько бы галочек в профиле пользователя ни стояло.

Модуль Push&Pull отвечает за мгновенное взаимодействие в Задачах, Календарях, ленте Новостей, Группах и RPA. Схема простая: сервер Битрикс24 формирует событие, модуль кладёт его в очередь, затем через cloud-messaging.bitrix24.com отправляет на устройство пользователя. В облаке это работает «из коробки». В коробочной версии — только если сервер имеет исходящий доступ к внешним доменам Битрикс24. В закрытом контуре, где наружу ничего не ходит, push-уведомления перестают доставляться целиком: событие в очереди есть, а забрать его некому.

flowchart LR
    A[Сервер Битрикс24] -->|"событие"| B[Модуль Push&Pull]
    B -->|"очередь"| C[cloud-messaging.bitrix24.com]
    C -->|"доставка"| D[Мобильное устройство]

Push можно отправить и без сообщения в мессенджер — через CPullStack::AddByUsers. Метод принимает массив ID пользователей и текст, а количество сообщений в пакете ограничено настройками модуля Push&Pull. Так удобно слать короткие сервисные сигналы: «задача просрочена», «отчёт готов», «пришёл новый лид».

<?php
use Bitrix\Main\Loader;

Loader::includeModule('pull');

$userIds = [12, 34, 56]; // замените на ваши ID пользователей

\CPullStack::AddByUsers($userIds, [
        'module_id' => 'custom.notify',
        'command'   => 'notify',
        'params'    => [
            'title' => 'Отчёт готов',
            'text'  => 'Выгрузка за прошлый месяц сформирована',
            'url'   => '/reports/monthly/',
        ],
]);

Настройки сервера очередей и кнопка «По умолчанию»

Настройки сервера очередей живут в административном интерфейсе модуля Push&Pull. Там задаются адрес сервера, параметры подключения и лимит сообщений в пакете. Если после экспериментов пуши перестали ходить, а исходные значения вы не помните — есть кнопка «По умолчанию», которая сбрасывает конфигурацию к заводской.

По нашему опыту, в коробке чаще всего ломается именно этот блок: администратор менял адрес сервера очередей под внутренний брокер, а модуль после этого не смог достучаться до cloud-messaging.bitrix24.com. Кнопка сброса возвращает штатные значения и обычно решает проблему за минуту. Не помогло — проверяйте сетевой доступ, а не настройки.

Ограничения: вложения и MESSAGE_OUT при отправке в push

Push — канал с урезанными возможностями. Вложения (attachments) не добавляются автоматически, когда уведомление уходит в XMPP, почту или PUSH. Если вы привыкли передавать картинки и файлы в чат-сообщении, для пуша их придётся заполнять вручную — либо вовсе отказаться от идеи.

Отдельная ловушка — поле MESSAGE_OUT. Для почтовых уведомлений его нужно заполнять отдельно: текст, который видит пользователь в интерфейсе, и текст, уходящий в письмо, — это разные поля. Если MESSAGE_OUT пустой, письмо придёт без тела. В push-канал это поле не уходит, но при комбинированной отправке (чат + почта + пуш) его отсутствие ломает как минимум почтовую часть.

Внешние домены, доступ к которым нужен в закрытом контуре:

• cloud-messaging.bitrix24.com — доставка push-уведомлений на мобильные устройства и в десктоп;
• im.bitrix.info — работа коннекторов мессенджера и внешних каналов связи;
• marta.bitrix.info — сервис ботов и часть сценариев автоматизации.

Почтовые уведомления Битрикс24: SMTP, sendmail и внешние сервисы

Типичный сценарий: интернет-магазин на коробке шлёт клиентам подтверждения заказов через встроенную «Почту», а параллельно Битрикс24 рассылает сотрудникам уведомления о новых лидах и комментариях. Письма уходят в спам, часть не доходит вовсе, а в логах тишина. Причина в том, что в коробочной версии почта — это не «включённая галочка», а транспорт, который нужно выбрать сознательно: локальный MTA, внешний SMTP без авторизации или внешний SMTP с авторизацией.

В облаке всё проще: Битрикс24 отправляет письма через свои серверы, и трогать там нечего. А вот на коробке вариантов ровно три, и они не равнозначны:

• Локальный sendmail/postfix — для Linux-серверов. Письма уходят напрямую с вашего IP, но без правильных PTR-записей и SPF их начнут резать почтовики получателей.
• Внешний SMTP без авторизации — рабочий вариант для Windows, когда есть доверенный релей в локальной сети.
• Внешний SMTP с авторизацией — то, что мы рекомендуем по умолчанию: подключаете Яндекс 360, Mail.ru, RuSender или корпоративный релей, и письма уходят от вашего домена с валидной подписью.

Третий способ требует замены штатной функции отправки. Это не хак, а штатный механизм через событие OnBeforeMailSend. О нём и поговорим.

Замена отправки через OnBeforeMailSend — идиоматичный для коробки способ. Событие перехватывает письмо до того, как его отдадут в mail(), и позволяет отправить через любой SMTP-клиент с авторизацией:

<?php
// bitrix/php_interface/init.php
use Bitrix\Main\EventManager;
use Bitrix\Main\Mail\Event;

EventManager::getInstance()->addEventHandler(
    'main',
    'OnBeforeMailSend',
    'customSmtpSend'
);

function customSmtpSend($arFields)
{
    // Параметры внешнего SMTP — замените на свои
    $host = 'smtp.yandex.ru';
    $port = 465;
    $user = 'robot@example.ru';
    $pass = 'app-password-here';
    $from = 'robot@example.ru';

    $to = is_array($arFields['TO']) ? implode(',', $arFields['TO']) : $arFields['TO'];
    $subject = $arFields['SUBJECT'] ?? '';
    $body = $arFields['BODY'] ?? '';

    $fp = stream_socket_client(
        'ssl://' . $host . ':' . $port,
        $errno, $errstr, 10
    );
    if (!$fp) {
        return false; // пробуем штатный способ
    }

    $read = function () use ($fp) { return fgets($fp, 512); };
    $write = function ($cmd) use ($fp) { fwrite($fp, $cmd . "\r\n"); };

    $read();
    $write('EHLO ' . $_SERVER['SERVER_NAME']);
    while ($line = $read()) { if (substr($line, 3, 1) === ' ') break; }

    $write('AUTH LOGIN');
    $read();
    $write(base64_encode($user));
    $read();
    $write(base64_encode($pass));
    $read();

    $write('MAIL FROM:<' . $from . '>');
    $read();
    $write('RCPT TO:<' . $to . '>');
    $read();
    $write('DATA');
    $read();

    $headers  = 'From: ' . $from . "\r\n";
    $headers .= 'To: ' . $to . "\r\n";
    $headers .= 'Subject: =?UTF-8?B?' . base64_encode($subject) . '?=' . "\r\n";
    $headers .= 'MIME-Version: 1.0' . "\r\n";
    $headers .= 'Content-Type: text/html; charset=UTF-8' . "\r\n";

    $write($headers . "\r\n" . $body . "\r\n.");
    $read();
    $write('QUIT');
    fclose($fp);

    return true; // штатная отправка не выполняется
}

Ключевое здесь — возврат true из обработчика: он сообщает ядру, что письмо уже отправлено, и штатный mail() не вызывается. Если SMTP недоступен, возвращаем false — и ядро отправит письмо обычным способом. В продакшене мы обычно выносим креды в .settings.php и оборачиваем отправку в try/catch, чтобы падение SMTP не роняло страницу.

Настройка SMTP через сторонние сервисы: порт 465, SSL

Практически все внешние сервисы (Яндекс 360, Mail.ru, RuSender и подобные) принимают соединение на порту 465 с шифрованием SSL. Это SMTPS, то есть «SMTP over SSL», а не STARTTLS на 587. Перепутать легко: если указать 465 без SSL или 587 с SSL, соединение просто повиснет без внятной ошибки.

Логин — обычно полный адрес ящика, пароль — либо обычный, либо «пароль приложения», если у провайдера включена двухфакторная аутентификация. У RuSender и аналогов в панели есть готовые параметры подключения — их и подставляем в код выше без изменений. Перед боем обязательно прогоняем через Проверку системы (Настройки > Инструменты > Проверка системы): там есть тест отправки почты, который покажет, уходит ли письмо вообще.

Проверка очереди отправки и сравнение «Встроенная почта» vs SMTP

Если письма «уходят», но не доходят — смотрим очередь. В коробке она живёт в таблице b_event_message и в логе почтовых событий. Встроенная «Почта» в Битрикс24 ставит письма в очередь и пытается отправить через cron-агент, поэтому при проблемах с транспортом они копятся там молча.

Сравнение двух режимов, к которому мы приходим по опыту:

• Встроенная почта — быстро включается, не требует внешних кредов, но плохо проходит спам-фильтры получателей и не даёт нормальной диагностики.
• SMTP с авторизацией — требует настройки и хранения пароля, зато письма подписаны вашим доменом, есть отчёт о доставке у провайдера, и любую ошибку видно в логе SMTP.

На практике мы всегда смотрим, что именно «молчит»: если в b_event_message записи есть, а писем нет — проблема на транспорте, и SMTP с авторизацией её закрывает.

Системные уведомления через REST: im.notify.system.add

Самый частый запрос на эту тему — «как отправить уведомление в Битрикс24 из внешней системы». Внешняя система — это что угодно: CRM-коннектор, складская надстройка, самописный сервис мониторинга, интеграция с 1С. Она живёт вне коробки, не имеет доступа к PHP-ядру и не может вызвать CIMNotify напрямую — ей нужен REST-канал. Именно для таких сценариев в Битрикс24 есть метод im.notify.system.add: он позволяет извне положить системное уведомление конкретному пользователю в его ленту мессенджера.

Почему не CIMNotify::Add напрямую? Потому что этот метод — внутренний PHP-API. Он работает только внутри коробки, требует подключения модуля и запуска в контексте ядра. Если ваша интеграция — это отдельный микросервис, демон или вебхук из внешней системы, у неё нет ни ядра, ни сессии, ни прав. REST-метод закрывает эту дыру: авторизуетесь токеном, шлёте JSON, получаете ответ. Уведомление появляется в интерфейсе так же, как если бы его отправило ядро.

Комбинируется это с чем угодно: роботы, бизнес-процессы, внешние триггеры по вебхуку. Когда у нас интеграция живёт отдельным сервисом, im.notify.system.add — штатный способ достучаться до пользователя без проксирования через коробку.

<?php
// Отправка системного уведомления через REST-клиент Битрикс24
$webhookUrl = 'https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/';

$payload = [
    'USER_ID'   => 42,                          // замените на ID получателя
    'MESSAGE'   => 'Заказ №1024 не удалось выгрузить в 1С',
    'TYPE'      => 'SYSTEM',                    // тип системного уведомления
    'FROM_USER_ID' => 1,                        // от чьего имени показывать
];

$ch = curl_init($webhookUrl . 'im.notify.system.add.json');
curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    // логируем ошибку — уведомление не ушло
    error_log('im.notify.system.add failed: ' . $response);
}

Обязательные поля здесь — USER_ID и MESSAGE. Остальные по ситуации: TYPE задаёт визуальный тип уведомления, FROM_USER_ID определяет, от кого оно придёт. Если ID получателя приходит из внешней системы, проверяйте его существование заранее. На несуществующий USER_ID метод вернёт ошибку, а не молча проглотит.

• Модуль REST API — не ниже версии 16.6.5, иначе метод может отсутствовать в списке доступных.
• Модуль intranet — не ниже 16.6.4: он отвечает за связку пользователей и уведомлений.
• Главный модуль — не ниже 16.5.11, базовая платформа для REST-обработчиков.
• Для облака версии подтягиваются автоматически, для коробки проверяйте в «Обновлении платформы».

События мессенджера: OnBeforeMessagesAdd, OnBeforeConfirmNotify, OnAfterConfirmNotify

Самый недооценённый слой работы с уведомлениями — события мессенджера. Пока коллеги правят шаблоны и ковыряют SMTP, мы через эти хуки решаем задачи, которые иначе не решаются: отменяем отправку уведомления конкретному сотруднику, дописываем в текст данные из внешней системы, логируем факт доставки для аудита. OnBeforeMessagesAdd (с версии модуля im 11.0.1) срабатывает до записи сообщения и позволяет модифицировать массив или отменить добавление. OnBeforeConfirmNotify и OnAfterConfirmNotify (с 11.0.3) дают контроль над моментом подтверждения уведомления получателем — то есть над тем, когда сообщение реально становится «прочитанным».

У нас в практике это всплывает в двух типовых сценариях. Первый — интеграция с внешней CRM: нужно, чтобы уведомление о лиде падало в мессенджер только ответственным менеджерам, а не всем сотрудникам, и при этом содержало ссылку на карточку во внешней системе. Второй — корпоративный комплаенс: служба безопасности требует журнал всех системных уведомлений с отметкой о прочтении. Оба решаются на этих хуках. Комбинируются они с REST-методом im.notify.system.add, о котором мы говорили выше: REST создаёт уведомление, а события мессенджера его перехватывают и дорабатывают.

Регистрация обработчика — стандартная, через AddEventHandler в init.php:

<?php
// bitrix/php_interface/init.php
AddEventHandler('im', 'OnBeforeMessagesAdd', 'patchNotifyBeforeAdd');

function patchNotifyBeforeAdd(&$arFields)
{
    // Логируем входящий массив для отладки (уберите в проде)
    // AddMessage2Log(var_export($arFields, true), 'im_notify');

    $message = $arFields['MESSAGE'] ?? '';

    // Дописываем ссылку на карточку для уведомлений о лидах
    if (mb_strpos($message, 'Новый лид') !== false) {
        $leadId = (int)($arFields['PARAMS']['LEAD_ID'] ?? 0);
        if ($leadId > 0) {
            $arFields['MESSAGE'] .= "\n\nКарточка: https://crm.example.com/lead/{$leadId}/";
        }
    }

    // Не отправляем уведомления уволенным сотрудникам
    $userId = (int)($arFields['TO_USER_ID'] ?? 0);
    if ($userId > 0) {
        $rsUser = CUser::GetByID($userId);
        $user = $rsUser->Fetch();
        if ($user && $user['ACTIVE'] === 'N') {
            return false; // отменяем добавление
        }
    }
}

Возврат false из OnBeforeConfirmNotify — самый чистый способ запретить подтверждение уведомления. Например, если уведомление требует обязательного ознакомления с вложением:

<?php
AddEventHandler('im', 'OnBeforeConfirmNotify', 'blockConfirmWithoutRead');

function blockConfirmWithoutRead($notifyId, $userId)
{
    // Проверяем, что сотрудник открыл прикреплённый регламент
    $notifyId = (int)$notifyId;
    $userId   = (int)$userId;

    $rsNotify = CIMNotify::GetList(
        [],
        ['ID' => $notifyId, 'USER_ID' => $userId]
    );

    if ($notify = $rsNotify->Fetch()) {
        $tag = $notify['NOTIFY_TAG'] ?? '';

        // Уведомления с тегом REGULATION_ACK требуют явного ознакомления
        if ($tag === 'REGULATION_ACK') {
            $isRead = CUserOptions::GetOption('intranet', 'reg_read_' . $notifyId, 'N', $userId);
            if ($isRead !== 'Y') {
                return false; // подтверждение не проходит
            }
        }
    }
}

Где размещать обработчики кнопок в уведомлениях

Кнопки в уведомлениях («Принять», «Отклонить», «Перейти») обрабатываются отдельно от самих хуков мессенджера. По опыту подрядчиков, их размещают в том же bitrix/php_interface/init.php через AddEventHandler — но привязываются они к событию действия, а не к моменту добавления сообщения. Для коробочной версии это единственное разумное место: файл подключается на каждом хите, а значит обработчик всегда доступен.

Если у вас собственный модуль — обработчики логичнее держать в его include.php или module.php, чтобы не засорять глобальный init.php. В облаке прямого доступа к init.php нет — там работают только через REST и локальные приложения, где обработчики кнопок регистрируются в placement.bind.

Отдельно про CIMNotify::Add: в блогах его иногда называют устаревшим, но официальная документация dev.1c-bitrix.ru продолжает приводить его в примерах без пометки Deprecated. Мы в проектах используем его как рабочий инструмент — с параметром NOTIFY_TAG, чтобы группировать однотипные уведомления у пользователя.

Аутентификация по QR-коду и мобильные пуши: что проверить

QR-логин, пожалуй, самый быстрый индикатор того, что модуль Push&Pull у вас в порядке. Механика простая: пользователь открывает десктопную версию Битрикс24, на экране появляется QR-код, мобильное приложение сканирует его и подтверждает вход. Весь обмен идёт через тот же транспорт, что и обычные пуши — модуль Push&Pull плюс доступ к внешним сервисам Битрикс24. Если этот канал молчит, QR-код не сработает.

Администраторы обычно ищут проблему не там. Переустанавливают мобильное приложение, чистят кэш телефона, проверяют настройки на самом устройстве. А корень в серверной части. Аутентификация по QR-коду появилась с версии 21.800.0 и требует наличия модуля Push&Pull и мобильного приложения. Не выполнено хотя бы одно условие — QR-логин не заработает, и никакие манипуляции с телефоном не помогут.

Хорошая новость: QR-логин и обычные мобильные пуши ломаются по одним и тем же причинам. Проверили QR — фактически проверили весь push-транспорт.

Дальше короткий чеклист.

• Версия главного модуля — не ниже 21.800.0, иначе функциональность QR-аутентификации просто отсутствует в коде.
• Модуль Push&Pull установлен и активен — без него не работает ни один push-канал, включая QR-логин.
• Мобильное приложение Битрикс24 установлено и обновлено — устаревшие клиенты не умеют сканировать QR.
• Доступ к внешним доменам cloud-messaging.bitrix24.com со стороны сервера — именно через него уходят пуши и подтверждения QR-входа.

Последний пункт особенно важен для коробочных инсталляций в закрытом контуре. Если сервер не может достучаться до внешних сервисов Битрикс24, QR-код будет генерироваться, но подтверждение не дойдёт. В таких случаях проверяем исходящие соединения на уровне сетевого экрана — без доступа к cloud-messaging.bitrix24.com канал не поднимется.

Самые частые ошибки, из-за которых уведомления не доходят

Когда уведомления молчат, дело почти никогда не в «сломанном Битрикс24». По нашей практике, в 9 случаях из 10 виноват один из типовых промахов: отключённый модуль, отсутствие внешнего доступа с сервера, устаревшие версии модулей, кривые настройки SMTP или персональные уведомления, которые пользователь (или админ за него) просто выключил в своём профиле. Каждый из этих пунктов мы уже разбирали выше — здесь соберём их в одну картину.

Смысл этой секции — не повторить диагностику, а дать вам чек-лист «грабель»: симптом → причина → что делать. Мы регулярно видим одни и те же сценарии у магазинов на коробке и у компаний в облаке, и почти всегда проблема снимается за 10–15 минут, если знать, куда смотреть. Важно только не бросаться сразу править код: сначала исключите конфигурационные причины, и лишь потом лезьте в обработчики событий.

Обратите внимание: четыре из шести причин — конфигурационные, а не программные. Поэтому прежде чем писать обработчики на OnBeforeMessagesAdd или отлаживать CPullStack::AddByUsers, пройдите по таблице сверху вниз. В нашей практике именно порядок проверки экономит больше всего времени: сначала инфраструктура, потом код.

Подробнее об услуге: внедрение и доработка Битрикс24 CRM.