Открытые линии Битрикс24: подключение внешнего мессенджера через API

Открытые линии — это единая система обработки обращений из разных каналов (сайт-чат, соцсети, мессенджеры) внутри Битрикс24, где оператор видит все диалоги в одном интерфейсе независимо от источника. Если нужному вам мессенджеру или каналу связи нет готового коннектора в Маркете, его можно подключить самостоятельно через семейство методов imconnector — этот раздел REST API отличается от стандартной работы с CRM и требует понимания собственной модели сессий и статусов доставки. Разберём весь цикл: от регистрации коннектора до отправки и приёма сообщений.

Регистрация коннектора: imconnector.register

Прежде чем канал появится в списке доступных для подключения линий, коннектор нужно зарегистрировать методом imconnector.register — с указанием ID (уникальный код коннектора в рамках приложения), NAME (отображаемое имя канала, увидит администратор при настройке Открытой линии) и ICON (значок канала для интерфейса). Это разовая операция, обычно выполняемая при установке приложения.

POST /rest/1/xxxxxxxxxxxxxxxx/imconnector.register.json

{
  "ID": "custom_telegram_bot",
  "NAME": "Telegram-бот компании",
  "ICON": { "DATA_IMAGE": "data:image/svg+xml;base64,...", "SIZES": [{"SIZE": 100}] },
  "ICON_DISABLED": { "DATA_IMAGE": "data:image/svg+xml;base64,..." }
}

Активация коннектора для конкретной линии

После регистрации коннектор становится доступен в настройках Открытых линий, но администратор портала должен явно включить его для конкретной линии — это можно сделать и через интерфейс, и программно методом imconnector.activate. Ваше приложение должно предоставить интерфейс настройки (обычно виджет в разделе настроек линии), где администратор вводит специфичные для канала данные — токен Telegram-бота, ключ API WhatsApp-провайдера и подобное — эти данные приложение сохраняет у себя и использует для реальной отправки/приёма сообщений через API самого мессенджера.

Приём входящего сообщения: imconnector.send.messages

Когда пользователь пишет сообщение во внешнем мессенджере (например, в Telegram-бот компании), ваш сервис получает это сообщение через API мессенджера напрямую (webhook Telegram, например), а затем передаёт его в Открытую линию Битрикс24 вызовом imconnector.send.messages — с указанием CONNECTOR (ID коннектора), LINE (код линии), MESSAGES (массив с текстом, ID отправителя во внешней системе, временной меткой). Портал создаёт или обновляет диалог в Открытой линии и уведомляет оператора о новом сообщении в его интерфейсе.

POST /rest/1/xxxxxxxxxxxxxxxx/imconnector.send.messages.json

{
  "CONNECTOR": "custom_telegram_bot",
  "LINE": "1",
  "MESSAGES": [{
    "user": { "id": "tg_88213", "name": "Иван Петров" },
    "message": { "id": "msg_001", "text": "Здравствуйте, есть вопрос по заказу" },
    "chat": { "id": "tg_chat_88213" }
  }]
}

Отправка ответа оператора обратно во внешний мессенджер

Обратное направление устроено иначе: когда оператор отвечает в интерфейсе Открытой линии, Битрикс24 вызывает ваш HANDLER (зарегистрированный вместе с коннектором) с текстом ответа, а ваша обязанность — переслать это сообщение через API конкретного мессенджера конечному пользователю. Именно на этом этапе чаще всего теряются сообщения при плохой обработке ошибок: если API Telegram или WhatsApp временно недоступен, попытку отправки нужно повторить с retry, а не просто проглотить ошибку молча, оставив оператора в уверенности, что сообщение доставлено.

Статусы доставки: imconnector.send.status.delivery

Открытая линия ожидает подтверждения статуса доставки каждого исходящего сообщения — это отдельный вызов imconnector.send.status.delivery с ID сообщения и статусом (доставлено, прочитано, ошибка доставки). Без этого подтверждения оператор в интерфейсе Битрикс24 видит сообщение как «отправляется» бесконечно, что создаёт у него ложное впечатление, будто клиент не получил ответ, хотя фактически всё доставлено, просто ваш коннектор забыл подтвердить статус обратно на портал.

• imconnector.register — регистрация нового типа коннектора (разово при установке приложения)
• imconnector.activate — включение коннектора для конкретной линии администратором
• imconnector.send.messages — приём входящего сообщения из внешнего канала в Открытую линию
• imconnector.send.status.delivery — подтверждение статуса доставки исходящего сообщения оператора
• imconnector.connector.data.set — сохранение специфичных для канала настроек (токены, ключи API)

Модель сессии диалога и её завершение

Каждый диалог в Открытой линии существует в рамках сессии, которая заводится автоматически при первом сообщении от нового пользователя внешнего канала и закрывается либо оператором вручную, либо по таймауту бездействия, настроенному в параметрах линии. Если тот же пользователь пишет повторно после закрытия сессии, создаётся новая сессия — это стандартное поведение Открытых линий, и коннектору не нужно самому управлять жизненным циклом сессии, только корректно передавать стабильный внешний ID пользователя (chat.id или user.id), чтобы портал мог связать историю переписки одного и того же клиента между разными сессиями.

1. 1.Зарегистрировать коннектор через imconnector.register при установке приложения
2. 2.Реализовать приём настроек канала (токен бота и т.п.) через интерфейс настройки линии
3. 3.Настроить приём входящих сообщений из API мессенджера и пересылку в imconnector.send.messages
4. 4.Настроить обработку исходящих сообщений оператора через HANDLER коннектора с пересылкой во внешний API
5. 5.Обязательно подтверждать статус доставки через imconnector.send.status.delivery на каждое исходящее сообщение

Правило обязательного подтверждения статуса. Пропуск вызова imconnector.send.status.delivery — самая частая причина жалоб операторов на «зависшие» сообщения в Открытых линиях. Даже при ошибке доставки во внешнем канале нужно явно передать статус ошибки, а не просто промолчать — молчание портал интерпретирует как незавершённую отправку.

Курс школы: Вебхуки в Битрикс24 без программирования — от 9 990 ₽

Прикрепление файлов и медиа

Открытые линии поддерживают передачу файлов и изображений в структуре MESSAGES через дополнительное поле с URL вложения, но конкретный формат зависит от типа мессенджера на другом конце: голосовые сообщения, стикеры и геолокация из Telegram не имеют прямого эквивалента в модели данных Открытых линий, и коннектору приходится либо конвертировать их в текстовое описание («клиент отправил голосовое сообщение, ссылка: ...»), либо в файл, который оператор сможет скачать и прослушать отдельно. Проектируйте эту конвертацию заранее, а не после первой жалобы оператора на нечитаемое сообщение в чате.

Оператор Открытой линии не должен знать, что за интерфейсом стоит самодельный коннектор к Telegram, — если он это заметил, значит где-то в цепочке статусов доставки или конвертации медиа что-то работает не так, как в нативных каналах.

Тестирование коннектора перед подключением реальной линии

Тестируйте коннектор на отдельной тестовой Открытой линии тестового портала, с реальным тестовым ботом во внешнем мессенджере — переписывайтесь сами с обеих сторон (оператор в Битрикс24, пользователь в мессенджере) и явно проверяйте оба направления передачи, статусы доставки и поведение при потере соединения с внешним API на несколько минут. Отдельно стоит проверить поведение при одновременном общении нескольких «пользователей» мессенджера с одной линией — это выявляет ошибки в сопоставлении chat.id и session, которые не видны при тестировании одним диалогом.

Множественные линии и маршрутизация обращений

Крупная компания часто держит несколько Открытых линий — отдел продаж, служба поддержки, отдельная линия для VIP-клиентов — и один и тот же коннектор может обслуживать несколько линий одновременно, если разграничение идёт, например, по разным ботам или разным номерам WhatsApp. При регистрации коннектора для нескольких линий важно, чтобы ваш сервис хранил чёткое сопоставление «внешний идентификатор канала (номер, имя бота) → LINE в Битрикс24» и не путал сообщения между линиями — ошибка маршрутизации означает, что обращение VIP-клиента может попасть в общую очередь поддержки, а это прямой репутационный ущерб для компании-заказчика.

Работа с историей переписки и синхронизация до подключения

Частый запрос от заказчика — перенести историю переписки, накопленную во внешнем канале до момента подключения коннектора (например, все диалоги Telegram-бота за последний год). Прямой массовый импорт старых сообщений через imconnector.send.messages технически возможен, но может создать некорректную нагрузку на интерфейс операторов (заваленная лента уведомлений о «новых» сообщениях, которые на самом деле старые) и сбить статистику по времени первого ответа и другим KPI Открытых линий. Если перенос истории всё же нужен, согласуйте с заказчиком через какой отдельный механизм это делать — обычно это разовый импорт с явной пометкой «архивное сообщение», а не проведение через стандартный поток новых обращений.

Идентификация пользователя между визитами

Открытая линия связывает диалоги одного и того же внешнего пользователя в единую историю по стабильному идентификатору — для Telegram это обычно chat_id, для WhatsApp — номер телефона в международном формате. Ошибка в постоянстве этого идентификатора (например, если вы по ошибке используете внутренний ID сообщения вместо ID пользователя) приводит к тому, что каждое новое обращение создаёт нового «клиента» в CRM вместо продолжения истории с уже существующим контактом — тогда операторы теряют контекст предыдущих обращений, а в CRM плодятся дублирующиеся карточки контактов на одного и того же реального человека.

Отключение линии и деактивация коннектора

Когда администратор отключает канал (например, компания перестаёт использовать конкретный номер WhatsApp), коннектор нужно корректно деактивировать методом imconnector.deactivate и прекратить пересылку сообщений из внешнего API в Битрикс24 — иначе входящие сообщения продолжат поступать во внешний канал, но не будут доставляться операторам, и клиенты компании останутся без ответа, даже не подозревая, что линия поддержки фактически не работает. Это один из самых незаметных для внутреннего мониторинга сбоев именно потому, что технически всё «работает» — просто сообщения складываются в никуда.

Учёт часовых поясов при работе с несколькими регионами

Если внешний канал обслуживает клиентов из разных часовых поясов, а Открытая линия настроена на график работы операторов по московскому времени, коннектору стоит передавать метки времени сообщений в UTC и не пытаться самостоятельно конвертировать их под локальный часовой пояс получателя — эту логику лучше оставить на стороне Битрикс24 и настроек графика работы линии, чем дублировать в коннекторе, рискуя разойтись в трактовке смещения при переходах на летнее/зимнее время в разных странах СНГ, где правила перехода отличаются или отсутствуют вовсе.