im.notify.system.add: системные уведомления сотрудникам в Битрикс24

im.notify.system.add - метод REST API Битрикс24, который отправляет сотруднику системное уведомление в мессенджер портала: без открытия диалога с ботом и без ответа от адресата, просто короткое сообщение с иконкой самой платформы. Я использую его, когда нужно молча дёрнуть менеджера: пришла заявка, изменился статус доставки, упал платёж на сайте. Ниже разбираю, как получить права на метод, собрать запрос и не словить типичные грабли с дублями уведомлений.

Что делает im.notify.system.add и чем отличается от personal.add

im.notify.system.add и im.notify.personal.add относятся к одной группе методов im.notify и оба кладут сообщение не в обычный чат, а во вкладку уведомлений мессенджера Битрикс24. Разница в том, как это выглядит для сотрудника.

personal.add подписывает уведомление именем и аватаром вызвавшего приложения - сотрудник видит, что сообщение прислала конкретная интеграция. Это уместно, если хочется, чтобы уведомление воспринималось как часть вашего сервиса, например бота техподдержки.

system.add выглядит иначе: серая системная иконка, без названия приложения, ровно так же, как штатные оповещения самого Битрикс24 про упоминание в задаче или новый комментарий. Из-за такого визуального веса Битрикс24 не раздаёт этот метод всем подряд, и об этом стоит знать до того, как начнёте проектировать интеграцию.

Какие права нужны и как настроить вебхук

По моей практике im.notify.system.add рассчитан на локальные интеграции конкретного портала, а не на приложения, которые ставят себе чужие компании из маркетплейса. Смысл ограничения понятен: системная иконка выглядит как официальное сообщение платформы, и раздавать такую возможность внешним разработчикам массово рискованно.

Для одной задачи вроде уведомлений о заказах хватает входящего вебхука, без публикации отдельного приложения.

1. Зайдите в разделе «Разработчикам», откройте «Другое» и создайте входящий вебхук.
2. Отметьте права, которые открывают доступ к разделу уведомлений (im) - без этой галки метод ответит ошибкой доступа.
3. Скопируйте готовый URL вида https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/ - это базовый адрес для вызова im.notify.system.add.

Отдельно проверьте, что USER_ID, на который летит уведомление, принадлежит активному сотруднику с лицензией, а не уволенному или деактивированному пользователю - в этом случае запрос вернёт успех, а сообщение никуда не долетит.

Структура запроса: USER_ID, MESSAGE, TAG и SUB_TAG

У метода четыре параметра, с которыми реально работаешь на практике.

• USER_ID - обязательный, целочисленный id одного получателя: «Идентификатор пользователя-получателя уведомления». Массив метод не принимает, при отсутствующем или нулевом значении приходит ошибка USER_ID_EMPTY, поэтому на нескольких сотрудников делается несколько вызовов.
• MESSAGE - обязательный текст уведомления, поддерживает BB-коды вида [B]жирный текст[/B], [I]курсив[/I], [URL=адрес]текст ссылки[/URL], перенос строки через \n.
• TAG - необязательная метка и единственный механизм против дублей: «Уникальный тег уведомления в рамках приложения. При добавлении уведомления с существующим тегом другие уведомления будут удалены». То есть повторный вызов с тем же TAG не обновляет прежнее сообщение, а удаляет старые уведомления с этой меткой и оставляет новое. Метку я привязываю к сущности, например order_482 или ticket_15.
• SUB_TAG - необязательный «Дополнительный тег уведомления без проверки уникальности», на дедупликацию он не влияет. При вызове через вебхук TAG и SUB_TAG передаются вместе с CLIENT_ID.

Есть ещё необязательный параметр ATTACH для более сложной вёрстки уведомления с дополнительными строками и ссылками. Схема у него вложенная, и я сознательно не привожу тут пример JSON, который выглядит правдоподобно, но может разойтись с актуальной документацией - для статуса заказа или новой заявки хватает обычного MESSAGE с BB-кодами, в большинстве своих интеграций я обхожусь без ATTACH.

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

Если по заказу должно оставаться одно актуальное сообщение, а не десяток одинаковых с текстом «статус изменился», я держу один и тот же TAG на всё время жизни заказа: «При добавлении уведомления с существующим тегом другие уведомления будут удалены», то есть прежние уведомления с этой меткой Битрикс24 убирает сам. Если же нужна именно цепочка сообщений по стадиям (заказ собран, передан в СДЭК, доставлен), TAG на каждую стадию должен быть свой: order_482_collected, order_482_cdek, order_482_delivered. На SUB_TAG эту логику не переложить, уникальность он не проверяет.

Пример запроса на PHP и curl к im.notify.system.add

Проще всего проверить метод curl-ом прямо из терминала.

curl -X POST "https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/im.notify.system.add" \
  -H "Content-Type: application/json" \
  -d '{"USER_ID": 4, "MESSAGE": "[B]Заказ 482[/B] оплачен через Т-Банк, можно собирать", "TAG": "order_482", "SUB_TAG": "paid", "CLIENT_ID": "shop_orders"}'

В боевом коде обычно оборачиваю вызов в функцию на PHP, которая уже стоит в обработчике заказа или в вебхуке от платёжной системы.

<?php

$webhookUrl = 'https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/im.notify.system.add';

$params = [
    'USER_ID'   => 4,
    'MESSAGE'   => '[B]Заказ 482[/B] передан в СДЭК, трек появится в течение часа',
    'TAG'       => 'order_482',
    'SUB_TAG'   => 'cdek',
    'CLIENT_ID' => 'shop_orders',
];

$ch = curl_init($webhookUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($response['error'])) {
    error_log('Bitrix24 notify error: ' . $response['error_description']);
}

Частые ошибки при вызове метода

• Вебхук создан без прав на раздел уведомлений - запрос возвращает ошибку доступа вместо результата, лечится пересозданием вебхука с нужной галкой.
• Метод вызывают из приложения, установленного на чужой портал через маркетплейс - system.add для такого сценария не предназначен, нужен personal.add или обычное сообщение бота в чат.
• USER_ID берут из старой выгрузки сотрудников без проверки, что человек всё ещё активен на портале.
• MESSAGE отправляют вообще без TAG, из-за чего при каждом срабатывании обработчика заказа сотруднику прилетает отдельное сообщение, и вкладка уведомлений превращается в мусор.
• При вызове через вебхук не передают CLIENT_ID вместе с TAG и SUB_TAG - в документации он описан так: «Идентификатор приложения. Параметр обязателен только при вызове через вебхук: передавайте его вместе с TAG и SUB_TAG».
• Забывают заголовок Content-Type при отправке JSON-телом - Битрикс24 не может разобрать тело запроса и возвращает ошибку формата.

Сравнение способов уведомить сотрудника в Битрикс24

Где я использую это на практике

Чаще всего im.notify.system.add встраивается в цепочку, где Битрикс24 не единственная система. Например, оплата приходит через Т‑Банк или заказ оформлен в WooCommerce, а дальше нужно дёрнуть менеджера в CRM, не открывая отдельный интерфейс уведомлений вручную.

Такую связку я обычно собираю через автоматизацией процессов в n8n: вебхук от платёжной системы или от СДЭК прилетает в workflow, там же проверяются и обогащаются данные, а на последнем шаге HTTP-запрос дёргает im.notify.system.add с нужным TAG под конкретный заказ.

Второй частый сценарий - Telegram-бот на aiogram, который принимает заявку от клиента и параллельно кладёт системное уведомление ответственному менеджеру в Битрикс24, чтобы тот не сидел одновременно в двух интерфейсах. Третий - лид с формы на Tilda, откуда вебхук летит на тот же обработчик, что и заказ из магазина.

Если такую цепочку нужно собрать с нуля, вебхук, обработку статусов, TAG и SUB_TAG под сущности, отправку в n8n, у меня автоматизация в n8n стоит от 25 000 ₽, а Telegram-бот на aiogram, который дёргает тот же im.notify.system.add при новых заявках, от 30 000 ₽.

Условия и возможности Битрикс24 меняются, поэтому перед запуском я уточняю их у самого сервиса.

Частые вопросы

Можно ли отправить системное уведомление сразу нескольким сотрудникам?

Нет, в USER_ID передаётся ровно один id: в документации параметр описан как «Идентификатор пользователя-получателя уведомления» с типом integer. Чтобы уведомить трёх сотрудников, метод вызывается три раза, по одному запросу на получателя, текст при этом можно держать один и тот же.

Чем это отличается от обычного сообщения в чат от бота?

Сообщение в чат идёт в обычный диалог с ботом, сотрудник может на него ответить, и переписка сохраняется в истории чата. im.notify.system.add кладёт сообщение в отдельную вкладку уведомлений без возможности ответить, и воспринимается это как системное оповещение платформы, а не как переписка.

Запрос вернул успешный результат, но сотрудник не видит уведомление, в чём дело?

Первым делом проверяю, активен ли пользователь с указанным USER_ID и есть ли у него лицензия на портале - уволенным или деактивированным сотрудникам уведомления не долетают, хотя метод формально отвечает успехом. Дальше смотрю, не отключил ли сам сотрудник уведомления в настройках, и тестирую вызов на своём собственном id, прежде чем разворачивать интеграцию на всех.

Работает ли im.notify.system.add в приложениях из маркетплейса?

По моей практике нет - метод рассчитан на локальные вебхуки и внутренние интеграции конкретного портала. Приложению, которое устанавливают на чужие порталы через маркетплейс, для уведомлений стоит использовать im.notify.personal.add или обычное сообщение бота в чат, а системную иконку Битрикс24 оставляет для собственных встроенных оповещений и локальных интеграций.