Интеграция Roistat с ПланФикс¶

Как работает интеграция¶

При оформлении заявки на сайте автоматически создается новая задача в ПланФикс, в которую передается номер визита из куки браузера roistat_visit в дополнительное поле с именем roistat. Если менеджер принимает заявку по телефону, он может спросить промокод (настраивается отдельно) и ввести этот код в поле roistat.

Настройка интеграции¶

Обратите внимание:

Данная инструкция подходит для конфигурации ПланФикс Базовое рабочее пространство, в которой верхняя панель выглядит следующим образом:

Шаг 1. Установите счетчик на сайт¶

На каждую страницу, куда заходят посетители, нужно установить счетчик, который позволит Roistat получать данные о посетителях. Сразу будет доступна функциональность промокодирования (для отслеживания продаж через телефон). Счетчик установит в cookie переменную roistat_visit, которая будет содержать номер визита.

О том, как установить счетчик на сайт, читайте в статье Установка счетчика. Если на сайте уже есть счетчик, пропустите этот шаг.

Шаг 2. Добавьте дополнительное поле roistat¶

Войдите в личный кабинет ПланФикс.
Перейдите в раздел Задачи → Шаблоны. Если у вас уже есть шаблон, по которому нужно создавать заявки, кликните по его названию и нажмите Редактировать. Вы также можете создать новый шаблон, кликнув Новый шаблон задачи:
В окне создания/редактирования шаблона нажмите Новое поле:

Откроется окно Добавление нового поля
В поле Название введите roistat. Значения остальных параметров установите по своему усмотрению:
Нажмите Сохранить.
Поле roistat появится в списке полей в блоке Панель 1. Вы можете отобразить его и на других панелях шаблона – для этого раскройте меню настроек поля и выберите нужные панели:

Шаг 3. Подключите ПланФикс в каталоге интеграций¶

В проекте Roistat откройте раздел Интеграции.
Нажмите Добавить интеграцию. В появившемся окне введите ПланФикс, кликните по карточке и нажмите Добавить:

Затем нажмите Настроить интеграцию (иконка шестеренки):
Откроется окно с параметрами авторизации:

Заполните поля:
- Поддомен АПИ: введите apiru, если ваш проект Планфикс расположен на сервере в России, или api, если ваш проект Планфикс расположен на сервере в другой стране;
- Поддомен: имя аккаунта в ПланФикс. Например, если адрес аккаунта – test.planfix.ru, введите test;
- Логин для входа в PlanFix и Пароль: логин и пароль, которые вы вводили при регистрации в ПланФикс;
- АПИ ключ: аутентификационный ключ для доступа к API ПланФикс;
- Секретный ключ: ключ подписи для доступа к API ПланФикс;
  Как получить аутентификационный ключ (АПИ ключ) и ключ подписи (секретный ключ)
  - В личном кабинете ПланФикс в правом верхнем углу откройте меню Настройки и выберите Управление аккаунтом:
  - Перейдите в раздел Доступ к API. В поле APIKey скопируйте аутентификационный ключ, в поле PrivateKey – ключ подписи.
- Идентификатор шаблона контакта и Идентификатор шаблона компании;
  Как получить идентификаторы шаблона контакта и шаблона компании
  - В личном кабинете ПланФикс на панели навигации выберите Контакты.
  - Перейдите в раздел Шаблоны. Напротив строк Шаблон контакта и Шаблон компании отображаются нужные идентификаторы:
- Идентификатор шаблона задачи;
  Как получить идентификатор шаблона задачи
  - В личном кабинете ПланФикс в панели навигации выберите Задачи.
  - Перейдите в раздел Шаблоны. Найдите шаблон, который вы используете для создания заявок. Напротив строки с названием шаблона отображается нужный идентификатор:
  В Roistat загружаются все задачи, а не только те, которые удовлетворяют указанному шаблону. Шаблон задачи необходим для создания новых задач в проекте Roistat для последующей передачи в ПланФикс (см. Шаг 4).
  
  Дополнительные поля и статусы задач загрузятся в Roistat из указанного шаблона задачи.
Нажмите Сохранить. Откроется раздел Распределение статусов, в котором загрузятся статусы задач из ПланФикс.
Перетаскивая статусы задач, распределите их по группам. Подробнее читайте в статье Распределение статусов сделок.
Нажмите Продолжить. Откроется инструкция по включению отправки заявок. Ознакомьтесь с ней и нажмите Следующий шаг.
В разделе Расширенные настройки укажите параметры для фильтрации сделок. Подробнее – в статье Фильтрация сделок.
Также укажите значения полей бизнес-показателей. Подробнее – в статье Поля бизнес-показателей.
Нажмите Сохранить.

Шаг 4. Настройте автоматическую отправку заявок в ПланФикс¶

Рекомендуем настроить передачу заявок в ПланФикс через Roistat – в этом случае заявки сначала передаются в Roistat, а затем отправляются в ПланФикс в виде задач. Данный механизм обладает рядом преимуществ. Подробнее читайте в статье Передача заявок в CRM через Roistat.

Обратите внимание:

Передача дополнительных полей в задачу Планфикс невозможна.

Если отправка заявок с сайта в ПланФикс уже настроена с помощью вашего кода, для обмена данными с Roistat вам необходимо заполнить дополнительное поле roistat значением cookie roistat_visit.

Пример кода, с помощью которого можно получить значение этой cookie:

$roistatVisitId = array_key_exists('roistat_visit', $_COOKIE) ? $_COOKIE['roistat_visit'] : "неизвестно"

Проверка работы¶

Если настроено создание задач в ПланФикс через Roistat

После того, как на сайте отправлена заявка, в ПланФикс создается новая задача с заполненным полем roistat. Заявки отображаются и в Roistat:

В проекте Roistat откройте раздел Состояние проекта → Список отправленных заявок и найдите созданную заявку:
Проверьте статус отправки заявки: в поле Отправлен должен появиться статус отправки V, а в поле Сделка – номер задачи в ПланФикс.

Если задачи создаются напрямую, а не через Roistat

В проекте Roistat перейдите в раздел Аналитика → Отчеты. Задачи ПланФикс должны отображаться в столбце Заявки:

Передача заявок при интеграции ПланФикс и Telegram¶

Вы можете настроить передачу заявок с номером визита из Telegram в Roistat, если у нас настроена интеграция ПланФикс с Telegram.

Если вы ещё не используете бота Telegram, создайте его:
- Найдите бота @BotFather в Telegram.
- Запустите бота, отправив в чат команду /start.
- Отправьте в чат команду /newbot.
- Создайте бота, следуя инструкции, которую предоставляет @BotFather.
После создания бота вам будет выдан API-токен. Сохраните его, он понадобится для настройки интеграции.

Если у вас есть готовый бот, зайдите в диалог с @BotFather и найдите в истории сообщений API-токен соответствующего бота.
В кнопку Telegram на сайте добавьте ссылку вида https://t.me/{botname}, где {botname} – название вашего бота.

Убедитесь, что на сайте установлен счетчик Roistat. Сразу после кода счетчика вставьте следующий скрипт:

<script>
   (function() {
       if (window.roistat !== undefined) {
           handler();
       } else {
           var pastCallback = typeof window.onRoistatAllModulesLoaded === "function" ? window.onRoistatAllModulesLoaded : null;
           window.onRoistatAllModulesLoaded = function () {
               if (pastCallback !== null) {
                   pastCallback();
               }
               handler();
           };
       }

       function handler() {
           function init() {
               appendMessageToLinks();

               var delays = [1000, 5000, 15000];
               setTimeout(function func(i) {
                   if (i === undefined) {
                       i = 0;
                   }
                   appendMessageToLinks();
                   i++;
                   if (typeof delays[i] !== 'undefined') {
                       setTimeout(func, delays[i], i);
                   }
               }, delays[0]);
           }

           function replaceQueryParam(url, param, value) {
               var explodedUrl = url.split('?');
               var baseUrl = explodedUrl[0] || '';
               var query = '?' + (explodedUrl[1] || '');
               var regex = new RegExp("([?;&])" + param + "[^&;]*[;&]?");
               var queryWithoutParameter = query.replace(regex, "$1").replace(/&$/, '');
               return baseUrl + (queryWithoutParameter.length > 2 ? queryWithoutParameter  + '&' : '?') + (value ? param + "=" + value : '');
           }

           function appendMessageToLinks() {
               var message = 'roistat_{roistat_visit}';
               var text    = message.replace(/{roistat_visit}/g, window.roistatGetCookie('roistat_visit'));
               text = encodeURI(text);
               var linkElements = document.querySelectorAll('[href*="//t.me"]');
               for (var elementKey in linkElements) {
                   if (linkElements.hasOwnProperty(elementKey)) {
                       var element = linkElements[elementKey];
                       element.href = replaceQueryParam(element.href, 'start', text);
                   }
               }
           }
           if (document.readyState === 'loading') {
               document.addEventListener('DOMContentLoaded', init);
           } else {
               init();
           }
       };
   })();
</script>

Настройте интеграцию ПланФикс с Telegram. Для этого перейдите в Меню → Управление аккаунтом → Интеграции → Мессенджер → Telegram:

Затем нажмите Добавить бота и заполните поля Имя бота и Ключ доступа (API-токен, полученный в п.1):

Нажмите Сохранить.
Если вы хотите настроить автоматическое заполнение поля roistat, перейдите к пунктам 6-12. Для настройки может понадобиться помощь разработчика.

Если же вы не хотите настраивать автоматическое заполнение поля roistat, можно передавать номер визита вручную. При первом обращении клиента в Telegram будет создана задача с текстом /start roistat_{number}, где {number} – номер визита. Этот номер нужно скопировать в поле roistat, созданное при интеграции с ПланФикс:
Вы можете настроить автоматическую передачу номера визита из Telegram в Roistat. Для этого в интерфейсе ПланФикс перейдите в Управление аккаунтом → Процессы задач → Новый процесс и создайте процесс с любым названием:
Перейдите в созданный процесс и нажмите Автоматические сценарии:
Создайте новый сценарий:

Необходимо заполнить поля следующим образом:
- Событие, при котором будет запущен сценарий: Задача создана и соответствует условиям
- Условия сценария: Описание – э (содержит) – roistat_
- Ставить сценарий в очередь на выполнение
- Выполнить следующие операции:
  - Послать HTTP-запрос
  - Метод: GET
  - URL: http://ссылка_на_ваш_скрипт?roistat={{Задача.Описание.Без форматирования::написание=с маленькой буквы}}, где ссылка_на_ваш_скрипт – ссылка на обработчик, расположенный на вашем хостинге. В дальнейшем в данный обработчик нужно будет вставить код (п.10). Другие значения в URL менять не нужно.
- Заголовки: Content-Type – application/x-www-form-urlencoded
- Авторизация: Без авторизации
- Установить чекбокс Разобрать полученный ответ
Внизу окна создания сценария нажмите Настроить разбор ответа – откроется окно настройки:

Необходимо заполнить поля следующим образом:
- Извлечение данных:
  - Извлекать из текста в формате: Текст (без форматирования)
  - Название инфоблока: visit
  - Извлечь текст: Все содержимое
- Выполнить следующие действия:
  - Изменить эту задачу
  - Изменение: Установить значение поля из инфоблока
  - Поле: roistat
  - Инфоблок: visit
В обработчик, указанный в п.8 в поле URL, вставьте следующий код:
```
<?php

if (empty($_GET['roistat'])) die();

echo preg_replace('/\/start roistat_/', '', $_GET['roistat']);
```
Привяжите процесс к вашему шаблону создания задач и проверьте работу. Для этого перейдите в Задачи → Шаблоны → Новый шаблон задачи:

Введите название шаблона и нажмите кнопку Сохранить:
Теперь необходимо привязать созданный шаблон к интеграции с Telegram. Для этого зайдите в Управление аккаунтом → Интеграции → Мессенджеры:

Нажмите Telegram → Настройки интеграции (шестеренка):

В списке Шаблон для создания новых задач выберите созданный шаблон:

Готово: теперь при создании задачи с Telegram номер визита будет автоматически передаваться в дополнительное поле roistat.