Страница настройки коннектора SETTING_CONNECTOR

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

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

Scope: imopenlines

Виджет выводит интерфейс приложения на странице настройки пользовательского коннектора открытых линий. Здесь пользователь подключает свой канал связи: вводит логин внешнего сервиса, выбирает аккаунт или подтверждает доступ.

Обработчик подключается не методом placement.bind, а параметром PLACEMENT_HANDLER метода imconnector.register. Битрикс24 сам создает привязку к точке, когда регистрирует коннектор.

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

Куда встраивается виджет

Код точки встраивания	Место
`SETTING_CONNECTOR`	Страница настройки пользовательского коннектора открытых линий

Где находится в интерфейсе

Откройте контакт-центр по адресу /contact_center/ и нажмите на плитку своего коннектора. В открывшемся слайдере нажмите Подключить и выберите открытую линию. Интерфейс приложения выводится между шапкой коннектора и блоком Настройки открытой линии и прав доступа.

Виджет на странице настройки коннектора

Плитка коннектора появляется в контакт-центре сразу после вызова imconnector.register — название и иконку берут из параметров NAME и ICON.

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

Данные передаются POST-запросом: часть параметров — в query-строке адреса обработчика, остальные — в теле запроса

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => ru
            [APP_SID] => 0123456789abcdef0123456789abcdef
            [AUTH_ID] => 6061e72600631fcd00005a4b00000001f0f1076700000000f69dd5fc643d9ce2fdbc1
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 50e00aa340631fcd00005a4b00000001f0f1071111116580a5b83c2de639ef28c12
            [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
            [APPLICATION_TOKEN] => 5b2f8c1d7e3a9046b8c5d2f1a7e3b904
            [APPLICATION_SCOPE] => imopenlines,placement
            [member_id] => da45a03b265edd8787f8a258d793cc5d
            [status] => L
            [PLACEMENT] => SETTING_CONNECTOR
            [PLACEMENT_OPTIONS] => {"CONNECTOR":"my_connector","LINE":"17","STATUS":false,"ACTIVE_STATUS":true,"CONNECTION_STATUS":false,"REGISTER_STATUS":false,"ERROR_STATUS":false,"URI":"\/contact_center\/connector\/?ID=my_connector&IFRAME=Y&IFRAME_TYPE=SIDE_SLIDER"}
        )

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

Параметры в query-строке адреса обработчика

Параметр `тип`	Описание
DOMAIN* `string`	Адрес Битрикс24, на котором был вызван обработчик виджета
PROTOCOL* `string`	Защищенный или незащищенный протокол HTTP: `0` — HTTP `1` — HTTPS
LANG* `string`	Язык интерфейса пользователя Битрикс24, который вызвал виджет. Вы можете локализовать язык интерфейса в своем виджете, ориентируясь на это значение
APP_SID* `string`	Идентификатор сессии приложения. Битрикс24 создает его заново при каждой отрисовке виджета и использует, чтобы связать js-библиотеку с окружением приложения

Параметры в теле POST-запроса

Параметр `тип`	Описание
AUTH_ID `string`	Авторизационный токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для вызовов REST API от лица этого пользователя
AUTH_EXPIRES `integer`	Время в секундах, после которого авторизационный токен станет неактуальным
REFRESH_ID `string`	Refresh-токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для обновления авторизационного токена от лица этого пользователя
SERVER_ENDPOINT* `string`	Адрес сервера авторизации Битрикс24, необходимый для обновления токенов OAuth 2
APPLICATION_TOKEN* `string`	Токен приложения. То же значение приходит в параметре `application_token` при вызове обработчиков событий. По нему обработчик виджета может проверить, что запрос пришел от Битрикс24
APPLICATION_SCOPE* `string`	Список скоупов, выданных приложению, через запятую. Показывает, какие методы REST API доступны с полученным авторизационным токеном
member_id* `string`	Уникальный строковый идентификатор Битрикс24, на котором был вызван обработчик виджета
status `string`	Тип приложения, зарегистрировавшего обработчик данного виджета. Принимает значения: `L` — локальное приложение `F` — бесплатное тиражное приложение `S` — подписное тиражное приложение
PLACEMENT* `string`	Код точки встраивания. Вы можете использовать один и тот же URL обработчика для всех своих виджетов. Значение, которое Битрикс24 будет сообщать в параметре `PLACEMENT`, поможет определить, из какой именно точки встраивания был вызван ваш обработчик в каждом конкретном случае
PLACEMENT_OPTIONS `string`	Дополнительные данные в виде JSON-строки, определяющие контекст выполнения виджета. Например, это может быть массив, содержащий числовой идентификатор элемента CRM, в карточке которого был вызван обработчик виджета, и так далее. Параметр `PLACEMENT_OPTIONS` вместе с параметром `PLACEMENT` позволяет точно определить, для какой именно точки встраивания и какого объекта был вызван обработчик виджета

Битрикс24 добавляет в PLACEMENT_OPTIONS ключ URI — путь с query-строкой той страницы, с которой открыт виджет. Он приходит для любой точки встраивания, вместе с ее собственными ключами. Ключа не будет, если браузер не передал заголовок Referer или виджет открыт со страницы другого домена.

Как разобрать контекст вызова

PLACEMENT_OPTIONS приходит JSON-строкой, а не массивом: перед использованием разберите ее на стороне обработчика. Состав ключей у каждой точки свой и описан в разделе PLACEMENT_OPTIONS этой страницы.

$placement = $_POST['PLACEMENT'] ?? '';
        $options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);

options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")

В B24JsSDK разбирать строку не нужно: свойство $b24.placement.options возвращает готовый объект, а $b24.placement.placement — код точки встраивания.

Что должен вернуть обработчик

Обработчик отвечает обычной HTML-страницей — Битрикс24 показывает ее во фрейме на месте виджета. Страница должна разрешать встраивание: если сервер приложения отдает заголовки X-Frame-Options или Content-Security-Policy, запрещающие фрейм, на месте виджета останется пустая область. Как это исправить, описано в статье Сайт не разрешает подключение.

PLACEMENT_OPTIONS

Значение PLACEMENT_OPTIONS передается как JSON-строка. В ней приходит и адресация вызова — какой коннектор на какой линии настраивают, — и текущее состояние этого коннектора.

Ключ `тип`	Описание
CONNECTOR `string`	Идентификатор коннектора — значение `ID`, с которым приложение зарегистрировало коннектор методом imconnector.register
LINE `string`	Идентификатор открытой линии, для которой открыта страница настройки. Настройки линии вернет метод imopenlines.config.get
ACTIVE_STATUS `boolean`	Коннектор включен на этой линии. Значение меняет метод imconnector.activate
CONNECTION_STATUS `boolean`	Соединение с внешним сервисом подтверждено
REGISTER_STATUS `boolean`	Канал во внешнем сервисе зарегистрирован. Оба признака приложение поднимает методом imconnector.connector.data.set, когда сохраняет настройки канала
ERROR_STATUS `boolean`	У коннектора есть ошибка. Признак выставляет метод `imconnector.set.error`
STATUS `boolean`	Итоговый статус: `true`, когда коннектор включен, соединение и регистрация подтверждены, а ошибок нет. То же значение возвращает метод imconnector.status

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

Как подключить обработчик

Отдельного вызова placement.bind для этой точки не нужно. Адрес обработчика передается один раз — при регистрации коннектора:

в PLACEMENT_HANDLER метода imconnector.register укажите адрес страницы настройки
Битрикс24 создаст привязку к точке SETTING_CONNECTOR и свяжет ее с коннектором
чтобы поменять адрес, вызовите imconnector.register повторно с тем же ID

Параметры OPTIONS точка не поддерживает: способа передать их при регистрации коннектора нет.

Типовые ошибки

Ошибка	Как решить
Обработчик привязали методом `placement.bind`	Метод примет код `SETTING_CONNECTOR` и создаст привязку, но на странице настройки она не появится. Битрикс24 показывает ту привязку, которую создал сам при регистрации коннектора
Страницу настройки ищут до подключения линии	Пока в слайдере коннектора не нажали Подключить и не выбрали открытую линию, интерфейса приложения на странице нет
Идентификатор коннектора не совпадает с сохраненным	Метод `imconnector.register` приводит `ID` к нижнему регистру, а в `PLACEMENT_OPTIONS` приходит уже приведенное значение. Сравнивайте значения в одном регистре

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

Была ли статья полезна?

Плитка в контакт-центре

Обзор точек встраивания

Страница настройки коннектора SETTING_CONNECTOR

Куда встраивается виджетКуда встраивается виджет

Где находится в интерфейсеГде находится в интерфейсе

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

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

Как подключить обработчикКак подключить обработчик

Типовые ошибкиТиповые ошибки

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