← Назад к заметкам

Заметки

Как написать свой коннектор открытых линий

Базовая схема своего коннектора открытых линий: imconnector.register, установка приложения, входящие и исходящие сообщения.

Свой коннектор открытых линий — это приложение, а не один обработчик. Нужно зарегистрировать коннектор, принять входящие сообщения, обработать исходящие события и хранить связь внешнего клиента с CRM.

Задача

Свой коннектор нужен, когда штатных каналов не хватает или внешний сервис должен работать через открытые линии как полноценный источник обращений.

Коннектор отвечает за две стороны обмена: принимает сообщения из внешнего канала и передаёт их в открытую линию, а исходящие сообщения операторов отправляет обратно во внешний канал.

Для пользователя внутри Битрикс24 это должно выглядеть как обычный диалог открытой линии: очередь, оператор, CRM, история, статусы.

Регистрация коннектора

Начинается всё с приложения и метода imconnector.register. Коннектор регистрируется в контексте приложения. 

BX24.callMethod(
    'imconnector.register',
    {
        ID: 'custom_telegram',
        NAME: 'Custom Telegram',
        ICON: {
            DATA_IMAGE: 'data:image/png;base64,...'
        },
        ICON_DISABLED: {
            DATA_IMAGE: 'data:image/png;base64,...'
        },
        PLACEMENT_HANDLER: 'https://example.com/connector/settings.php',
    },
    function (result) {
        console.log(result.error() || result.data());
    }
);

После регистрации коннектор появляется в контакт-центре и может иметь страницу настроек. На этой странице обычно выбирают линию, токены внешнего сервиса и параметры канала.

Установка приложения

Коннектор не должен быть просто скриптом с вебхуком. Нужна нормальная установка приложения и хранение токенов. 

// install.php приложения:
// 1. зарегистрировать коннектор;
// 2. подписаться на события исходящих сообщений;
// 3. сохранить auth и параметры установки;
// 4. открыть страницу настройки коннектора.

На установке важно сохранить данные авторизации, зарегистрировать обработчики событий и подготовить страницу настроек. Без этого исходящие сообщения операторов некуда будет отправлять.

Входящие и исходящие сообщения

Входящее сообщение приходит из внешнего канала, а исходящее — из Битрикс24 через событие коннектора.

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

$payload = [
    'CONNECTOR' => 'custom_telegram',
    'LINE' => 1,
    'MESSAGES' => [
        [
            'user' => [
                'id' => 'telegram_1001',
                'name' => 'Иван',
            ],
            'message' => [
                'id' => 'tg_555',
                'text' => 'Здравствуйте',
            ],
            'chat' => [
                'id' => 'telegram_chat_1001',
            ],
        ],
    ],
];

Исходящие сообщения обрабатываются через события коннектора. Обработчик получает сообщение оператора и отправляет его во внешний сервис через его API.

CRM и идентификация клиента

Хороший коннектор сразу решает, как внешний клиент будет сопоставляться с CRM.

Если канал знает телефон или email, их лучше передавать в CRM-логику, чтобы Битрикс мог найти контакт или создать новый. Если известен только внешний ID, его нужно сохранять как техническую связку.

Для Telegram username не должен быть единственным ключом: он может измениться или отсутствовать. Лучше хранить внешний ID и отдельно проверенный телефон, если он был получен.