Уведомления в Битрикс24 — это отдельный от чата канал: они попадают в «колокольчик» и в центр уведомлений, а не в ленту диалога. За их отправку через REST отвечают методы im.notify.personal.add и im.notify.system.add.
Уведомления против сообщений в чат
Важно не путать два канала. Сообщение (im.message.add) создаёт запись в диалоге. Уведомление появляется в центре уведомлений (иконка колокольчика) и не привязано к переписке — это скорее «системный сигнал» пользователю.
| Признак | Сообщение | Уведомление |
|---|---|---|
| Метод | im.message.add | im.notify.* |
| Где видно | чат/диалог | центр уведомлений |
| Ответ пользователя | да, в диалоге | обычно нет (или кнопки) |
Персональные и системные
Есть два типа уведомлений:
- Персональное (
im.notify.personal.add) — обычное уведомление, на которое можно настроить ответ или кнопки. Приходит от имени приложения/бота. - Системное (
im.notify.system.add) — служебное уведомление без возможности ответа, помечается как автоматическое.
Оба метода относятся к скоупу im. На практике для приложений и ботов чаще применяют персональные уведомления, потому что они допускают интерактивные кнопки.
Отправка уведомления
Обязательные параметры — получатель и текст:
POST /rest/1/xxxx/im.notify.system.add.json
{"USER_ID":17,"MESSAGE":"Заказ №5012 оплачен","MESSAGE_OUT":"Заказ №5012 оплачен","TAG":"order-5012-paid"}
Разберём поля:
| Поле | Назначение |
|---|---|
USER_ID | получатель уведомления |
MESSAGE | текст с BB-кодом (для веб) |
MESSAGE_OUT | упрощённый текст для push/почты |
TAG | метка для последующего удаления/группировки |
SUB_TAG | дополнительная метка группы |
ATTACH | карточка-вложение |
MESSAGE_OUT стоит заполнять без BB-кода — именно он уходит в мобильный push и e-mail, где разметка не нужна.
Теги и снятие уведомлений
Поле TAG — ключевой инструмент управления. По нему можно снять уведомление, когда оно потеряло смысл:
POST /rest/1/xxxx/im.notify.delete.json
{"TAG":"order-5012-paid"}
Так реализуют «живые» уведомления: пришло напоминание об оплате счёта с тегом invoice-88, счёт оплатили — вызвали im.notify.delete с тем же тегом, и уведомление исчезает у пользователя. Удалять можно и по ID уведомления, полученному в ответе на отправку.
Кнопки и интерактив
Персональное уведомление может нести кнопки через ATTACH с блоком кнопок или через параметр клавиатуры (в контексте бота). Пример карточки:
{"USER_ID":17,"MESSAGE":"Согласуйте отпуск сотрудника","ATTACH":[{"BLOCKS":[{"MESSAGE":"Иванов И., 5 дней"},{"LINK":{"NAME":"Открыть заявку","LINK":"https://portal.bitrix24.ru/..."}}]}]}
imbot.register).Где применять
Уведомления закрывают широкий класс задач автоматизации:
- Статусы процессов. Оплата заказа, смена стадии сделки, готовность документа — короткий сигнал ответственному.
- Напоминания. Приближение дедлайна, просроченная задача, необходимость согласования.
- Алерты систем. Мониторинг сервера или интеграции шлёт предупреждение нужному сотруднику с тегом инцидента и снимает его при восстановлении.
Во всех случаях связка «отправить с тегом → снять по тегу» делает центр уведомлений актуальным, а не превращает его в свалку устаревших сообщений.
Итог
Уведомления (im.notify.personal.add, im.notify.system.add) — правильный канал для фоновых сигналов, отдельный от чата. Заполняйте MESSAGE_OUT для push, используйте осмысленные TAG и снимайте неактуальное через im.notify.delete.
Мы выстраиваем такие оповещения как часть автоматизации бизнес-процессов: события внешних систем и портала превращаются в аккуратные, самоочищающиеся уведомления нужным людям. Спроектируем логику и подключим к вашим источникам данных.
Частые вопросы
Чем уведомление отличается от сообщения в чат?
Сообщение появляется в диалоге и предполагает переписку, уведомление — в центре уведомлений (колокольчик) как служебный сигнал. Для фоновых оповещений уместнее уведомления.
Когда использовать system, а когда personal?
im.notify.system.add — служебное уведомление без ответа. im.notify.personal.add допускает интерактив и кнопки. Для приложений и ботов чаще берут personal.
Зачем нужно поле MESSAGE_OUT?
Это упрощённый текст без BB-кода для мобильного push и e-mail. MESSAGE отображается в веб-интерфейсе, MESSAGE_OUT — во внешних каналах доставки.
Как убрать уведомление, когда оно неактуально?
Отправляйте уведомление с осмысленным TAG, а затем вызывайте im.notify.delete с тем же тегом. Уведомление исчезнет у пользователя без хранения числового ID.
Можно ли слать уведомления через входящий вебхук?
Да, текстовые и со ссылками — можно. Но обрабатывать нажатия интерактивных кнопок способен только зарегистрированный чат-бот, поэтому для интерактива нужен imbot.register.
Сколько получателей можно указать за раз?
Один вызов адресован одному USER_ID. Для рассылки нескольким сотрудникам делайте несколько вызовов, желательно объединив их в batch, чтобы уложиться в лимиты.
Поддерживают ли уведомления вложения?
Да, через параметр ATTACH можно добавить карточку с полями и ссылкой. Это удобно для уведомлений о заявках и документах.
Какой скоуп нужен для уведомлений?
Скоуп im. Его нужно включить в правах вебхука или приложения, иначе методы im.notify.* вернут ошибку доступа.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.