О плагине

Минимальная версия CRM: 2020.1
Версия плагина: 0.50 beta
Разработчик: Владислав Андреев

Плагин позволяет общаться с потенциальными клиентами (Посетителями) используя различные каналы - мессенджеры и социальные сети.

Поддержка мессенджеров:
- Telegram
- Viber
- Whatsapp ( через ChatApi.com )
Поддержка социальных сетей:
- Vk.com
- Fasebook Messenger
Возможность подключения других решений:
- см. /php/Class/Providers/ExampleProvider.php

Прежде чем начать

Используйте только защищенное соединение ( https )

Самоподписанные сертификаты не поддерживаются ни одним провайдером (рекомендуем использовать сертификаты от Let’s Encrypt).

Ваш сервер должен быть доступен из Интернет, чтобы получать уведомления о новых сообщениях

Ваш сервер должен поддерживать работу модуля Apache Mod_Rewrite

Плагин не предназначен для рассылок сообщений - клиент должен написать первым (кроме WhatsApp - вы можете начать беседу из карточки клиента)

При невыполнении данных условий подключение этого плагина бессмысленно

Возможности плагина

Получение сообщений Посетителей и отправка ответов через единый интерфейс
Мгновенная доставка сообщений
Отправка и получение вложений (фотографий и документов)
Возможно ведение диалога совместно с коллегами
Возможна передача диалога другому сотруднику
Загрузка Имени и Аватара Посетителя
Привязка нового Посетителя к Клиенту

Диалог с клиентом в карточке Клиента:

Настройка плагина

Базовая логика

Автоматически добавлять в базу - включает функцию добавления Посетителя в базу
Тип записи - при автоматическом добавлении задает тип записи - Клиент или Контакт добавлять
Автоматически распределять - включает автоматическое распределение новых диалогов на сотрудников в онлайн
Автозакрытие диалогов - автоматически закрывает диалог при отсутствии активности в течение определенного интервала
Автоответы
- Первое обращение - отправляет текст при первом обращении клиента
- Операторы Offline - отправляет текст, если операторы оффлайн
Подключение к Comet-server.ru - этот сервис обеспечит доставку уведомлений о новых сообщениях в режиме реального времени
- Зарегистрируйтесь и добавьте свой сайт
- Получите данные для подключения
  - Публичный id - Dev ID
  - Приватный ключ - Dev KEY

Управление операторами

Оператор - это пользователь CRM, который может общаться с клиентами.

Для добавления оператора следует вызвать список пользователей CRM с помощью кнопки "Добавить оператора". В открывшемся окне выбираем нужных сотрудников.

Удаление сотрудника возможно по-одному или вызовом окна выбора сотрудников кнопкой "Добавить оператора".

Добавление каналов

WhatsApp (через ChatAPI)

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

Регистрация в личном кабинете ChatAPI - https://app.chat-api.com/
Получаем регистрационные данные:
- API URL вида https://eu86.chat-api.com/instanceXXXXX/
- Токен
- Номер аккаунта: WhatsApp #XXXXX
Переходим в настройки плагина
- Добавить новый канал
- Выбираем Chat API
- Заполняем форму:
  - API URL
  - Token - Токен
  - ID канала - Номер аккаунта
- Нажимаем кнопку QR - Авторизация и дожидаемся загрузки QR-кода
- Открываем Whatsapp на телефоне, жмем на три точки -> WhatsApp Web и сканируем код
- Сохраняем форму
- После сохранения система установит Webhook для этого бота

Для сведения

Регистрация Webhook проводится в момент сохранения настроек канала автоматически.

Канал не поддерживает загрузку Аватаров клиентов

Зарегистрируем бота:
- в Telegram (https://tlgrm.ru/docs/bots)
Подключим бота кнопкой "Добавить канал"
- Достаточно указать тип бота и Secret Key
- При необходимости задайте Proxy-сервер, через который сообщения будут доходить до сервера Telegram
- Далее нажмем "Проверить" - в случае успешного подключения будут заполнены поля "Bot ID" и "Имя бота"
- После сохранения система установит Webhook для этого бота

Для сведения

Все манипуляции с ботами осуществляются через @BotFather.

Для получения информации по всем своим ботам используйте команду /mybots

Регистрация Webhook проводится в момент сохранения настроек канала автоматически.

Viber

Зарегистрируемся в Админ-панели - https://partners.viber.com/login. После регистрации мы попадем в панель и сможем создавать ботов
Добавим бота с помощью кнопки Create Bot Account
- добавим аватар бота
- укажем необходимую информацию
- принимаем соглашение
- жмем кнопку "Create" В результате мы получим Token такого вида - 4875a8xxxx-d949xxxxx-463xxx
Подключим бота кнопкой "Добавить канал"
- Достаточно указать тип бота и Secret Key
- Далее нажмем "Проверить" - в случае успешного подключения будут заполнены поля "Bot ID" и "Имя бота"
- Сохраняем данные

Важно для функционирования Регистрация Webhook проводится в момент сохранения настроек канала автоматически.

Vk.com

Vk.com - это социальная сеть, а не просто чат. Поэтому в этом случае процедура подключения канала более сложная. Все действия по получению ключей должен осуществлять сотрудник имеющий права администратора в подключаемой группе

Шаг 1. Регистрация Приложения

Заходим в раздел Мои приложения
Жмем Создать приложение
Выбираем Платформу - Standalone-приложение и сохраняем
Заполняем Информацию о приложении. Тут важно:
- Выбрать Сообщество - указать группу, которую будем подключать как канал
- Желательно загрузить изображения для приложения
Переходим в Настройки приложения и
1. получаем параметры:
  - ID приложения
  - Защищённый ключ
  - Сервисный ключ доступа
2. устанавливаем Состояние в положение "Приложение включено и видно всем"
3. устанавливаем Open API в положение "Включено"
4. сохраняем

Шаг 2. Настройка группы

Переходим в выбранную в п.4 группу ( это должен делать администратор )
Переходим в раздел Управление / Работа с API
Нажимаем Создать ключ
В открывшемся окне указываем права для создаваемого ключа - помечаем все пункты ( это важно )
После нажатия на кнопку Сохранить вам будет показано уведомление - суть его в том, что ВК перезвонит на указанный номер телефона.

Вам нужно запомнить последние 4 цифры номер телефона ( с которого поступил звонок ) и указать их в появившемся окошке без поднятия трубки. Как только вы укажете эти 4 цифры и нажмете на кнопку подтверждения звонок прекратится.
После подтверждения вам будет выдан ключ группы - сохраните его, он понадобится дальше

Шаг 3. Подключение канала к плагину

Выбираем канал - Vk.com
Заполняем поля:
- ID приложения вконтакте - из п. 5 предыдущего шага
- Секретный код приложения - из п. 5 предыдущего шага
- Токен группы - из п.6 предыдущего шага
- ID группы - можно узнать из ссылки на группу
Нажимаем кнопку "Авторизация" ( зеленая )
Будет открыто новое окно ( если не блокируется браузером ), в котором вы должны будете разрешить доступ приложению к группе
Соглашаемся - нас перебросит на новую страницу с примерно таким текстом:

Пожалуйста, не копируйте данные из адресной строки для сторонних сайтов. Таким образом Вы можете потерять доступ к Вашему аккаунту.
Именно данные из адресной строки нам и нужны, поэтому копируем параметр access_token - это вечный ключ доступа, который не требует периодического подтверждения доступа.

Пример данных адресной строки: https://oauth.vk.com/blank.html#access_token=d67d3sdfsdffdfsdfsdfdgcb0249d7fdb967fasdadasd64009c06c6559casdsatee4rfcdfb1b23d1sdfsdf895&expires_in=0&user_id=2498989
Закрываем всплывающее окно, а полученный ключ копируем в поле Токен приложения
Нажимаем кнопку Проверить ( синяя ) - после нажатия:
- Плагин свяжется с сервером Vk с указанными данными
- Будет получен параметр Callback Server ID - он нужен для подтверждения адреса для Webhook
- Будет заполнено Название группы
Сохраняем настройки

Для сведения

Регистрация Webhook проводится в момент сохранения настроек канала автоматически.

Facebook Messenger

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

Все действия необходимо делать параллельно и в Fasebook и в CRM

Переходим в Facebook
Заходим в раздел Мои приложения
Жмем Добавить новое приложение и проходим проверку ( например Google Capcha )
Выбираем Messenger и нажимаем Настроить
Переходим к блоку Маркеры доступа / Добавить и в открывшемся окне ( следую подсказкам ) связываем приложение со страницей в Facebook
Генерируем Маркер доступа и сохраняем его где-нибудь (если не сохранить, то придется генерировать новый)
Переходим в CRM
Жмем "Добавить канал" и выбираем "Facebook Messenger"
Заполняем данные:
- ID страницы - отображается в разделе "Маркеры доступа" под названием страницы
- ID приложения - отображается в верхней части страницы
- Секретный код приложения - получили при создании приложения (можно найти в разделе "Настройки / Основное" в интерфейсе FB)
- Токен страницы (Маркер страницы) - сгенерирован в п.6
Делаем предварительное сохранение - чтобы сохранить Токен подтверждения - он генерируется при добавлении канала в CRM
Переходим в Facebook
Переходим к блоку Webhooks и нажимаем кнопку Добавить URL обратного вызова. Здесь нам нужно указать:
- URL-страницы, которая будет принимать данные от Facebook - его нужно будет получить в плагине, вызвав форму добавления нового канала и выбрав Facebook и заполнив ID страницы ( п.7 )
- Токен подтверждения - из формы добавления канала ( п.7 )
- Сохраняем форму - В это время будет проведена проверка URL-страницы для webhook с токеном подтверждения. Если всё прошло удачно, то URL будет сохранен
Добавляем подписки:
- messages — сообщения, написанные пользователем боту
- message_deliveries — уведомления о доставке сообщения
- messaging_optins — callback при получении сообщения через кнопку на сайте (Send-to-Messenger Plugin)
- messaging_postbacks — переходы по кнопкам из предыдущих сообщений бота (будет понятно далее)
Переходим к проверке приложения «Messenger»
- добавим в заявку pages_messaging
- подробно заполняем сведения Подробная информация о функции «pages_messaging»:
  - принимаем условия
  - выбираем сценарии использования:
    - Использование бизнес-интеграции для поддержки чата между людьми
    - Другое. Расскажите подробнее о своих примерах использования: Общение между людьми и специалистами компании
  - опишем действия клиентов в блоке Протестируйте и воспроизведите функции вашей интеграции. Мы писали так:
    - Шаг 1. Перейдите на страницу https://www.facebook.com/{ВАША_СТРАНИЦА}/
    - Шаг 2. Нажмите отправить сообщение
    - Шаг 3. Напишите сообщение
  - приложим скринкаст - придется записать видео, в котором покажете, как действует приложение (максимум 5 минут, мы еще и голосом описали действия)
- сохраняем
Если кнопка "Отправить на проверку" стала активной, то следует отправить заявку, нажав на эту кнопку
Скорее всего вам будет отправлено сообщение через Webhook с просьбой ответить с помощью нашего приложения в течение 2-х дней, поэтому следите за появлением новых диалогов
Теперь придется подождать проверки вашей интеграции сотрудником FB и подтверждения приложения.
После подтверждения приложения можно будет принимать сообщения из Messenger в наш чат и отвечать на него
Переходим в раздел Настройки / Расширенный обмен сообщениями нашей страницы
- Способ ответа = Все ответы дают люди
- Связанные приложения = добавим наше приложение
- Настройки приложения:
  - Основной получатель протокола передачи = выбираем наше приложение
  - Второстепенный получатель протокола передачи = Page Inbox
Проведите тестирование чата (администратор страницы не может писать в чат, т.ч. придется использовать другой аккаунт)

Код для сайта

Вы можете установить код на сайт, который показывает каналы, по которым с вами можно связаться. Можно настроить цвет основной иконки и её положение относительно нижнего правого угла сайта.

Отображаются только активные каналы.

Пример

Статистика

Для разработчиков

Плагин поддерживает расширение количества поддерживаемых каналов. В качестве шаблона можно использовать файл /php/Class/Providers/ExampleProvider.php

Для подключения дополнительного канала требуется создать новый класс {Канал}Provider на основе шаблона и реализовать в нем описанные методы, адаптированные для нового канала.

Основные методы класса

Метод "settingsForm" ( основной )

Метод выводит форму настроек канала. Метод выполняется при загрузке формы настроек.

public static function settingsForm( $id = 0 ) {
}

Загрузить сохраненные значения канала можно так:
$channel = Chats ::channelsInfo( $id );
id - id записи

Метод "check" ( основной )

Метод используется для проверки соединения. В результате можно заполнить какое-либо поле: название/id канала и т.п.

Метод "callbackServerConfirmation" ( основной )

Метод используется для подтверждения установленного url для Webhook

Метод "setWebhook" ( основной )

Метод используется для установки url для Webhook, если поддерживается. Вызывается при сохранении формы

Метод "deleteWebhook" ( вспомогательный )

Метод используется для удаления Webhook, если поддерживается. Не вызывается отдельно.

Метод "sendMessage" ( основной )

Метод используется для отправки текстового сообщения

Метод "sendFile" ( основной )

Метод используется для отправки вложений

Метод "deleteMessage" ( вспомогательный )

Метод используется для удаления сообщения, отправленного оператором, если поддерживается.

Метод "getUserInfo" ( основной )

Метод используется для получения информации о посетителе - Имя, Фамилия, ссылка на Аватар

Метод "eventFilter" ( основной )

Метод используется для обработки входящих на Webhook данных. Должен вернуть данные в заданном формате

Плагин: Чаты и мессенджеры