Зарегистрировать коннектор imconnector.register

Если вы разрабатываете интеграции для Битрикс24 с помощью AI-инструментов (Codex, Claude Code, Cursor), подключите MCP-сервер, чтобы ассистент использовал официальную REST-документацию.

Scope: imopenlines

Кто может выполнять метод: любой пользователь

Метод imconnector.register регистрирует пользовательский коннектор для открытых линий.

Метод работает только в контексте приложения.

Параметры метода

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

Название `тип`	Описание
ID* `string`	Уникальный идентификатор коннектора. Метод приводит значение к нижнему регистру. Рекомендуется добавлять в начало идентификатора уникальный префикс, чтобы избежать пересечения с текущими и будущими идентификаторами других коннекторов. Для формирования идентификатора используйте цифры, буквы в нижнем регистре и знак подчеркивания `_`. Символ `.` запрещен. Это значение используйте во всех методах, где требуется идентификатор коннектора — обычно в параметре `CONNECTOR`
NAME* `string`	Название коннектора в интерфейсе
ICON* `object`	Параметры основной иконки. Структура объекта подробно описана ниже
PLACEMENT_HANDLER* `string`	URL обработчика встраивания для настроек коннектора. По этому адресу Битрикс24 открывает интерфейс настройки в слайдере для пользователя. Подробнее о встраивании интерфейсов читайте в статье Механизм встройки виджетов
ICON_DISABLED `object`	Параметры иконки неактивного состояния. Структура объекта подробно описана ниже
DEL_EXTERNAL_MESSAGES `boolean`	Разрешает удалять входящие сообщения. Значение по умолчанию `true`
EDIT_INTERNAL_MESSAGES `boolean`	Разрешает редактировать сообщения операторов. Значение по умолчанию `true`
DEL_INTERNAL_MESSAGES `boolean`	Разрешает удалять сообщения операторов. Значение по умолчанию `true`
NEWSLETTER `boolean`	Разрешает использовать канал в CRM-рассылках. Значение по умолчанию `true`
NEED_SYSTEM_MESSAGES `boolean`	Разрешает отправку системных сообщений в канал. Значение по умолчанию `true`
NEED_SIGNATURE `boolean`	Добавляет подпись оператора в сообщения. Значение по умолчанию `true`
CHAT_GROUP `boolean`	Признак режима обработки чатов коннектора: `true` — группировка по `chat.id` (групповой чат), `false` — по `user.id` (чат один на один). Значение по умолчанию `false`
COMMENT `string`	Текстовое пояснение, которое отображается в блоке настроек коннектора в слайдере

Параметр ICON

Название `тип`	Описание
DATA_IMAGE* `string`	SVG-иконка в формате Data URI: строка с префиксом `data:image/svg+xml,`, после которого передается содержимое SVG, обычно URL-кодированное
COLOR `string`	Цвет фона иконки. Пример: `#69acc0`
SIZE `string`	Размер фона. Пример: `90%`
POSITION `string`	Позиция фона. Пример: `center`

Параметр ICON_DISABLED

Название `тип`	Описание
DATA_IMAGE `string`	SVG-иконка неактивного состояния в формате Data URI: строка с префиксом `data:image/svg+xml,`, после которого передается содержимое SVG, обычно URL-кодированное
COLOR `string`	Цвет фона неактивной иконки
SIZE `string`	Размер фона неактивной иконки
POSITION `string`	Позиция фона неактивной иконки

Примеры кода

Как использовать примеры в документации

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "ID": "myconnector",
            "NAME": "Мой коннектор",
            "ICON": {
              "DATA_IMAGE": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E",
              "COLOR": "#69acc0",
              "SIZE": "90%",
              "POSITION": "center"
            },
            "PLACEMENT_HANDLER": "https://example.com/connector/settings",
            "ICON_DISABLED": {
              "DATA_IMAGE": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E",
              "COLOR": "#99adb3"
            },
            "DEL_EXTERNAL_MESSAGES": true,
            "EDIT_INTERNAL_MESSAGES": true,
            "DEL_INTERNAL_MESSAGES": true,
            "NEWSLETTER": true,
            "NEED_SYSTEM_MESSAGES": true,
            "NEED_SIGNATURE": true,
            "CHAT_GROUP": false,
            "COMMENT": "Настройка канала",
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/imconnector.register

const payload = {
          ID: 'myconnector',
          NAME: 'Мой коннектор',
          ICON: {
            DATA_IMAGE: 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
            COLOR: '#69acc0',
            SIZE: '90%',
            POSITION: 'center',
          },
          PLACEMENT_HANDLER: 'https://example.com/connector/settings',
          ICON_DISABLED: {
            DATA_IMAGE: 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
            COLOR: '#99adb3',
          },
          DEL_EXTERNAL_MESSAGES: true,
          EDIT_INTERNAL_MESSAGES: true,
          DEL_INTERNAL_MESSAGES: true,
          NEWSLETTER: true,
          NEED_SYSTEM_MESSAGES: true,
          NEED_SIGNATURE: true,
          CHAT_GROUP: false,
          COMMENT: 'Настройка канала',
        };
        
        const response = await $b24.callMethod('imconnector.register', payload);
        console.log(response.getData());

$result = $b24Service->core->call(
            'imconnector.register',
            [
                'ID' => 'myconnector',
                'NAME' => 'Мой коннектор',
                'ICON' => [
                    'DATA_IMAGE' => 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
                    'COLOR' => '#69acc0',
                    'SIZE' => '90%',
                    'POSITION' => 'center',
                ],
                'PLACEMENT_HANDLER' => 'https://example.com/connector/settings',
                'ICON_DISABLED' => [
                    'DATA_IMAGE' => 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
                    'COLOR' => '#99adb3',
                ],
                'DEL_EXTERNAL_MESSAGES' => true,
                'EDIT_INTERNAL_MESSAGES' => true,
                'DEL_INTERNAL_MESSAGES' => true,
                'NEWSLETTER' => true,
                'NEED_SYSTEM_MESSAGES' => true,
                'NEED_SIGNATURE' => true,
                'CHAT_GROUP' => false,
                'COMMENT' => 'Настройка канала',
            ]
        );

BX24.callMethod(
          'imconnector.register',
          {
            ID: 'myconnector',
            NAME: 'Мой коннектор',
            ICON: {
              DATA_IMAGE: 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
              COLOR: '#69acc0',
              SIZE: '90%',
              POSITION: 'center',
            },
            PLACEMENT_HANDLER: 'https://example.com/connector/settings',
            ICON_DISABLED: {
              DATA_IMAGE: 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
              COLOR: '#99adb3',
            },
            DEL_EXTERNAL_MESSAGES: true,
            EDIT_INTERNAL_MESSAGES: true,
            DEL_INTERNAL_MESSAGES: true,
            NEWSLETTER: true,
            NEED_SYSTEM_MESSAGES: true,
            NEED_SIGNATURE: true,
            CHAT_GROUP: false,
            COMMENT: 'Настройка канала',
          },
          function(result) {
            console.log(result.data());
          }
        );

$result = CRest::call(
            'imconnector.register',
            [
                'ID' => 'myconnector',
                'NAME' => 'Мой коннектор',
                'ICON' => [
                    'DATA_IMAGE' => 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
                    'COLOR' => '#69acc0',
                    'SIZE' => '90%',
                    'POSITION' => 'center',
                ],
                'PLACEMENT_HANDLER' => 'https://example.com/connector/settings',
                'ICON_DISABLED' => [
                    'DATA_IMAGE' => 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http://www.w3.org/2000/svg%22/%3E',
                    'COLOR' => '#99adb3',
                ],
                'DEL_EXTERNAL_MESSAGES' => true,
                'EDIT_INTERNAL_MESSAGES' => true,
                'DEL_INTERNAL_MESSAGES' => true,
                'NEWSLETTER' => true,
                'NEED_SYSTEM_MESSAGES' => true,
                'NEED_SIGNATURE' => true,
                'CHAT_GROUP' => false,
                'COMMENT' => 'Настройка канала',
            ]
        );

Обработка ответа

HTTP-статус: 200

{
            "result": {
            "result": true
            },
            "time": {
            "start": 1738065600.11,
            "finish": 1738065600.38,
            "duration": 0.27,
            "processing": 0.10,
            "date_start": "2025-01-28T12:00:00+00:00",
            "date_finish": "2025-01-28T12:00:00+00:00"
            }
        }

Возвращаемые данные

Название `тип`	Описание
result `boolean`	`true`, если коннектор успешно зарегистрирован
time `time`	Информация о времени выполнения запроса

Обработка ошибок

В методе возможны два формата ошибок:

HTTP-статус: 200 с result = false

{
            "result": {
                "result": false,
                "error": "CONNECTOR_ID_REQUIRED",
                "error_description": "Не указан ID коннектора"
            }
        }

HTTP-статус: 403 для системной ошибки авторизации

{
            "error": "WRONG_AUTH_TYPE",
            "error_description": "Current authorization type is denied for this method Application context required"
        }

Название `тип`	Описание
error `string`	Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания
error_description `error_description`	Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Статус	Код	Описание	Значение
`200`	`APPLICATION_REGISTRATION_ERROR_POINT`	Ошибка регистрации приложения. В идентификаторе коннектора недопустимо использовать точку	В `ID` передан символ `.`
`200`	`CONNECTOR_ID_REQUIRED`	Не указан ID коннектора	Пустой или нестроковый `ID`
`200`	`NAME_REQUIRED`	Не указано имя коннектора	Пустой или нестроковый `NAME`
`200`	`ICON_REQUIRED`	Не указана иконка коннектора	Не передан `ICON.DATA_IMAGE` или передан не как строка
`200`	`NO_APPLICATION_ID`	Не удалось получить ID приложения	В контексте запроса не найдено приложение
`200`	`NO_PLACEMENT_HANDLER`	Не удалось получить URL обработчика встраивания	Пустой или нестроковый `PLACEMENT_HANDLER`
`200`	`APPLICATION_REGISTRATION_ERROR`	Ошибка регистрации приложения	Не удалось завершить регистрацию: данные коннектора и параметры встраивания не были сохранены
`200`	`GENERAL_CONNECTOR_REGISTRATION_ERROR`	Общая ошибка регистрации коннектора	Прочие ошибки валидации входных данных
`403`	`WRONG_AUTH_TYPE`	Current authorization type is denied for this method Application context required	Метод вызван не в контексте приложения OAuth

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	Текущий метод не разрешен для вызова с помощью batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	Превышена максимальная длина параметров, переданных в метод batch
`401`	`NO_AUTH_FOUND` Wrong authorization data	Неверный access-токен или код вебхука
`400`	`INVALID_REQUEST` Https required	Для вызовов методов требуется использовать протокол HTTPS
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	REST API доступен только на коммерческих планах
`403`	`INVALID_CREDENTIALS` Invalid request credentials	У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	Манифест недоступен
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более высоких привилегий, чем предоставляет токен вебхука
`401`	`expired_token` The access token provided has expired	Предоставленный access-токен доступа истек
`403`	`user_access_error` The user does not have access to the application	Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям
`500`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Частые кейсы

Активировать коннектор

Зарегистрировать коннектор imconnector.register

Параметры методаПараметры метода

Параметр ICONПараметр ICON

Параметр ICON_DISABLEDПараметр ICON_DISABLED

Примеры кодаПримеры кода

Обработка ответаОбработка ответа

Возвращаемые данныеВозвращаемые данные

Обработка ошибокОбработка ошибок

Возможные коды ошибокВозможные коды ошибок

Статусы и коды системных ошибокСтатусы и коды системных ошибок

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