Интеграция 1С с открытыми линиями облачного Битрикс24

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

Можно, конечно, нанять отдельного специалиста, который будет отслеживать и управлять всеми каналами связи. А можно использовать Битрикс24, где реализована поддержка множества цифровых каналов связи, которые объединяются в единый центр – Открытые линии. Каждое обращение Открытой линии представлено в виде диалога между клиентом и сотрудником компании.

Информацию диалогов Открытых линий можно использовать для автоматического инициирования процесса продажи товаров/услуг в учетной системе 1С. Но можно ли интегрировать Открытые линии Битрикс24 с 1С и использовать информацию диалогов для автоматического старта бизнес-процессов и задач?

Зачем нам это понадобилось?

Мы хотели получить инструмент, который позволит:

• сохранять историю переписки с клиентом в 1С, чтобы обращаться к ней при дальнейшей работе с клиентом и при заключении новых сделок;
• делать автоматический старт бизнес-процесса с описанием сделки на ответственного сотрудника и следить за эффективностью его работы;
• автоматически ставить задачи на наших консультантов, чтобы оперативно отрабатывать запросы наших клиентов.

Эти три функции позволят существенно сократить время реагирования на запрос клиента и помогут ориентироваться в истории отношений с каждым клиентом, даже если их тысячи. Такой подход даст +100 к репутации и клиентоориентированности.

Итак, задача ясна, посмотрим, как ее решить.

Интеграция с Битрикс24

Интеграция 1С и Битрикс24 описана на сайте поддержки и решает несколько больших задач:

• ведение клиентской базы,
• автоматическое выставление счетов в учетной системе,
• синхронизация товаров.

Для этого производитель предлагает набор специальных модулей, предназначенных для определенных версий конфигураций «1С» и для обмена только определенными данными.

Как же выполнить «нестандартную» интеграцию, например, с Открытыми линиями? Для этих целей Битрикс24 предоставляет разработчикам REST API с довольно обширным функционалом.

Ознакомившись с предоставляемыми функциями API, их описанием в документации, проведя ряд экспериментов, мы поняли: выполнить интеграцию с Открытыми линиями с помощью REST API не получится. Причина – REST API не предоставляет базовых возможностей работы с Открытыми линиями: нет получения списка диалогов, настройки фильтрации и т.д. Поиск решения проблемы на специализированных форумах технической поддержки Битрикс24, также не принес результата.

Что же делать?

Раз уж в REST API нет функционала по полноценной работе с Открытыми линиями, эмулируем работу пользователя с сайтом Битрикс24 для автоматической загрузки информации из Открытых линий в учетную систему.

Со стороны пользователя для получения истории переписки с клиентом необходимо выполнить следующие шаги:

• Пройти авторизацию на сайте Битрикс24;
• Перейти в список диалогов контакт-центра;
• Найти интересующий диалог;
• Посмотреть историю диалога.

Каждый из этих шагов требуется эмулировать программно, в автоматическом режиме. Но какие запросы выполняет сайт Битрикс24, какие структуры данных передает? Для успешной эмуляции работы пользователя требуется изучить работу сайта «под капотом» и получить ответ на этот вопрос.

Для изучения поведения и работы сайта будем использовать:

• Инструменты разработчика для изучения запросов, отправляемых сайтом. Выбор пал на инструменты разработчика, встроенные в Google Chrome (далее GCDT – Google Chrome DevTools);
• Инструменты тестирования. Например, Postman. Инструмент используется для эмуляции вызовов API Битрикс24;
• Инструменты просмотра JSON/XML, таких как json.parser.online.fr.

Критерии интеграции

Для начала определим, какие именно данные Открытых линий интересуют для автоматической обработки. Это диалоги, которые отвечают следующим условиям:

• Принадлежат определенной Открытой линии, ведь линий может быть несколько;
• Не помечены как СПАМ;
• Завершены, причем завершены в указанный интервал даты/времени.

Загрузке же в учетную систему подлежит вся доступная информация диалога:

• Текст диалога;
• Ссылки;
• Имеющиеся данные клиента;
• Данные сотрудника, который общался с клиентом.

Изучение работы сайта Битрикс24 и эмуляция работы пользователя средствами 1С

Так как эмуляции подвергается работа сайта, то задействованными объектами будут HTTPСоединение и HTTPЗапрос.

Каждый запрос или ответ сайта Битрикс24 анализируются с помощью инструментов разработчика Google Chrome(GCDT).

Также следует отметить, что:

• Для корректной работы сайта Битрикс24 требуются cookie, полученные с сервера Битрикс24. Cookies необходимо передавать при каждом запросе к серверу;
• AJAX запросы к серверу должны сопровождаться заголовком «bx-ajax: true»;
• Http-формы отправляются на сервер методом POST, тип содержимого формы, заголовок content-type: application/x-www-form-urlencoded.
  
• Большинство запросов к серверу требуют указания параметра SESSID (идентификатором сессии пользователя). SESSID содержится в html-коде страницы авторизации по ключу bitrix-sessid. Также есть хитрость получения SESSID, которая заключается в том, что если SESSID не указан в запросе – ответом сайта будем ошибка с указанием ожидаемого SESSID. Формат ошибки различен для разных запросов и требует дополнительного изучения с помощью GCDT. Ниже приведены примеры, иллюстрирующие положение SESSID в коде html-страницы и ответа ошибки неверного SESSID на запрос проверки авторизации пользователя.
  

Авторизация на сайте

В работе с Битрикс24 используем стандартную аутентификацию «Пользователь/Пароль», поэтому далее будет описан процесс этого вида авторизации.

При входе на сайт, если требуется проверка авторизации, Битрикс24 выполняет переход на страницу. Т.е. в работе Битрикс24 используется два различных сайта: первый – это адрес сайта Битрикс24(собственно сайт Битрикс) и второй – это адрес сайта авторизации. В дальнейшей работе необходимо учитывать этот факт.

При переходе на сайт авторизации адрес страницы, на которую выполняется переход, указан в заголовке ответа location.

Проверка пары «Пользователь/Пароль» выполняется AJAX запросом по адресу СайтАвторизации/bitrix/services/main/ajax.php?action=b24network.authorize.check

Данные пользователя для проверки передаются html-формой:

• login – Имя пользователя сайта Битрикс24;
• password – Пароль пользователя;
• remember – Число 0 или 1. Признак «запомнить на сайте». 0 – не запоминать;
• SITE_ID – ID сайта, в формате sНомерСайта.
• У компании может быть несколько нод сайта Битрикс24, поэтому при проверке авторизации указывается, для какой ноды пользователь проходит проверку. В нашем случае нода одна – указывается s1;
• sessid – Идентификатор сессии пользователя. См. описание и получение идентификатора тут (!!переход внутри документа!!).

Результат проверки авторизации – JSON строка следующего вида:

{
"status":"error", – Статус проверки

"data":null, – Данные результата аутентификации. В случае ошибки null.

"errors":{ – Ошибки
}
}

После успешной проверки авторизации сайт Битрикс24 может выполнить несколько переходов. Учитывая данную специфику эмуляция этапа проверки авторизации должна поддерживать рекурсивные переходы. Также следует ограничить количество переходов, например не более 20 переходов, это необходимо в случае сбоя в работе сайта или ошибках аутентификации.

Работа с диалогами

После успешного прохождения аутентификации доступно получение истории диалогов.

Но для этого требуется знать номер диалога.

Как было сказано выше, REST API Битрикс24 не предоставляет функционала чтения списка и истории диалогов.

Поэтому список диалогов будем получать путем парсинга страницы контакт-центра. Список диалогов подготавливается с помощью установки фильтров.

Для программного получения истории диалога открытой линии необходимо:

• 1. Перейти на страницу списка диалогов по адресу СайтБитрикс24/contact_center/openlines/statistics.php. Это страница списка диалогов контакт-центра;
• 2. Определить идентификаторы таблицы диалогов и AJAX данных путем парсинга html-кода страницы списка диалогов.

Идентификатор таблицы диалогов содержится в атрибуте id следующего за определением css класса для таблицы списка диалогов:

class=”main-grid” id=”ИдентификаторТаблицы”

Идентификатор AJAX данных содержится в атрибуте:

data-ajaxid=”ИдентификаторAJAX”

• 3. Настроить фильтр списка диалогов.

Настройка фильтра выполняется в html-форме, которая поддерживает настройку ряда параметров.

Структура настроек фильтра:

params[FILTER_ID]= - Идентификатор настройки фильтра
&params[GRID_ID] = - Идентификатор таблицы диалогов
&params[action] = setFilter - Действие выполняемое с фильтром
&params[apply_filter] = Y - Применять фильтр
&params[clear_filter] = N - Выполнить очистку фильтра
&params[with_preset] = N - Фильтрация не по шаблону
…Список параметров через &…
&param[Параметр] = Значение - Настроенные поля фильтров
&data[fields][Поле]= Значение
…Список настроенных фильтров &…
&data[rows] = - Перечень полей включаемых в результат, разделенный запятой

&data[preset_id] = - Идентификатор настройки фильтра
&data[name] = - Заголовок фильтра
&SITE_ID = - Номер сайта, по аналогии с авторизацией
&sessid = - Номер сессии пользователя

Полный список всех параметров следует поискать в документации Битрикс или проанализировать с помощью GCDT.

По критериям интеграции интересуют диалоги, отвечающие условиям:

• Только завершенные диалоги. За эту настройку отвечает поле STATUS. Значение для закрытых диалогов – closed;
• Завершенные в конкретный интервал дат. Фильтр устанавливается на поля:
  • DATE_CLOSE_datesel – Тип интервала дат. Необходим RANGE – произвольный интервал;
  • DATE_CLOSE_from – Дата, с которой нужно получить список диалогов в формате дд.ММ.гггг [ЧЧ:мм], где [ЧЧ:мм] опционально;
  • DATE_CLOSE_to – Дата, до которой нужно получить список диалогов. Формат аналогичен описанному в DATE_CLOSE_from.
• Не помеченные как СПАМ. Для этого устанавливается настройка поля SPAM = N;
• Конкретных открытых линий. Поддерживается настройка нескольких открытых линий. Настройка выполняется в формате data[fields][CONFIG_ID][ПорядковыйНомер] = ИдентификаторЛинии, где: ПорядковыйНомер – Последовательный числовой номер открытой линии для фильтра; ИдентификаторЛинии – Идентификатор открытой линии. Получить список открытых линий можно с помощью метода imopenlines.config.list.get, описанного в REST API (либо посмотреть требуемый идентификатор с помощью GCDT). Для использования методов REST API необходима активация вебхуков, как это сделать, описано здесь и здесь.

Пример заполненной формы для установки фильтра:

params[FILTER_ID]: tmp_filter
params[GRID_ID]: imopenlines_statistic_v3
params[action]: setFilter
params[forAll]: false
params[apply_filter]: Y
params[clear_filter]: N
params[with_preset]: N
params[save]: Y
data[fields][STATUS]: closed
data[fields][DATE_CLOSE_datesel]: RANGE
data[fields][DATE_CLOSE_from]: 01.09.2020
data[fields][DATE_CLOSE_to]: 02.09.2020
data[fields][CONFIG_ID][0]: 23
data[fields][SPAM]: N
data[rows]: SOURCE,ID,STATUS,DATE_CLOSE
data[preset_id]: tmp_filter
data[name]: Фильтр
SITE_ID: s1
sessid: f8a159827a295a15808e53f3367a5sss

• 4. Установить отбор диалогов по настроенному фильтру, с помощью AJAX запроса по адресу СайтБитрикс/bitrix/services/main/ajax.php?analyticsLabel[FILTER_ID]=ИдентификаторФильтра&analyticsLabel[GRID_ID]= ИдентификаторТаблицыДиалогов&mode=ajax&c=bitrix:main.ui.filter&action=setFilter, в качестве тела запроса передается настроенная html-форма фильтра.

Результат установки отбора диалогов – JSON строка, ключ status которой содержит признак статуса установки фильтра. Значение success соответствует успешно установленному фильтру.

• 5. Сбросить навигацию (пагинацию) после установки отбора.

Для этого на адрес установки отбора списка диалогов отправляется AJAX запрос, содержащий следующую html-форму:

apply_filter: Y
&clear_nav: Y

• 6. Постранично прочитать и обработать таблицу со списком диалогов.

Для постраничного чтения необходимы идентификатор сессии (sessid) и данные таблицы списка диалогов: идентификатор таблицы, идентификатор AJAX, номер страницы и общее количество страниц.

Идентификатор сессии(sessid), идентификаторы таблицы диалогов и AJAX данных определены на предыдущих шагах

Общее количество страниц вычисляется путем парсинга страницы и определяется по классу main-ui-pagination-page.

Например,

…class="main-ui-pagination-page">13</a>….

Определив общее количество страниц, для получения списка диалогов, для каждой страницы, отправляется запрос вида

СайтБитрикс/contact_center/openlines/statistics.php?sessid=ИдентификаторСессии&internal=true&grid_id=ИдентификаторТаблицыДиалогов&apply_filter=Y&clear_nav=Y&grid_action=showpage &page=page-НомерСтраницы&bxajaxid=ИдентификаторAJAXДанных

В результате запроса для указанного номера страницы будет сформирована html-таблица, содержащая номера диалогов.

Номер диалога в html-коде таблицы представляет из себя текст формата imol|НомерДиалога. Для получения перечня номеров диалогов из таблицы необходимо выполнить парсинг html-страницы или поиск по регулярному выражению “(imol\|[0-9\s]+)”

• 7.Получить историю диалога после того, как список диалогов определен.

История диалога представляет из себя JSON строку получаемую в результате отправки на адрес СайтБитрикс/bitrix/components/bitrix/im.messenger/im.ajax.php?SESSION_GET_HISTORY&V=129 html-формы следующего содержания:

COMMAND=sessionGetHistory - Команда получения истории
&SESSION_ID= - Число номера диалога (без imol)
&IM_OPEN_LINES=Y
&IM_AJAX_CALL=Y
&sessid= - Идентификатор сессии пользователя

В случае ошибки json содержит ключ «error», значение которого указывает на ошибку.

Пример ошибки сессии:

{
"ERROR":"SESSION_ERROR",
"BITRIX_SESSID":"151160cd188b98ff342290522ba43sss"
}

В случае успешного получения истории диалога JSON, в общем случае, имеет следующую структуру:

{
"CHAT_ID":НомерЧата,
"CAN_JOIN":"Y",
"CAN_VOTE_HEAD":"Y",
"SESSION_ID":НомерДиалога,
"SESSION_VOTE_HEAD":"0",
"SESSION_COMMENT_HEAD":"",
"USER_ID":ИдентификаторЧата в формате chat<НомерЧата>,
"MESSAGE":{ - Сообщения диалога
НомерСообщения":{
"id":НомерСообщения,
"chatId":НомерЧата,
"senderId":ПользовательОтправитель, - Идентификатор пользователя из секции USERS
"recipientId":Получатель,
"date":ДатаСообщения в формате ISO,
"text":ТекстСообщения,
"params":{ -Параметры сообщения, включая вложения, ссылки, формы и т.д.
}
},
… Другие сообщения …
},
"USERS_MESSAGE":{ - Все номера сообщений диалога
"ИдентификаторЧата":[
"НомерСообщения",
… Другие номера …
]
},
"USERS":{ - Пользователи диалога
"ИдентификаторПользователя":{
"id":ИдентификаторПользователя,
"name":ПолноеИмяПользователя,
"active":ПризнакАктивности,
"first_name":ИмяПользователя,
"last_name":ФамилияПользователя,
… Прочие поля …
},
… Другие пользователи …
},
"OPENLINES":{ - Список отрытых линий диалога
… Список открытых линий …
},
…
"FILES":{ - Файлы вложений
"ИдентификаторФайла":{
"id":ИдентификаторФайла,
"chatId":Чат к которому прикреплен файл,
"date":Дата,
"type":ТипВложения,
"name":ИмяВложения,
"extension":РасширениеФайла,
"size":РазмерФайла в байтах,
… Прочие поля …
}
… Другие файлы …
},
"ERROR":""
}

Обработав список пользователей, секция USERS, и сопоставив их с сообщениями, MESSAGE.Сообщение.senderID, формируем удобочитаемую историю диалога.

В результате мы получаем программный доступ к сообщениям диалогов, которые можем сохранить в учетной системе 1С. Например: сформировать задачи или бизнес-процессы, если диалог удовлетворяет требования бизнеса.