# О плагине

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

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

## Changelog

* 05.06.2024: **v.0.9 beta**
    - исправлено обновление информации о диалоге с сервера провайдера
    - исправлена обработка ошибок при несуществующем канале
    - исправлена прокрутка к последнему сообщению
    - произведен рефакторинг кода, код обновлен, устранены выявленные ошибки
* 16.05.2024: **v.0.8 beta**
    - исправлена работа интеграции с Viber
* 10.11.2021: **v0.7 beta**
    - исправлена работа с отправкой файлов
    - добавлен поиск в базе по номеру телефона во время начала диалога (для Whatsapp)
    - улучшена работа интерфейса
    - добавлена оптимизация БД (обновите плагин)
* 04.01.2021: **v0.6 beta**
    - исправление для поддержки MySQL 8.0
    - исправлено получение кода для установки кнопки на сайт
* 11.09.2020: **v0.55 beta**
    - исправление работы с каналом Whatsapp
    - дозагрузка имени, если оно не загрузилось ранее
    - загрузка аватара, если клиент впервые написал нам (впервые для сервера Whatsapp)
* 10.02.2020: **v0.51 beta**
    - добавлена адаптация под мобильные экраны
* 03.02.2020: **v0.5 beta** 
    - первый релиз beta-версии

### Прежде чем начать
>
>
> 1. Используйте только защищенное соединение ( https )
> 2. Самоподписанные сертификаты не поддерживаются ниодним провайдером (рекомендуем использовать сертификаты от Let’s Encrypt).
> 3. Ваш сервер должен быть доступен из Интернет, чтобы получать уведомления о новых сообщениях
> 4. Ваш сервер должен поддерживать работу модуля Apache Mod_Rewrite
> 5. Плагин не предназначен для рассылок сообщений - клиент должен написать первым
>
> При невыполнении данных условий подключение этого плагина бессмысленно

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

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

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

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

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

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

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

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

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


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

### WhatsApp через ChatAPI  <img src="assets/images/whatsapp.png" alt="messenger" width="20"/>

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

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

> **Для сведения**
> * Регистрация Webhook проводится в момент сохранения настроек канала автоматически.
> * Канал не поддерживает загрузку Аватаров клиентов

### Telegram  <img src="assets/images/telegram.png" alt="telegram" width="20"/>

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


### Viber  <img src="assets/images/viber.png" alt="viber" width="20"/>

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

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


### Vk.com <img src="assets/images/vk.png" alt="vk" width="20"/>

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

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

1. Заходим в раздел [Мои приложения](https://vk.com/apps?act=manage)
2. Жмем **Создать приложение**
3. Выбираем Платформу - **Standalone-приложение** и сохраняем
4. Заполняем Информацию о приложении. Тут важно:
    * Выбрать Сообщество - указать группу, которую будем подключать как канал
    * Желательно загрузить изображения для приложения
5. Переходим в Настройки приложения и 
    1. получаем параметры:
        * **ID приложения**
        * **Защищённый ключ**
        * **Сервисный ключ доступа**
    2. устанавливаем **Состояние** в положение "Приложение включено и видно всем"
    3. устанавливаем **Open API** в положение "Включено"
    4. сохраняем
    
**Шаг 2. Настройка группы**

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

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

1. Выбираем канал - Vk.com
2. Заполняем поля:
    - **ID приложения вконтакте** - из п. 5 предыдущего шага
    - **Секретный код приложения** - из п. 5 предыдущего шага
    - **Токен группы** - из п.6 предыдущего шага
    - **ID группы** - можно узнать из ссылки на группу
3. Нажимаем кнопку "Авторизация" ( зеленая )
4. Будет открыто новое окно ( если не блокируется браузером ), в котором вы должны будете разрешить доступ приложению к группе
5. Соглашаемся - нас перебросит на новую страницу с примерно таким текстом:
        > Пожалуйста, не копируйте данные из адресной строки для сторонних сайтов. Таким образом Вы можете потерять доступ к Вашему аккаунту. 
        
6. Именно данные из адресной строки нам и нужны, поэтому копируем параметр **access_token** - это вечный ключ доступа, который не требует периодического подтверждения доступа.
        > Пример данных адресной строки: https://oauth.vk.com/blank.html#access_token=<b class="red">d67d3sdfsdffdfsdfsdfdgcb0249d7fdb967fasdadasd64009c06c6559casdsatee4rfcdfb1b23d1sdfsdf895</b>&expires_in=0&user_id=2498989
        
7. Закрываем всплывающее окно, а полученный ключ копируем в поле **Токен приложения**
8. Нажимаем кнопку **Проверить** ( синяя ) - после нажатия:
    - Плагин свяжется с сервером Vk с указанными данными
    - Будет получен параметр **Callback Server ID** - он нужен для подтверждения адреса для Webhook
    - Будет заполнено Название группы
9. Сохраняем настройки
 
> **Для сведения**
> * Регистрация Webhook проводится в момент сохранения настроек канала автоматически.


### Facebook Messenger  <img src="assets/images/messenger.png" alt="messenger" width="20"/>

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

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

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

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

Плагин поддерживает расширение количества поддерживаемых каналов. Пример можно посмотреть в файле: /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 данных. Должен вернуть данные в заданном формате