Открытые линии Битрикс24: обзор методов и событий

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

• Открытые линии — настроить линию, очередь операторов и обработать диалог
• Коннекторы открытых линий — подключить собственный канал связи
• Статистика открытых линий — выгрузить показатели для отчетов во внешней системе

Для собственного канала связи нужны первые две группы: коннектор регистрирует канал, а открытые линии обрабатывают обращения из него. Открытую линию другого Битрикс24 подключают без своего коннектора.

Быстрый переход: все методы и события

Пользовательская документация: Контакт-центр в Битрикс24

Связь с другими объектамиСвязь с другими объектами

Открытые линии связаны с чатами и сессиями, участниками диалога, сообщениями и чат-ботами, CRM, универсальными списками и данными статистики.

Чат. Обращение клиента обрабатывается в чате открытой линии. Чат связывает сообщения, операторов и сессии, а его идентификатор CHAT_ID — сквозной параметр методов раздела, начиная с группы Диалоги открытых линий.

Сессия. Внутри чата обращение проходит как сессия и получает свой SESSION_ID. Чтобы запустить сессию, прочитать историю, подключить оператора и переключить режим, используйте методы той же группы Диалоги открытых линий.

Оператор. Линия распределяет обращения между операторами из очереди. Очередь настраивают методы группы Открытые линии, а действия оператора в активном диалоге выполняют методы группы Операторы открытых линий от имени авторизованного пользователя. Получателя перевода в этой группе принимает метод imopenlines.operator.transfer: сотрудника — в USER_ID, линию, в очередь которой уйдет диалог, — в QUEUE_ID.

Внешний пользователь. Клиент внешнего канала связан с диалогом через USER_CODE. По этому коду методы группы Диалоги открытых линий находят чат и сессию клиента.

Сообщение. Переписка клиента и оператора связана с чатом и сессией. Отправить сообщение в чат, привязанный к объекту CRM, можно методом imopenlines.crm.message.add, сохранить быстрый ответ — методом imopenlines.message.quick.save. Чтобы реагировать на добавление, изменение и удаление сообщений, используйте события открытых линий.

Чат-бот. Бот отправляет сообщения, переключает диалог на оператора и завершает сессию методами группы Чат-боты в открытых линиях.

CRM. Чат открытой линии привязывается к объекту CRM — лиду, сделке, контакту или компании. Методы группы Чаты CRM находят такие чаты и управляют их участниками: тип объекта они принимают в CRM_ENTITY_TYPE, идентификатор — в CRM_ENTITY. Метод imopenlines.crm.lead.create создает лид по итогам диалога.

Универсальные списки. Быстрые ответы линии хранятся в универсальном списке. Его идентификатор передается в параметре QUICK_ANSWERS_IBLOCK_ID. Прочитать значение можно методом imopenlines.config.get, а задать при создании или обновлении линии — методами imopenlines.config.add и imopenlines.config.update.

Данные статистики. Накопленные показатели связаны с сессиями, линиями и операторами. Методы группы Статистика открытых линий ограничивают выборку по линии и оператору, а отдельные сессии детализируют по sessionId.

Ключевые идентификаторыКлючевые идентификаторы

Идентификатор	Описание	Пример	Как получить
CHAT_ID	Идентификатор чата открытой линии. Нужен, чтобы работать с диалогом, сообщениями, операторами и чат-ботами	1763	imopenlines.session.open по коду USER_CODE — в поле chatId, imopenlines.dialog.get — в поле id
SESSION_ID	Идентификатор сессии внутри чата. Нужен, чтобы прочитать историю, обработать обращение и получить детальную статистику	321	imopenlines.session.history.get — в поле sessionId, по известному CHAT_ID. Выборкой по линии, каналу и периоду — imopenlines.v2.Session.list. Идентификатор входит и в строку entity_data_1 ответа imopenlines.dialog.get. Правило разбора этой строки описано на странице метода imopenlines.session.history.get
USER_CODE	Внешний код пользователя канала связи. Нужен, чтобы однозначно связать внешнего клиента с чатом и сессией в линии. Составное значение формата <connector>|<LINE_ID>|<CONNECTOR_CHAT_ID>|<CONNECTOR_USER_ID>	livechat|22|1761|587	Внешний канал собирает его из четырех частей: код коннектора, идентификатор линии, идентификатор чата и идентификатор собеседника в самом канале. Готовое значение возвращает imopenlines.dialog.get в поле entity_id, принимает — imopenlines.session.open
USER_ID	Идентификатор пользователя Битрикс24. Нужен, чтобы назначить получателя при передаче диалога, указать отправителя в imopenlines.crm.message.add и отбирать сессии по оператору. В большинстве методов статистики тот же идентификатор называется operatorId и operatorIdList, в imopenlines.v2.Operator.list — userId и userIdList	1	user.get, user.search
LINE/CONFIG_ID	Идентификатор открытой линии. Нужен, чтобы читать данные линии, менять настройки, связывать с линией сообщения коннектора и ограничивать выборку статистики. В методах imconnector.* называется LINE, в методах, которые читают, изменяют и удаляют конкретную линию, — CONFIG_ID, в методах статистики — configId и configIdList	22	imopenlines.config.add возвращает идентификатор созданной линии в result, imopenlines.config.list.get — идентификаторы существующих линий
CONNECTOR	Идентификатор коннектора. Нужен, чтобы указать, к какому подключенному каналу относится вызов imconnector.*. Хранится в нижнем регистре	myconnector	Задается в параметре ID метода imconnector.register, затем передается, например, методам imconnector.activate и imconnector.send.messages
source	Код канала открытой линии в методах статистики. Нужен, чтобы отбирать сессии по каналу обращения. У собственного коннектора совпадает с его CONNECTOR. У встроенных каналов свой код, он может не совпадать с первой частью USER_CODE	livechat	Готовые значения приходят в поле source ответа imopenlines.v2.Session.list. Коды доступных каналов возвращает imconnector.list

Идентификаторы CHAT_ID и USER_ID приведены в таблице в том значении, которое им дают методы imopenlines.*. В методе imconnector.chat.name.set те же имена означают другое — это идентификаторы чата и собеседника во внешней системе, а не в Битрикс24.

Метод imconnector.send.messages возвращает CHAT_ID Битрикс24 в объекте session — это значение передают дальше в методы imopenlines.*. Полный разбор идентификаторов коннектора — в разделе Коннекторы открытых линий.

Как начать работуКак начать работу

Подключить собственный канал связи через коннекторПодключить собственный канал связи через коннектор

1. Создайте открытую линию методом imopenlines.config.add или получите идентификатор существующей линии методом imopenlines.config.list.get — передавайте его в параметре LINE начиная с третьего шага
2. Зарегистрируйте коннектор методом imconnector.register
3. Включите коннектор на линии методом imconnector.activate
4. Задайте настройки канала методом imconnector.connector.data.set. Порядок важен: настройки появятся в интерфейсе оператора только после активации коннектора
5. Проверьте готовность канала методом imconnector.status
6. Передайте сообщение клиента методом imconnector.send.messages
7. Подпишитесь на события коннекторов, чтобы получать ответы операторов и передавать их во внешний канал

Подключить открытую линию другого Битрикс24Подключить открытую линию другого Битрикс24

1. Подключите линию методом imopenlines.network.join по 32-символьному коду CODE из карточки линии в Контакт-центре
2. Отправьте сообщение пользователю от имени подключенной линии методом imopenlines.network.message.add — по тому же коду CODE

Обработать обращение на своей линииОбработать обращение на своей линии

1. Получите идентификатор чата методом imopenlines.session.open по коду USER_CODE
2. Примите диалог методом imopenlines.operator.answer
3. Прочитайте переписку методом imopenlines.session.history.get
4. Завершите обращение методом imopenlines.operator.finish

Передать диалог другому оператору можно методом imopenlines.operator.transfer. Для автоматизации подключите события открытых линий.

Построить отчет по открытым линиям во внешней системеПостроить отчет по открытым линиям во внешней системе

1. Получите агрегированные показатели за период с dateFrom по dateTo методом imopenlines.v2.Stat.get
2. Получите список сессий методом imopenlines.v2.Session.list — период у него задают парой dateCreateFrom и dateCreateTo либо dateCloseFrom и dateCloseTo
3. Детализируйте выбранные сессии методами imopenlines.v2.Session.Stat.get и imopenlines.v2.Session.Transfer.list — оба принимают идентификаторы сессий из второго шага
4. Выгрузите оцененные клиентом сессии методом imopenlines.v2.Session.Rating.list — период у него задают обязательные dateVoteFrom и dateVoteTo, это даты оценки. Вместе с оценкой клиента метод возвращает оценку руководителя, если она доступна по тарифу и правам пользователя
5. Получите текущую нагрузку операторов методом imopenlines.v2.Operator.list

Ограничения и версииОграничения и версии

• Ветка imopenlines.v2.* — единственная для статистики. Здесь v2 — часть имени метода, а не префикс версии API: предыдущей версии этих методов в REST нет
• Параллельных и устаревших веток методов в разделе нет
• Метод imopenlines.session.mode.silent помечен плашкой DEPRECATED, но продолжает работать. Это единственный метод раздела, у которого остановлено развитие
• Методы статистики в облаке работают, если тариф позволяет использовать отчеты открытых линий. В коробочной версии ограничение тарифа не применяется
• Метод imopenlines.network.message.add не работает при сессионной авторизации и отправляет каждому пользователю не больше одного сообщения в неделю. На аккаунтах с лицензией Партнера (NFR) лимит не действует

Обзор методов и событийОбзор методов и событий

Scope: imopenlines

Кто может выполнять метод: в зависимости от метода

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

Методы коннекторов входят в тот же scope imopenlines. Методам группы Чат-боты в открытых линиях нужны два scope: imopenlines и imbot. Подписаться на события можно только из приложения — методом event.bind, работа с событиями описана в статье Концепция и преимущества обработки событий.

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

Справочные материалыСправочные материалы

Статья	Описание
Типы данных статистики открытых линий	Структуры объектов session, rating, transfer и других, которые возвращают методы imopenlines.v2.*

Настройка линий и работа с диалогамиНастройка линий и работа с диалогами

Раздел	Когда использовать	Ключевые методы
Открытые линии	Для настройки линий, очередей операторов и подключения Битрикс24 Network	imopenlines.config.add, imopenlines.config.list.get, imopenlines.network.join
Диалоги открытых линий	Для работы с чатами, сессиями, историей переписки, режимами диалога и оценкой руководителя за завершенную сессию	imopenlines.session.open, imopenlines.dialog.get, imopenlines.session.history.get
Операторы открытых линий	Для действий оператора в активном диалоге: принять, передать, завершить	imopenlines.operator.answer, imopenlines.operator.transfer, imopenlines.operator.finish
Сообщения открытых линий	Для отправки сообщений в чат, привязанный к объекту CRM, и сохранения быстрых ответов	imopenlines.crm.message.add, imopenlines.message.quick.save
Чаты CRM	Для поиска чатов, связанных с объектами CRM, и управления их участниками	imopenlines.crm.chat.get, imopenlines.crm.chat.user.add
Чат-боты в открытых линиях	Для автоматизации диалога ботом: ответить, перевести на оператора, закрыть сессию	imopenlines.bot.session.message.send, imopenlines.bot.session.operator, imopenlines.bot.session.finish

Раздел	Когда использовать	Ключевые события
События открытых линий	Для реакции на сообщения, начало и завершение сессии	OnOpenLineMessageAdd, OnSessionStart, OnSessionFinish

Коннекторы и статистикаКоннекторы и статистика

Раздел	Когда использовать	Ключевые методы
Коннекторы открытых линий	Для подключения собственного канала связи и обмена сообщениями с ним	imconnector.register, imconnector.activate, imconnector.send.messages
Статистика открытых линий	Для отчетов и дашбордов во внешней системе: агрегаты, сессии, оценки, переводы, нагрузка операторов	imopenlines.v2.Stat.get, imopenlines.v2.Session.list, imopenlines.v2.Operator.list

Раздел	Когда использовать	Ключевые события
События коннекторов	Для реакции на ответы операторов, создание и закрытие диалога, отключение статуса канала и удаление линии	OnImConnectorMessageAdd, OnImConnectorDialogStart, OnImConnectorStatusDelete