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

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

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

Scope: imopenlines

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

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

Если вызвать метод повторно с тем же ID, метод обновит текущий коннектор.

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

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

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

Название
тип

Описание

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.

В групповом режиме CRM-трекер входящих сообщений не запускается. Из-за этого стандартная автопривязка CRM и автосоздание элементов CRM могут не выполняться для части диалогов. Если для коннектора нужен чат один на один с автопривязкой CRM, передайте false

Параметр 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 -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,
    "auth": "**put_access_token_here**"
  }' \
  https://**put_your_bitrix24_address**/rest/imconnector.register
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<{ result: boolean; error?: string; error_description?: string }>({
    method: 'imconnector.register',
    params: {
      ID: 'myconnector',
      NAME: 'My Connector',
      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,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Connector registered:', result.result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function registerConnector() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'imconnector.register',
        params: {
          ID: 'myconnector',
          NAME: 'My Connector',
          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,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Connector registered:', result.result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', registerConnector)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.imconnector.register(
        bitrix_id="myconnector",
        name="My Connector",
        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,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
$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,
    ]
);
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,
  },
  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,
    ]
);
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "imconnector.register", b24.Params{
	"ID":   "myconnector",
	"NAME": "Мой коннектор",
	"ICON": b24.Params{
		"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": b24.Params{
		"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,
})
if err != nil {
	return fmt.Errorf("imconnector.register: %w", err)
}

var item struct {
	Result bool `json:"result"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.Result)

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

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
object

Результат регистрации коннектора (подробное описание)

time
time

Информация о времени выполнения запроса

Объект result

Название
тип

Описание

result
boolean

true, если коннектор успешно зарегистрирован. Если регистрация не выполнена, возвращает false, а в объекте появляются поля error и error_description

error
string

Код ошибки. Возвращается при result = false

error_description
string

Описание ошибки. Возвращается при result = false

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

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

  1. HTTP-статус: 200 с result = false
{
    "result": {
        "result": false,
        "error": "CONNECTOR_ID_REQUIRED",
        "error_description": "Не указан ID коннектора"
    }
}
  1. 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

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут

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

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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