Виджеты в карточках CRM: зачем и как встроить
Карточка сделки в Битрикс24 — это не только поля и воронка. Это рабочее место менеджера, где он проводит большую часть времени. Если вашему приложению или интеграции нужно показать дополнительную информацию о сделке, логично встроить её прямо в карточку, а не заставлять пользователя открывать отдельный раздел. Виджеты в карточках CRM решают эту задачу: они добавляют вкладки, кнопки в панель инструментов или элементы в таймлайн, которые открывают ваш интерфейс в контексте конкретной сделки.
В 2026 году механизм встройки виджетов в Битрикс24 работает через метод placement.bind. Вы регистрируете обработчик для конкретной точки встраивания, и Битрикс24 отправляет на него POST-запрос с контекстом вызова. Для карточек CRM доступно несколько точек: вкладка в карточке (CRM_DEAL_DETAIL_TAB), элемент в таймлайне (CRM_DEAL_DETAIL_ACTIVITY), кнопка в панели инструментов (CRM_DEAL_DETAIL_TOOLBAR) и другие. Выбор точки зависит от того, что именно вы хотите показать пользователю.
В этой статье — полное руководство по виджетам в карточках CRM: какие точки размещения существуют, как зарегистрировать обработчик, как обработать контекст вызова, как взаимодействовать с интерфейсом Битрикс24 из виджета и какие ошибки чаще всего допускают. Если нужна кастомизация Битрикс24 под ваш процесс — поможем.
Зачем нужны виджеты в карточках
Виджеты в карточках CRM дают несколько преимуществ по сравнению с отдельным приложением или внешним интерфейсом.
Функционал там, где он нужен
Пользователь уже находится в сделке. Ему не нужно переключаться на другой раздел, чтобы увидеть дополнительную информацию или выполнить действие.
Проще программировать
Не нужно создавать свой интерфейс со списком сделок. Пользователь уже нашёл нужную сделку в CRM. Вы сосредотачиваетесь только на уникальном функционале.
Целевой трафик
Если вы разрабатываете тиражное приложение, витрина Маркета будет предлагать его клиентам в тех местах встройки, которые вы используете. Конверсия в установки выше.
Бесшовный опыт
Виджет открывается внутри карточки, в слайдере или на вкладке. Пользователь не покидает привычный интерфейс.
Точки размещения
Для карточек CRM доступно несколько точек встраивания. Код точки передаётся в параметре PLACEMENT при регистрации обработчика.
| Точка | Где отображается | Что передаёт в контексте | Когда использовать |
|---|---|---|---|
CRM_DEAL_DETAIL_TAB | Дополнительная вкладка в карточке сделки | ID сделки | Для отображения информации или действий, связанных со сделкой |
CRM_DEAL_DETAIL_ACTIVITY | Элемент в таймлайне сделки | ID сделки и идентификаторы записи таймлайна | Для добавления действий в историю (звонки, встречи, комментарии) |
CRM_DEAL_DETAIL_TOOLBAR | Кнопка в панели инструментов карточки | ID сделки | Для быстрых действий (например, «Отправить в外部 систему») |
CRM_DEAL_DETAIL_MENU | Пункт в меню карточки | ID сделки | Для дополнительных действий, которые не нужно выносить на видное место |
Аналогичные точки существуют для лидов (CRM_LEAD_DETAIL_TAB и т.д.), контактов (CRM_CONTACT_DETAIL_TAB), компаний (CRM_COMPANY_DETAIL_TAB) и других сущностей. Выбор точки зависит от сценария: если информация важна и должна быть на виду — вкладка; если это действие — кнопка или пункт меню; если это запись в историю — таймлайн.
💡 Важно
Вкладка в карточке — самая заметная точка. Но если виджет нужен только для редкого действия, лучше использовать кнопку или пункт меню, чтобы не перегружать интерфейс.
Регистрация через placement.bind
Чтобы виджет появился в карточке, приложение должно зарегистрировать обработчик. Это делается методом placement.bind .
Что нужно передать
- PLACEMENT. Код точки встраивания (например,
CRM_DEAL_DETAIL_TAB); - HANDLER. URL, на который Битрикс24 будет отправлять POST-запрос. Адрес должен быть доступен из внешней сети ;
- TITLE. Название виджета (например, «Поставки по сделке»). Отображается на вкладке или кнопке.
Пример запроса:
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"PLACEMENT": "CRM_DEAL_DETAIL_TAB",
"HANDLER": "https://your-domain.com/widgets/deal-tab-handler.php",
"TITLE": "Поставки по сделке",
"auth": "**access_token**"
}' \
https://**your-bitrix24**/rest/placement.bind
Регистрацию обычно выполняют во время установки приложения. Если приложение уже установлено, можно зарегистрировать обработчик вручную или через скрипт .
Для отмены регистрации используется метод placement.unbind с теми же параметрами. Для получения списка зарегистрированных виджетов — placement.get.
Контекст вызова
Когда пользователь открывает виджет, Битрикс24 отправляет POST-запрос на адрес обработчика. В запросе передаются авторизационные данные и контекст вызова — PLACEMENT_OPTIONS.
Что приходит в запросе
- DOMAIN. Домен портала;
- AUTH_ID. Токен авторизации для вызова REST API от лица пользователя;
- PLACEMENT. Код точки встраивания;
- PLACEMENT_OPTIONS. JSON-строка с контекстом вызова.
Для карточек CRM в PLACEMENT_OPTIONS обычно приходит ID — идентификатор сущности, в карточке которой открыт виджет. Например, для сделки это ID сделки.
Пример разбора контекста в обработчике:
$placementOptions = json_decode($_POST['PLACEMENT_OPTIONS'], true);
$dealId = $placementOptions['ID'];
Зная ID сделки, обработчик может вызвать REST API, чтобы получить данные из карточки, или выполнить действие, связанное с этой сделкой.
💡 Важно
Всегда проверяйте, что ID пришёл и является числом. Если контекст пустой или некорректный, виджет не сможет работать.
Взаимодействие с UI
Из виджета можно управлять интерфейсом Битрикс24. Это позволяет открывать стандартные карточки, слайдеры и выполнять другие действия без перезагрузки страницы.
Основные методы
- openPath. Открывает стандартный слайдер Битрикс24 (например, карточку контакта или задачу);
- openApplication. Открывает другое приложение или интерфейс внутри слайдера. Удобно для форм настроек или детальных карточек.
Эти методы вызываются из JavaScript внутри фрейма виджета. Они позволяют сделать опыт пользователя бесшовным: он остаётся в карточке сделки, но может открыть связанные данные.
Прямые вызовы REST API
Из виджета можно напрямую вызывать REST-методы Битрикс24, используя токен авторизации, который пришёл в запросе. Это позволяет получать и изменять данные без дополнительных запросов к вашему серверу.
Права и доступность
Виджет увидят не все пользователи. Есть два условия :
- Скоупы приложения. Приложению нужен скоуп
placementдля регистрации виджета. Если виджет работает с данными CRM, нужен также скоупcrm; - Доступ к приложению. Виджет видят только те сотрудники, которым открыт доступ к приложению. Битрикс24 проверяет доступ при каждом выводе виджета.
Адрес обработчика должен быть доступен из внешней сети. Локальные адреса и самоподписанные сертификаты не подойдут.
Также убедитесь, что ваш веб-сервер разрешает показ во фреймах. Без этого виджет не отобразится.
Типичные ошибки
1. Обработчик недоступен извне
URL обработчика — localhost или локальный домен. Битрикс24 не может до него достучаться, виджет не открывается.
2. Нет скоупа placement
Приложение не имеет права регистрировать виджеты. placement.bind возвращает ошибку.
3. Неверный разбор контекста
PLACEMENT_OPTIONS не декодируется или ID не извлекается. Виджет не знает, в какой сделке открыт.
4. Нет проверки прав
Виджет показывает данные, которые пользователь не должен видеть. Нужно проверять права при каждом запросе.
5. Фрейм запрещён
Веб-сервер отдаёт заголовок X-Frame-Options: DENY. Виджет не отображается.
Наши рекомендации
Что вы получаете, заказывая настройку у нас
- Регистрацию виджета — через
placement.bind; - Обработчик — с разбором контекста и вызовом API;
- Интерфейс — вкладка, кнопка или таймлайн;
- Проверку доступности — из внешней сети и во фрейме;
- Обучение — как поддерживать виджет;
- Поддержку — если что-то пойдёт не так.
📌 Итоговый вывод
Виджеты в карточках CRM — это способ дать пользователю нужный функционал там, где он работает.
Что нужно знать:
- Зачем: функционал в контексте, проще программировать, целевой трафик, бесшовный опыт;
- Точки размещения: вкладка (
CRM_DEAL_DETAIL_TAB), таймлайн (CRM_DEAL_DETAIL_ACTIVITY), панель инструментов (CRM_DEAL_DETAIL_TOOLBAR), меню; - Регистрация:
placement.bindс параметрамиPLACEMENT,HANDLER,TITLE; - Контекст:
PLACEMENT_OPTIONSсодержитIDсущности; - UI:
openPathиopenApplicationдля навигации; - Права: скоуп
placement, доступ к приложению, доступность извне; - Ошибки: недоступный обработчик, нет скоупа, неверный контекст, нет проверки прав, фрейм запрещён.
Также рекомендуем: Кастомизация, Кастомные роботы, API, все статьи.