Подключение каналов и сервисов

• Metabot Widget
• Metabot Widget и GTM
• Metabot Widget с диплинками
• Telegram
• Jivochat
• VK
• Umnico
• Подключение распознавания файлов в различных каналах
• Битрикс24
• Pyrus
• LiveTex
• Webim
• Viber

Metabot Widget

Создание канала

При создании и тестировании чат-бота можно воспользоваться быстрой и бесплатной настройкой чат-виджета от Metabot.

Первым делом, следует создать канал для общения с клиентами. Это место, где будут проходить все диалоги.

Для этого в меню Каналы создаем новый канал и из выпадающего списка в открывшемся окне Новая привязка к каналу выбираем Metabot Widget.

Затем сохраните введенные параметры настройки, нажав на кнопку Создать.

Конфигурация виджета и брендирование

Для кастомизации цветов доступны следующие параметры:

Если в поле attachment: icon указано 'default' то указываем SVG иконки прошитую в виджете, иначе будет указана HTTPS ссылка на картинку.

Эти параметры добавляются в код инициализации виджета, который вы можете взять в поле Код виджета канала.   

Например, вот так выглядит код виджета для бренда Metabot, который работает на нашем сайте https://metabot24.ru. Обратите внимание на новые параметры в методе init. 

<script type="text/javascript">
		(function (url)
		 {
			const callback = function () {

				let container = document.createElement('div');
				container.id = "metabot-ab8e2b168d216b1a6fa7b8d82c230f13";
				container.insertAdjacentHTML('beforeend','<div class="widget"></div>');
				document.body.appendChild(container);

				let showMessageDate = false;

				showMessageDate = ((date) => {
					const dateToFormat = new Date(date);
					const showDate = (dateToFormat.toLocaleDateString() === (new Date).toLocaleDateString()) ? '' : `${dateToFormat.toLocaleDateString()} `;
					return `${showDate}${dateToFormat.toLocaleTimeString('ru-RU', { timeStyle: 'short' })}`;
				});

				WebChat.default.init({
					selector: "#metabot-ab8e2b168d216b1a6fa7b8d82c230f13 .widget" 
					, customData: 'v3_metabotWidget_17_49_359_TvIxQdsegnJgJrMKktBtYbFkwcpmQIeJPDFabo'
					, locale: 'ru-RU'
					, title: 'Метабот'
					, subtitle: 'В сети ...'
					, initPayload: '/start'
					, inputTextFieldHint: 'Введите сообщение...'
					, inputTextTitle: 'Введите сообщение...'
					, showMessageDate: showMessageDate
					, params: {"storage": "local"}
					, socketUrl: 'https://app.metabot24.com:3000'
					, shortcut: []
					, mainColor: "#F69B1D" // Основной цвет
					, userTextColor: "#FFF" // Цвет текста на кнопке
					, userBackgroundColor: "#F69B1D" // Цвет фона кнопки				
				});
			};

			const head = document.head;
			const script = document.createElement('script');
			script.type = 'text/javascript';
			script.src = url;

			script.onreadystatechange = callback;
			script.onload = callback;

			head.appendChild(script);

		})("https://user43148.clients-cdnnow.ru/js/chatwidget/metabot_widget-1.3.4.js");
</script>

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

Размещение кода виджета на сайте

Асинхронное подключение чат-виджета

Для асинхронного подключения чат-виджета в настройках имеется поле Загрузчик. Оно становится доступным после первоначального сохранения настроек канала.

По команде Загрузить выполняется (пере-)генерация скрипта-загрузчика и загрузка его на CDN. Загружается скрипт, идентичный тому, что выведен в поле Код виджета выше. Соответственно при изменении настроек, влияющих на код виджета, следует перезагружать скрипт-загрузчик на CDN.

Metabot Widget и GTM

Настройка чат-виджета через Google Tag Manager (GTM)

Чтобы настроить чат-виджет через GTM нужно выполнить следующие действия:

1. Войти в Google аккаунт по ссылке https://tagmanager.google.com/.

2. Далее создать аккаунт как показано на рисунке ниже.

3. Заполнить контейнер и создать запись как показано на рисунке ниже.

4. В остальных диалоговых окнах согласиться и нажать кнопку ОК.

Если аккаунт GTM уже был создан, то достаточно в аккаунте добавить новый контейнер.

5. Добавить новый тег.

6. Нажать на кнопку в блоке Конфигурация тега.

7. Выбрать пункт Пользовательский HTML.

8. В административной панели платформы Metabot, необходимо создать подключение канала Metabot Widget (если ещё нет) и загрузить в CDN скрипт-загрузчик.

Запись должна быть отмечена зеленым значком со значением “200”.

9. Скопировать тело скрипта в буфер.

10. Продолжить заполнение тега в GTM, для этого выполнить по пунктам:

   10.1. Придумать имя тега.

   10.2. Вставить из буфера обмена скопированный скрипт.

   10.3. Создать GTM-триггер.

   10.4. Выбрать пункт All Pages.

   10.5. Нажать кнопку Сохранить.

11. В рабочей области нажать кнопку Отправить.

12. Заполнить форму указав название версии, например, ver1 и по желанию описание версии. Затем нажать кнопку Опубликовать.

13. После успешной публикации версии, вернуться в Рабочую область и открыть popup с кодами тег-менеджера.

14. Скопировать фрагменты кода в вставить в соответствующие разделы на сайте в head и body нужной html-страницы.

Ниже показан пример как это может выглядеть:

15. Открыть страницу сайта в браузере. Нужные скрипты подгружаются и виджет запускается.

Редактирование чат-виджета в GTM

При удалении и создании нового канала Metabot Widget на платформе, затем достаточно просто скопировать скрипт из блока Загрузчик и вставить его новой версией тега в контейнер GTM.

Для этого в аккаунте GTM открыть тег на редактирование.

Через функцию редактирования вставить скопированный скрипт и сохранить изменения, указав новое имя версии. Далее опубликовать новую версию.

Мы получим новую версию загруженного чат-виджета с платформы.

Таким образом без правки кода сайта мы можем переключать на различные версии чат-виджетов.

Metabot Widget с диплинками

Чат-виджет с диплинками

При создании и тестировании чат-бота в канале Metabot Widget необходимо провести первоначальные настройки виджета. Как это сделать подробно описано в статье Metabot Widget.

Здесь мы рассмотрим дополнительные настройки бота и виджета, которые позволят вам изучить метод настройки с диплинками.

Настройка маршрутов с диплинками

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

Также можно настроить на странице сайта кнопку с запуском диплинка и переходом в чат-виджет в соответствующий сценарий.

Рассмотрим пример:

Заполним следующие параметры:

Нажимаем кнопку Создать.

Аналогично создаем ссылки с именами: "Deeplink2" и "Deeplink3".

Результатом проделанных действий будут созданные 3 ссылки как на рисунке ниже.

ДЕМО-БОТ

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

ПОДДЕРЖКА

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

Тестовый бот - СЕРВИС ОПРЕДЕЛЕН - ДЕМО-БОТ

Должны быть активированы следующие свойства маршрута и заполнены соответствующие поля, также необходимо указать условие JS:

Тестовый бот - СЕРВИС ОПРЕДЕЛЕН - ПОДДЕРЖКА

Должны быть активированы следующие свойства маршрута и заполнены соответствующие поля, также необходимо указать условие JS:

Контроль автоопределения текущего раздела сайта выполняется с помощью V8 условий в маршруте с диплинком.

// Запуск диплинка ДЕМО-БОТ

var requestJson = null;
if (request) {
  requestJson = request.json;
}

var requestDeeplinkData = null;
if (requestJson && requestJson.deeplink) {
  requestDeeplinkData = requestJson.deeplink;
}

var requestService = null;
if (requestDeeplinkData && requestDeeplinkData.service) {
  requestService = requestDeeplinkData.service;
}

if (requestService === null || requestService === '') {
  return false;
}

var availServices = ['demo_bot'];
if (availServices.includes(requestService)) {
  return true;
} else {
  return false;
}

Далее в диплинке ТЕСТОВЫЙ БОТ мы определяем какой это сервис и запускаем необходимый скрипт.

Тестовый бот - СЕРВИС НЕ ОПРЕДЕЛЕН

Последним маршрутом с диплинком ТЕСТОВЫЙ БОТ и V8 условием идет маршрут, который запускает приветствие бота если сервис не распознан.

В нем условие можно и не писать, но в таком случае этот маршрут должен обязательно идти последним в списке.
На случай если кто-то случайно передвинет его выше в списке маршрутов, v8 просто не даст ему запуститься, если сервис ОПРЕДЕЛЕН.

// Запуск диплинка ТЕСТОВЫЙ БОТ, если сервис с сайта не передан или не определен

var requestJson = null;
if (request) {
  requestJson = request.json;
}

var requestDeeplinkData = null;
if (requestJson && requestJson.deeplink) {
  requestDeeplinkData = requestJson.deeplink;
}

var requestService = null;
if (requestDeeplinkData && requestDeeplinkData.service) {
  requestService = requestDeeplinkData.service;
}

if (requestService === null || requestService === '') {
  return true;
}

var availServices = ['demo_bot', 'support'];
if (availServices.includes(requestService)) {
  return false;
} else {
  return true;
}

Настройка чат-виджета с диплинками

Список диплинков указывается в виде json массива. В списке можно указывать макросы с названием ссылок или хэш код, если такой макрос не найден, то в поле диплинка будет подставлена строка как есть.

Дополнительной валидации правильности заполнения списка диплинков на платформе нет. Есть только общая проверка, что в поле введен json.

Автогенерация списка диплинков

В настройках канала Metabot Widget есть опция Автогенерация спиcка диплинков.

Если данная опция включена, то список диплинков заполненный вручную ниже не будет задействован.

Эта опция позволяет не заполнять список диплинков, они будут генерироваться автоматически при формировании кода виджета.

При автогенерации списка диплинков ссылки с диплинками будут выстроены в той же последовательности, как и в разделе Ссылки, поэтому в данном разделе имеется сортировка ссылок.

Генерация списка диплинков для заполнения вручную

Диплинки могут быть настроены в виде кнопок со ссылками или кнопки объединены в папки.

Настройка виджета с диплинками в виде кнопок со ссылками.

При такой генерации учитывается порядок ссылок бота, которые описаны в предыдущем пункте.

Для того, чтобы отредактировать список диплинков, необходимо открыть канал на редактирование по кнопке Редактировать.

Можно убрать лишние диплинки, блок настройки одного диплинка выделен на рисунке.

При предварительном просмотре чат-виджет имеет 3 кликабельные кнопки с диплинками перехода в сценарные скрипты.

Настройка виджета с диплинками объединенными в папки.

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

Рассмотрим несколько примеров:

• Внешняя ссылка — возможность перехода из чат-виджета в мессенджеры и соц.сети, где также будет диалог с чат-ботом или оператором, например, в Telegram;

 {
        "type": "link",
        "href": "https:\/\/t.me\/Stage_metabot_bot",
        "target": "_blank",
        "title": {
            "text": "переходи в Телеграм",
            "color": "#1B1C1E"
        },
        "icon": {
            "type": "url",
            "value": "https:\/\/app.metabot24.com\/uploads\/business\/34\/telegram_logo_icon_168692.png?nc=1689846288"
        }
    },

 "href": <ссылка на телеграм аккаунт бота с икранирующими \/ символами>

 "value": <ссылка на загруженный файл иконки с икранирующими \/ символами, картинку можно загрузить на платформу в разделе Магазин- Медиагалерея>

• Объединение диплинков в папки — различные кнопки с диплинками можно объединить/сгруппировать в папки;
  

  {
        "type": "folder",
        "title": {
            "text": "Сервисы тестового САЙТА",
            "color": "#ffffff"
        },
        "icon": {
            "type": "url",
            "value": "https:\/\/user43148.clients-cdnnow.ru\/img\/more.svg"
        },
        "data": [
            {
                "type": "deepLink",
                "event": {
                    "dataset": {
                        "deeplink": "{{ ^#Deeplink1 }}"
                    }
                },
                "title": {
                    "color": "#1B1C1E",
                    "background": "#1B1C1E",
                    "text": "ДЕМО-БОТ"
                },
                "background": "#E8F3FF"
            },
            {
                "type": "deepLink",
                "event": {
                    "dataset": {
                        "deeplink": "{{ ^#Deeplink2 }}"
                    }
                },
                "title": {
                    "color": "#1B1C1E",
                    "background": "#1B1C1E",
                    "text": "ПОДДЕРЖКА"
                },
                "background": "#E8F3FF"
            },
            {
                "type": "deepLink",
                "event": {
                    "dataset": {
                        "deeplink": "{{ ^#Deeplink3 }}"
                    }
                },
                "title": {
                    "color": "#1B1C1E",
                    "background": "#1B1C1E",
                    "text": "СТАРТ общий"
                },
                "background": "#E8F3FF"
            }
        ]
    },

• Кнопка с диплинком в теле чат-виджета:
  • Если лид новый и еще не общался с ботом в виджет;

{
        "type": "deepLink",
        "newConversation": {
            "title": {
                "color": "#1B1C1E",
                "text": "Начать диалог"
            },
            "subtitle": {
                "text": "Начать диалог с ботом"
            },
            "event": {
                "dataset": {
                    "deeplink": "someDeeplinkHashCode"
                }
            },
            "icon": {
                "type": "url",
                "value": "https:\/\/user43148.clients-cdnnow.ru\/img\/message_round.svg"
            }
        },

• • Если лид уже общался с ботом в виджете, то продолжение кода;

 "existConversation": {
            "title": {
                "color": "#1B1C1E",
                "text": "Продолжить диалог"
            },
            "subtitle": {
                "text": "Продолжить ранее начатый диалог"
            },
            "icon": {
                "type": "url",
                "value": "https:\/\/user43148.clients-cdnnow.ru\/img\/message_round.svg"
            }
        }

На виджете так 

• Кнопка в футере виджета:
  • Если лид новый и еще не общался с ботом в виджет;

  {
        "type": "actionOpen",
        "title": {
            "color": "#1B1C1E",
            "text": "Задать вопрос"
        },
        "event": {
            "dataset": {
                "deeplink": "E7tsR7VFWUGHKBgg"
            }
        },
        "icon": {
            "type": "url",
            "value": "https:\/\/user43148.clients-cdnnow.ru\/img\/message.svg"
        }
    },

• • Если лид уже общался с ботом в виджете, в кнопки можно добавить диплинки с переходом в нужные точки сценарной ветки чат-бота;
    

 {
        "type": "actionContinue",
        "title": {
            "color": "#1B1C1E",
            "text": "Задать новый вопрос"
        },
        "event": {
            "dataset": {
                "deeplink": "E7tsR7VFWUGHKBgg"
            }
        },
        "icon": {
            "type": "url",
            "value": "https:\/\/user43148.clients-cdnnow.ru\/img\/message.svg"
        }
    },
  

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

Настройка диплинков на сайте

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

Раздел Ссылки с типом ссылки Deep Link.

Например, на беке есть кнопки: Демо-бот, Поддержка и Старт общий, то для их настройки надо передать:

• ДЕМО-БОТ:

{"type":"deepLink","event":{"dataset":{"deeplink":"{{ ^#Deeplink1 }}"}},
"title":{"color":"#1B1C1E","background":"#1B1C1E","text":"Deeplink1"},"background":"#E8F3FF"}

• ПОДДЕРЖКА:
  

 {"type":"deepLink","event":{"dataset":{"deeplink":"{{ ^#Deeplink2 }}"}},
 "title":{"color":"#1B1C1E","background":"#1B1C1E","text":"Deeplink2"},"background":"#E8F3FF"} 

• СТАРТ общий:

 {"type":"deepLink","event":{"dataset":{"deeplink":"{{ ^#Deeplink3 }}"}},
 "title":{"color":"#1B1C1E","background":"#1B1C1E","text":"Deeplink3"},"background":"#E8F3FF"}

Telegram

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

Для настройки интеграции рекомендуется использовать ПК версию мессенджера Telergam.

В поиске по ID необходимо найти @BotFather.

В найденном боте следует открыть список команд и выбрать функцию /newbot.

Затем нужно ввести имя нового бота (то, что будет отображаться в Именной строке).

Название может быть на любом языке и может быть созвучно с вашим бизнесом. Например, primerbot.

Далее укажите ID для мессенджера (то, что будет использоваться для ссылки), оно может совпадать с именем бота для удобства.

Например, укажем со словом test test_rpimerbot.

Затем сохраните ID токена, который будет сгенерирован в Telegram, скопировать его полностью в буфер обмена.

Перейдите в Настройки бота в раздел подраздел Каналы.

Нажмите кнопку Новая привязка и выберите канал Telegram, вставьте токен.

Остальные параметры можете заполнить по желанию:

• Использовать inline-кнопки — вместо списка вариантов в боте будет выводиться inline-кнопка отдельно для каждого варианта из меню;
• Реакция на фото — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать фото отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для фото — контекст NLP для реакции на фото;
• Отключить Fallback для фото — при игнорировании фото, не активировать для него Fallback скрипт;
• Реакция на файлы (документы) — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать файлы отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для файлов (документов) — контекст NLP для реакции на файлы;
• Отключить Fallback для файлов (документов) — при игнорировании файлов, не активировать для них Fallback скрипт; 
• Реакция на видео — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать видео отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для видео — контекст NLP для реакции на видео;
• Отключить Fallback для видео — при игнорировании видео, не активировать для него Fallback скрипт;
• Реакция на аудио — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать аудио отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для аудио — контекст NLP для реакции на аудио;
• Отключить Fallback для аудио — при игнорировании аудио, не активировать для него Fallback скрипт;
• Реакция на голосовые сообщения — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать голосовые сообщения отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для голосовых сообщений — контекст NLP для реакции на голосовые сообщения;
• Отключить Fallback для голосовых сообщений — при игнорировании голосовых сообщений, не активировать для них Fallback скрипт;
• Реакция на стикер — в зависимости от выбора пункта из выпадающего списка, бот будет либо игнорировать стикеры отправленные пользователем, либо реагировать при помощи NLP или выводом меню;
• Контекст NLP для стикера — контекст NLP для реакции на стикеры;
• Отключить Fallback для стикера — при игнорировании стикера, не активировать для него Fallback скрипт.

Если оставить настройки файлов без изменений, то бот будет реагировать на них вызовом Fallback-а.

Нажмите кнопку Сохранить. Новая привязка создана и для завершения настройки необходимо нажать ссылку Вебхук.

Не забудьте сгенерировать Вебхук в поле Операции, иначе операция привязки бота к каналу не будет завершена.

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

Подключение к каналу Telegram завершено.

Теперь можно проверить запуск бота, набрав имя бота в мессенджере Telegram.

Нажмите кнопку Запустить. На экране должно появиться приветственное сообщение — это свидетельствует о правильности привязки канала.

Оформление карточки бота

Чтобы наполнить бота информацией необходимо выбрать раздел /mybots — edit your bots [beta] в сообщении с помощью или меню.

Выберите бота, которого хотите изменить и нажмите кнопку Edit Bot.

Далее выберите, что именно хотите изменить: название, описание или информацию о боте.

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

• Edit Name — меняет имя в главной строке. Введите новое имя и отправьте боту (замена моментальная);

• Edit Description — меняет первое сообщение, приглашающее к диалогу. Введите текст и отправьте боту (замена моментальная);

• Edit About —  меняет описание бота в карточке аккаунта. Введите описание, объем 120 символов (замена моментальная);

Команда Метабот очень просит своих клиентов указывать в описании сотрудничество, если это позволяет политика компании: Сделано вместе с @MetabotBot.

• Edit Botpic — меняет аватар аккаунта. Отправьте фото. Не файл, а именно фото через телефон любого формата, размером не менее 150х150 пикселей - замена моментальная. Какое-то время у бота может показываться галерея предыдущих аватаров, но через день галерея автоматически сбросится и останется только последнее отправленное фото;

• Edit Commands — меняет системные команды бота (замена моментальная).

Команды должны быть написаны латиницей, а описание можно написать кириллицей в формате:

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

Для того, чтобы команды работали с ботом в маршруте бота, который будет вызывать скрипт по команде регулярное выражение (код команды) должно быть написано с экранированием.

Также можно добавить маршрут рестарта, для корректного реагирования бота, в случае остановки-перезапуска бота в настройках Telegram.

Блокировка канала

На платформе реализована реакция на событие блокировки бота в Telegram, если приходит событие блокировки, то автоматически блокируется лид, включается параметр Отключение реакции боа на сообщения лида и сбрасывается беседа лида.

Также на платформе реализована реакция на событие разблокирования бота в Telegram (событие перезагрузки бота), Если приходит событие разблокировки, то автоматически у лида выключается параметр Отключение реакции боа на сообщения лида.

Далее после получения вебхука с разблокировкой приходит вебхук с текстом /start.

Jivochat

Интеграции сервиса Jivo с Metabot24 позволяет подключить бота в диалоги с клиентами в любых каналах связи. При этом, все новые диалоги вначале будут отправляться боту. По сценарию бот может переключить диалог на оператора.

Создание канала

Для подключения Jivo в меню Каналы создаем новый канал и из выпадающего списка в открывшемся окне Новая привязка к каналу выбираем Jivo.

После выбора канала в окне появятся дополнительные поля:

• Использовать inline-кнопки — по умолчанию выключено. При включении в чате пункты меню будут отображены в виде кнопок, а не текста;
• Коды виджетов — коды виджетов различных мессенджеров: 
  • Jivo Widget
  • Telegram
  • Viber
  • ВКонтакте
  • Instagram
  • WhatsApp
  • Facebook
  • Авито
  • Apple Business Chat
  • Одноклассники
• Использовать inline-кнопки для мессенджеров — по умолчанию Определяется общей настройкой канала. При включении в чате пункты меню будут отображены в виде кнопок, а не текста:
  • Jivo Widget
  • Telegram
  • Viber
  • ВКонтакте
  • Instagram
  • WhatsApp
  • Facebook
  • Авито
  • Apple Business Chat
  • Одноклассники
• ID провайдера канала — ID провайдера канала.

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

Все параметры кроме Использовать inline-кнопки пока можно оставить без изменений, по умолчанию и сохранить настройку.

После создания нажмите пункт Вебхук и скопируйте сгенерированный вебхук.

При копировании обратите внимание, чтобы не было вначале и в конце строки знаков «пробел».

Настройка Jivochat

После получения вебхука, вам необходимо будет зайти в приложение Jivo в раздел Управление, Каналы связи, добавить канал, например, Telegram.

После подключения канала проведите настройку раздела Настройки интеграции для разработчиков. Для этого необходимо включить опцию Включить Webhooks и заполнить поле URL для Webhooks вставить скопированный вебхук, полученный в Metabot.

Аналогично можно сделать настройку для виджета и всех подключенных каналов.

Перейдите по ссылке https://app.jivosite.com/settings/integrations/add-bot/31 и настройте расширение Metabot для подключения бота:

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

Токен бота можно найти на платформе в разделе Каналы:

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

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

На этом всё. Бот подключен и готов к работе. Мы рекомендуем вам провести несколько тестовых диалогов, чтобы убедиться в правильности настройки сценариев. Увидеть активность пользователей при взаимодействии с ботом вы можете в разделе Лиды в личном кабинете Metabot24.

Настройка включения кнопок по каналам связи

Если по части каналов не поддерживаются или не корректно работают кнопки, то необходима настройка выборочного включения кнопок по каналам связи Jivo.

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

Если мессенджер не определен, то параметр берется из глобальной настройки канала из параметра Использовать inline-кнопки.

Если мессенджер определен, по параметр берется из следующего перечисления:

• Определяется общей настройкой канала — установлен по умолчанию;
• Да — использовать в канале кнопки;
• Нет — не использовать в канале кнопки.

Проведем настройку кодов виджета и мессенджеров для определения наличия кнопок в мессенджере при обращении лида.

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

Для подключения сразу нескольких каналов к Jivo в одном боте можно сочетать регулярные выражения. Для этого нужно разделить их символами |||. Например: telegram|||^metabotjivo$

Если в Jivo настроена омниканальность, то могут возникнуть проблемы, поэтому рекомендуем подключать каждый мессенджер в Jivo как новый канал

Если у вас в ЛК Jivo не указан алиас, то в регулярном выражении канала Jivo по мессенджеру telegram следует указать дополнительно имя канала. Например: telegram|||^Test_bot*$

Заполнение контактных данных по лиду

После общения Лида (пользователя) с ботом можно в дальнейшем просмотреть его контактные данные: мессенджер, с которого общались, имя, телефон, email.

На сервисе Jivo эти данные можно посмотреть на вкладке Диалоги, зайдя в диалог:

Для просмотра этих данных на платформе Metabot24 следует выполнить следующие действия:

1. В истории сообщений хранится параметр widget_id, который является уникальным для каждого канала. По тестовому лиду перейдите в историю сообщений.

2. Далее перейдите по ссылке в webhooks-log.

3. В строках с параметрами в поле Event Type = chat_accepted/chat_finished/chat_updated необходимо открыть ссылку Show Formatted Payload.

4. Cкопируйте код параметра widget_id.

5. Откройте на редактирование канал Jivo в настройках бота, вставьте скопированный код в соответствующее поле мессенджера и сохраните настройки.

После этого при получении последующих CRM-вебхуков из этого канала для лидов будет прописываться соответствующий мессенджер, а также и все контактные данные из карточки лида отредактированные в сервисе Jivo.

Дополнительные возможности

• Bot API сервиса Jivo не поддерживает вложения, поэтому изображения и прочие вложения отправляемые с платформы Metabot24 клиенту приходят в виде текста URL:
  • Telegram автоматически делает такую ссылку активной и даже подгружает изображение;
  • Чат-виджет ссылку передает просто текстом и не кликабельной, поэтому ее можно только выделить и скопировать текст, далее вставить в адресную строку браузера;
• Если в настройках канала включить параметр Использовать inline-кнопки, то кнопки прорисовываются и становятся кликабельны;
• При подключении оператора в чат с лидом сервис Jivo отправляет сообщение в мессенджер о присоединении оператора к чату. При выходе оператора из чата сервис Jivo не отправляет никаких сообщений и в боте также не отображается, что оператор вышел из чата с лидом;
• После завершения чата оператором или если это произошло автоматически через определённое время простоя, теряется возможность отправки ботом сообщений в этот чат. Возможность возобновляется после перезагрузки данного чата оператором или лидом;
• Имеется возможность переключения на оператора с помощью команд в боте, обратно переключение на бота может сделать только оператор — Выйти из чата, но лид должен заново начать диалог, написав сообщение, иначе бот не возобновит работу;
• Если операторов нет онлайн, то при отправке сообщения приходит вебхук соответствующего события и в боте можно использовать вызов скрипта с типом Нет доступных операторов;
• При перенаправлении чата от одного оператора другому оператору, никаких событий от сервиса Jivo не поступает в Metabot24 и этот момент не обрабатывается на платформе, в бота не отправляются уведомительные сообщения;
• Рекомендуемые настройки канала, для отображения чата:
  • Можно настроить автоматические действия и поведение чат-бота при недоступности операторов, для этого в настройках канала в разделе Автоматические действия отключить все пункты и добавить новый пункт Показать чат-бот при самом первом посещении сайта, делается это с помощью кнопки Добавить действие;

  • В новом пункте указать следующие рекомендованные настройки по условиям:

    • Время на сайте;
    • Количество визитов;
    • Время от последнего активного приглашения;

  • При таких настройках окно чата будет показываться пользователю при первом посещении через 20 сек;

  • В разделе Форма контактов необходимо отключить запрос формы контактов клиента;

  • В разделе Кнопки в чате можно настроить поведение чата при условии, что пользователь еще ничего не написал. Это рекомендуется настраивать, чтоб при повторном обращении в бота спустя время, пользователь мог нажать на кнопку и активировать бота или при первом посещении чата - окно чата не было пустым.

Работа с Jivochat из JS

С каналами Jivochat можно работать из JS следующими методами:

Отправить markdown текст

Описание:

Используйте когда вам необходимо отправить форматированное сообщение в канал, например, когда вам нужно отправить ссылку в окно чат-виджета в виде гипертекстовой ссылки сайт вместо https://metabot24.ru.

Markdown передается через указание дополнительных параметров apiAdditionalParams для JS функции bot.sendText(). Если интеграция Jivochat с каналом не поддерживает markdown, то будет отправлена plain версия.

Пример:

let markdown = `Ознакомьтесь с нашим [каталогом плагинов](https://metabot24.ru/plugins/)`;
let plain = `Ознакомьтесь с нашим каталогом плагинов:  https://metabot24.ru/plugins/`;
bot.sendText(
  plain,
  {
    "message": {
      "type":"MARKDOWN",
      "content": markdown,
      "text": plain,
      "timestamp": Date.now(),
    }
  }
);

VK

Интеграция канала VK с платформой Metabot24

Для интеграции канала VK с платформой необходимо иметь в сообществе VK роль — Администратор.

Входим в аккаунт VK. Затем переходим в раздел Сообщества, на вкладку Управление и выбираем нужное для настройки канала сообщество.

Переходим в раздел Управление.

Здесь выбираем раздел Работа с API и нажимаем кнопку Создать ключ.

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

Копируем созданный ключ в буфер обмена.

Дальше следует перейти в административную панель платформы Metabot24. Для этого выполняем следующие действия:

1. Переходим в Настройки бота в подраздел Каналы.
2. Нажимаем кнопку Новая привязка и выбираем канал VK.
3. Вставляем скопированный ключ в поле Токен.
4. При необходимости включаем опцию Использовать inline-кнопки.
5. Форму пока не закрываем.

При включении опции Использовать inline-кнопки стоит помнить об ограничениях VK:  в меню должно быть не более 7 пунктов и наименование кнопок меню должно быль не более 20 символов с учетом пробелов между словами.

Переходим обратно в админ-панель VK в раздел Сообщения подраздел Настройки для бота. Опция Сообщения сообщества должна быть включена, остальные поля необязательны.

Далее переходим в раздел Настройки и копируем ID сообщества.

Возвращаемся в административную панель платформы Metabot24 и вставляем скопированное в поле ID сообщества. Сохраняем, нажав кнопку Создать.

Новая привязка создана и для завершения настройки необходимо нажать на кнопку Вебхук.

Не забудьте сгенерировать вебхук в поле Операции, иначе операция привязки бота к каналу не будет завершена.

Подтверждаем или отменяем выполняемую операцию. Версия формата вебхука по умолчанию = V3.

Подключение к каналу VK завершено.

Далее необходимо проверить работу бота, написав боту в VK сообщение.

Если в приложении появится новое сообщение от бота — это успех!

Umnico

Для интеграции сервиса Umnico с платформой Metabot24 необходимо в разделе Настройки -> API скопировать ваш API токен, нажав на кнопку Скопировать токен. 

Далее на платформе Metabot24 в настройках своего бота выполнить следующие действия:

• Перейти в настройки бота в раздел Настройки бота подраздел Каналы;
• Нажать кнопку Новая привязка и выбрать канал Umnico;
• В поле Токен вставить скопированный токен;
• В поле Логин менеджера вставить логин пользователя из Umnico и сохранить настройку.

Найти Логин менеджера можно на сайте Umnico.

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

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

Подключение к сервису Umnico завершено!

Подключение распознавания файлов в различных каналах

Редактирование настроек канала Metabot Widget

В канале Metabot Widget через редактирование необходимо:

1. Поставить активность чекбокса Разрешить отправку файлов.

2. В поле Список поддерживаемых расширений файлов добавить список разрешенных форматов файлов: 

3. Выбрать Только меню в поле Реакция на файлы (документы).

4. Сохранить настройки.

Редактирование настроек скрипта с типом Fallback

В название скрипта Fallback рекомендуем добавить “+ ФАЙЛЫ” для оперативного поиска в списке скриптов. Необходимо проверить корректность настроек NLP в скрипте.

Затем наполните скрипт командами:

• Первой командой должна идти команда Выполнить JavaScript, которая получает из вебхука событие: есть ли в сообщении с распознанным текстом файл и добавляет переменную is_attachment, что файл есть;

let whJob = bot.getWebhookJob()
let eventType = whJob.event_type

memory.setAttr('is_attachment', false)
if (eventType === 'user_attachments') {
  memory.setAttr('is_attachment', true)
  bot.disableRepeatMessageText() // погасит вывод сообщения с повтором вопроса 
  bot.hideRepeatMessageButtons() // погасит вывод меню с повтором вопроса
}

• Второй командой должна идти команда Выполнить JavaScript, которая фиксирует сам файл в хранилище и формирует ссылку для передачи в последствии в сообщениях/в письме на почту;

// Библиотека с помощью которой можно записать в карочку лида данные не отправля их в тг
let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()       

// Все входящие файлы
let attachments = bot.getAllAttachments()

if(Boolean(attachments?.[0]?.url)){

uploadData = bot.downloadFileFromUrl(attachments[0].url)
msg.debug('Пользователь отправил файл: ' + uploadData.url)
  
lead.setAttr('file', uploadData.url)
// Запуск скрипта...
bot.runScriptByCodeForLead("recieveFile", lead.getData('id'))
  
bot.stop()
}

• Третьей командой должна идти команда Выполнить JavaScript, которая срабатывает в случае, когда файла в сообщениях нет (проверка в условии).  JavaScript подбирает случайный ответ из списка, фиксирует дату сообщения, заносит в Google таблицу нераспознанный текст;

// Условие

return !(memory.getAttr('is_attachment')*1)

// JavaScript

var randomStrings = [
        "Не совсем понимаю, о чём вы.",
        "Извините, я вас не понял. Перефразируйте, пожалуйста.",
        "Попробуйте воспользоваться разделами меню или сказать другими словами.", 
        "Простите, не понял вас, попробуйте снова." 
    ];

randomIndex = Math.ceil((Math.random()*randomStrings.length-1));

lead.setAttr('randomAnswer', randomStrings[randomIndex]);
var ДатаСообщения = new Date(Date.now());

var ДатаСообщенияСтр =
    ДатаСообщения.getFullYear() + "-" +
    ("0" + (ДатаСообщения.getMonth()+1)).slice(-2) + "-" +
    ("0" + ДатаСообщения.getDate()).slice(-2);

var GoogleSheetsService = require('Common.Integrations.GoogleSheets') // Плагин для работы с Google Sheets

GoogleSheetsService.sheetId = '1pLbxTJG2YI6LghJ4FMCCBkQ7ybTL0Y7ZGw4yvaGCsQo' // ID скопированный из таблицы
GoogleSheetsService.listName = 'Рехау.Про' // Название листа

// Параметры где ключ - название столбца, значение - данные которые занесутся в строку
let params = {
    "Bot ID": botId,
    "Лид ID": leadId,
    "Время": ДатаСообщения,
    "Сообщение": bot.getIncomingMessage(),
}

let result = GoogleSheetsService.addRow(params) // Функция для добавления строк в таблицу

debug(result)

• Четвертой командой должна идти команда Отправить текст с рандомным текстом, которая срабатывает в случае, когда файла в сообщениях нет (проверка в условии);

// Условие

return !(memory.getAttr('is_attachment')*1)

• Пятой командой должна идти команда Отправить текст с текстом, которая срабатывает в случае, когда в сообщении есть файл (проверка в условии);

   

  // Условие
  
  return (memory.getAttr('is_attachment')*1)

  Текст команды

  Файл принят, передадим на изучения группе поддержки. С вами свяжутся либо через чат-бота, либо через имеющиеся контакты. А пока что можете воспользоваться автоматическим функционалом чат-бота.

• При необходимости шестой командой должна идти команда Email, которая срабатывает в случае, когда в сообщении есть файл (проверка в условии).  На почту отправляется письмо с файлом пользователя;

// Условие

return (memory.getAttr('is_attachment')*1)

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

• Последней командой должна идти команда Повторить вопрос.

Битрикс24

Создать новый портал Битрикс24 вы можете самостоятельно, просто перейдите по ссылке и пройдите регистрацию. Далее мы сможем вам помочь его настроить под ваш бизнес.

Настройка канала Битрикс24

Для интеграции портала Битрикс24 c платформой Metabot24 необходимо в настройках своего бота выполнить следующие действия:

1. В меню Настройки разделе Каналы создать новый канал, нажав на кнопку Новая привязка.

2. Далее в диалоговом окне выбрать из списка канал Bitrix и нажать кнопку Создать, оставив остальные поля не заполненными.

3. Новая привязка создана, далее необходимо нажать ссылку Вебхук.

4. Подтвердить выполняемую операцию.

5. Обновить страницу Привязка к каналам и скопировать созданный вебхук.

6. Перейти на свой портал Битрикс24 в раздел Приложения, в подраздел Разработчикам. Далее раздел Готовые сценарии, в подразделе Другое, выбрать Локальное приложение.

Настройки интеграции в Битрикс24 должен проводить пользователь с правами Администратор.

7. В открывшемся диалоговом окне на вкладке Серверное установить параметр Использует только API.

8. Далее добавить следующие параметры:

• Путь вашего обработчика* —  вставить скопированный вебхук с платформы Metabot24;
• Путь для первоначальной установки — вставить скопированный вебхук с платформы Metabot24;
• В блок Настройка прав добавить разделы:
  • CRM;
  • Чат и уведомления;
  • Создание и управление Чат-ботами;
  • Пользователи;
  • Списки;
  • Открытые линии.

9. После проверки всех указанных параметров нажать на кнопку Сохранить.

10. Последовательно скопировать Код приложения (client_id) и Ключ приложения (client_secret) обратно в настройки привязки к каналам на платформе.

11. Для этого перейти на платформе в раздел Настройки -> Каналы и открыть канал Bitrix для редактирования.

12. Вставить последовательно скопированные Код приложения и Ключ приложения и сохранить данную настройку, нажав кнопку Сохранить.

Если все сделано правильно, то настроенный канал Bitrix будет выглядеть следующим образом.

Настройка Открытых линий в Битрикс24

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

Создавать Открытые линии может администратор Битрикс24 в Контакт-центре – нужно всего лишь выбрать любой канал. Итак, рассмотрим подключение Открытой линии на примере канала Telegram.

Как провести подключение канала, можно ознакомиться в инструкции Битрикс24 или обратиться в нашу службу поддержки по удобному каналу связи на странице Помощь.

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

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

На вкладке Автоматические действия также рекомендуем провести настройки по отключению автоматических сообщений.

Настройка статусов

После настройки интеграции канала необходимо выполнить синхронизацию статусов. В меню Настройки разделе Статусы выполните следующие действия:

1. Нажмите кнопку Синхронизация.
2. Подтвердите или отмените выполняемую операцию.

Следует помнить, что изначально рекомендуем в боте наименования статусов устанавливать идентично используемым по воронке статусам справочника Лиды в Битрикс24.

Синхронизация завершена успешно, если в списке Статусов появятся записи с заполненным полем Внешний ID, которое является идентификатором статуса в Битрикс24.

Работа бота в Открытой линии

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

В Битрикс24 данный диалог можно открыть из карточки лида.

Pyrus

Интеграция сервиса Pyrus с Metabot позволяет подключить бота в задачи по Формам в любых каналах связи. При этом, все новые диалоги вначале будут отправляться боту. По сценарию бот, предварительно собрав информацию и запросив контактные данные, далее может переключить диалог на оператора.

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

Настройка аккаунта

Для подключения интеграции Pyrus нужен аккаунт на Metabot Platform. Регистрация аккаунта (бизнеса) бесплатная и далее тарификация зависит от активности пользователей в боте.

Создайте чат-бота в своем аккаунте, придумав ему название и проставив все необходимые настройки.

Уроки с шаблонами можно посмотреть в документации Metabot, там же вы найдете инструкции по подключению бота в каналы.

1. Для настройки интеграции с Pyrus в бизнес-аккаунте должен быть создан пользователь с правами доступа Пользователь API, для этого обратитесь в службу поддержки Metabot через раздел Связаться с нами или через виджет на платформе оставить обращение. 

2. В разделе Пользователи бизнеса для появившегося пользователя сгенерируйте API-токен, нажав соответствующую кнопку. Скопируйте и сохраните появившийся в зеленом информационном окне токен.

3. Перейдите в раздел Настройки бота — Внутреннее API.

4. Создайте endpont (конечную точку) с алиасом — pyrus.

5. Скопируйте получившуюся ссылку: https://app.metabot24.com/api/v1/bots/{bot_id}/call/{alias} — замените в ней bot_id на ID своего бота.

Для того чтобы узнать ID, необходимо нажать на редактировать бота в списке ботов и скопировать его ID (это число расположенное в url между /bot/ и /edit). А алиас нужно заменить на pyrus (без фигурных скобок).

let webhook = request.array

let alias = webhook?.alias
let leadId = webhook?.channel_id
let eventType = webhook?.event_type

switch (alias) {

    case ("sendmessage"):

        bot.runScriptByCodeForLead("pyrus_callback", leadId, null, false, {
            "script_request_params": webhook
        })

        break

    case ("event"):

        leadId = findMetabotLeadId(webhook?.mappings)

        // Если тип close
        if (eventType == "Close") {
            bot.runScriptByCodeForLead("pyrus_close_task", leadId, null, false, {
                "script_request_params": webhook
            })
        }

        break

}

return {
    "result": true
}

function findMetabotLeadId(mappings) {
    let result = mappings.find(mapping => mapping.code === "MetabotLeadId")
    if (result) {
        let value = result.value.split(',')[0]
        return parseInt(value, 10)
    }
    return null
}

Номер формы будет отображен после подключения аккаунта в Pyrus.

6. Сохраните создание эндпоинта.

Настройка чат-бота

В списке скриптов создайте отдельный раздел для команд, которые будут работать в связке с эндпоинтом.

Название раздела и скриптов может быть произвольным, но коды ОБЯЗАТЕЛЬНО нужно перенести в предлагаемом виде:

• pyrus_callback — запускает перевод на общение из задачи;
• pyrus_close_task — завершает диалог и возвращает в бота.

В скрипте перевода диалога на Pyrus необходимо создать: команду Выполнить JavaScript Callback с кодом:

require('Common.DB.Select')
let db = CommonDBSelect

let pyrus = require("Common.Integrations.Pyrus")
let pyrusRequestData = request.array

pyrus.accountId = bot.getAttr("sys_pyrus_account_id")

let attachments = bot.getAllAttachments()
let guiIds = []
let mappings = lead.getJsonAttr("mappings")

let whJob = bot.getWebhookJob()
let eventType = whJob.event_type

// Если из виджета, достаём по другому
if (eventType === 'user_attachments') {
  attachments = JSON.parse(whJob.payload)?.payload?.attachments || []
}

if (attachments.length) {

    for (let i = 0; i < attachments.length; i++) {

        let url = attachments?.[i]?.url
        let giuId = pyrus.getGuiIdFile(url)
        guiIds.push(giuId)

    }
}


switch (true) {
    case Boolean(Object.keys(pyrusRequestData).length):
        let messageText = pyrusRequestData?.message_text || ""
        let attachmentIds = pyrusRequestData?.attachment_ids || []

        if (attachmentIds.length) {

            let messageAttachments = pyrus.getFileUrl(attachmentIds[0]) // todo: Сдлеать передачу всех файлов и возврат массива через for
            let sendAttachmentData = [{
                "type": "file",
                "url": messageAttachments?.url
            }]

            bot.sendMessage(`Оператор ${pyrus.getOperatorName()}: Файл`, [], sendAttachmentData)
          
            if (bot.getLastResultPayload()?.ok == false) {

                pyrus.sendMessage(`Файл ${attachmentIds[0]} не доставлен. Попробуйте изменить формат, сжать или отправить ссылку`, [], [], "БОТ")
            }

            return false

        } else if (messageText === "/stop") {
            pyrus.setForwarded(false) // Показываем, что диалог возвращён боту
            bot.sendMessage("Диалог с оператором завершён")
            bot.runScriptForLead(3137, leadId)
            pyrus.sendMessage(`Диалог с пользователем завершён`, [], [], "БОТ")

        } else if (messageText.includes("/go")) {
            let numberPattern = /\d+/
            let numberMatch = messageText.slice(messageText.indexOf("/go") + 3).match(numberPattern)
            let scriptCode = parseInt(numberMatch[0], 10)

            pyrus.setForwarded(false) // Показываем, что диалог возвращён боту
            bot.sendMessage(`Оператор ${pyrus.getOperatorName()} перевёл вас в сценарий бота.`)
            bot.runScriptForLead(scriptCode, leadId)
            pyrus.sendMessage(`Диалог с пользователем завершён. Пользователь переведён на выбранный сценарий`, [], [], "БОТ")

        } else {
            bot.sendMessage(`Оператор ${pyrus.getOperatorName()}: ${messageText}`)
        }
        break


    default:
        let incomingMessage = bot.getIncomingMessage()
        
        if (isFirstImmediateCall){
            bot.sendMessage("Перевод диалога на оператора")
            incomingMessage = "Пользователь отправил новый вопрос"         
        }
    
        if (checkIncomingMessage(incomingMessage)) {
            bot.runScriptForLead(3137, leadId)
        } else if (pyrus.isForwardedToOperator()) {
            pyrus.sendMessage(incomingMessage, mappings, guiIds)
        } else {

            // Примечанеи: Если оператор небыл подключен ранее, то диалог достанется с даты создания лида. Если был, то с даты завершения диалога. Либо с даты которую передадите в функции
            let lastCommunicateDate = pyrus.getLastCommunicateDate()
            let lastMessages = db.getMessagesByDate(lastCommunicateDate)
            pyrus.sendGroupMessages(lastMessages)

            if (guiIds.length) {
                pyrus.sendMessage(incomingMessage, [], guiIds) // Отправляем последнее сообщение с файлами
            }
          
            if (mappings.length) {
                pyrus.sendMessage("Поля формы обновлены", mappings) // Отправляем поля
            }
        }
        pyrus.setForwarded(true) // Показываем, что диалог передан оператору Pyrus
        return false
}

// Проверка слова на совпадения
function checkIncomingMessage(word) {
    const patterns = [
        /^бот$/,
        /^меню$/,
        /^\/start$/
    ];
    
    word = word.toLowerCase();
    
    for (let pattern of patterns) {
        if (pattern.test(word)) {
            return true;
        }
    }
    
    return false;
}

В коде используется функция pyrus.getOperatorName(), которая возвращает значение — "Имя" или пустое значение. Также в коде callback есть текст "Оператор", который можно заменить на значение на любом языке, это используется в мультиязычных чат-ботах и когда интерфейс pyrus отличен от русского.

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

Именно этот скрипт отвечает за беспрерывное общение в задаче.

И завершить его может либо кодовые слова, прописанные в переменной patterns, либо закрытие задачи, которое можно настроить в боте с переводом в любой сценарий.

Если вы хотите, чтобы ваш бот в Telegram мог принимать файлы (фото, аудио и т.д.), не забудьте указать это при создании канала.

Далее настройки следует произвести в самом Pyrus.

Настройка расширения в Pyrus

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

Бот преобразует ваши разговоры в любом канале, подключенном на платформе Metabot в комментарии к задачам в Pyrus и позволяет вам управлять ими так же, как и обычными задачами.

Сотрудники смогут отвечать клиентам из Pyrus прямо в тот канал связи, в котором ранее обращался пользователь (Telegram, Viber, VK, WhatsApp, виджет на сайте), завершать задачи, добавлять других участников в разговор и использовать любой другой функционал Pyrus.

Чтобы сообщения клиентов из чат-бота попадали в задачи Pyrus, подключите расширение Metabot к нужной форме — новой или уже существующей.

Перейдите в настройки формы и в списке расширений найдите Metabot и нажмите Подключить.

В настройках расширения необходимо указать Эндпоинт Metabot и Токен.

В поле Эндпоинт Metabot вставляем ссылку, которую берём во внутреннем API (https://app.metabot24.com/api-internal-endpoints) с предварительно измененными параметрами в п.3.

В поле Токен вставляем значение, которое генерируем в разделе Пользователи бизнеса https://app.metabot24.com/user, в п.2.

Нажмите кнопку Подключить аккаунт.

Генерируется номер аккаунта, это значит что аккаунт успешно подключен.

Номер формы — это цифры после Account.

Теперь, когда клиент будет общаться с ботом, вы получите его в Pyrus. А ваши ответы он увидит в сообщениях в том канале связи, в котором он общался с ботом.

Все API запросы будут записываться в Лог.

Логи можно обрабатывать с помощью JS кода в блоке эндпоина, который вы указали.

Возможности интеграции

Отправлять и принимать сообщения

При запуске на платформе Metabot скрипта callback_pyrus происходит следующее:

• Если это был первый запрос пользователя, то при переходе диалога в Pyrus вся история его переписок поступит комментарием в задачу по Форме, к которой подключено расширение. В блок с отправкой сообщений пропишется имя аккаунта и мессенджер;

  

• Если это не первый запрос пользователя, то отправиться только само сообщение от пользователя;
• Если менеджер закрыл диалог с пользователем, т.е. закрыл задачу, нажав на кнопку Завершить, а человек подал новый запрос, то загружается вся история с момента последнего диалога;

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

• Если менеджер закрыл диалог с пользователем, прошло время больше количества часов/дней, которые были указаны в настройках Формы и пользователь задал вопрос повторно, то создается новая задача без истории;

Часы/дни можно изменить в настройках формы. 

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

• Файлы можно отправлять в чат-бот и принимать из чат-бота в каналах связи: Telegram и Виджет на сайте только в том случае, когда открыт диалог с пользователем;

• На платформе можно настроить Маршрут бота с регулярными выражениями. Например, когда пользователь пишет “бот" или “меню" (без кавычек), то для его диалога запускается скрипт с меню и обновляется атрибут, в котором указывается что диалог закрыт.

Работа менеджера

• Менеджер из задачи в Pyrus может останавливать диалог, написав команду — /stop;

Пользователю отправляется сообщение, что его диалог Завершен и запускается скрипт Главного меню. Задача в Pyrus при этот действии не закрывается.

• Менеджер из задачи в Pyrus может переводить пользователя в определенную точку сценария на запуск скрипта, написав команду — /go + ID<скрипта>;
• В диалоге пользователя в мессенджере отображается Ответственный менеджер, который ведет в донное время диалог с пользователем.

Имя оператора меняется после смены Ответственного в Pyrus и после отправки сообщения пользователем.

Закрытие задачи

При закрытии менеджером задачи по кнопке Завершить, она закрывается и на платформе Metabot. Пользователю отправляется сообщение и запускается скрипт Главного меню.

Запрос и передача данных

Для того чтобы передать контактные или запрошенные у пользователя данные в соответствующие поля задачи по Форме, необходимо сохранить эти данные в переменную mappings.

let mappings = [{
        "code": "SenderName",
        "value": lead.getAttr('clientName')
    }, {
        "code": "Subject",
        "value": "Задача: " + lead.getAttr('Задача')
    }, {
        "code": "PhoneNumberFrom",
        "value": lead.getAttr('sys_phone')
    },
    {
        "code": "SenderEmail",
        "value": lead.getAttr('sys_email')
    },
    {   "code": "CustomFields1",
        "value": lead.getAttr('источник')
    },
    {
        "code": "Message",
        "value": "Компания: " + lead.getAttr('company') + '\n' +
                 "Сфера деятельности: " + lead.getAttr('Ниша')
    },
    {
        "code": "MetabotLeadId",
        "value": leadId.toString()
    }
]

lead.setJsonAttr("mappings", mappings)

Как получить коды полей code

1. Перейдите в раздел Формы.
2. Выберите необходимую форму.
3. Перейдите в раздел Настройки.
4. Откройте вкладку Шаблон.
5. В настройках шаблона просмотрите или измените коды полей.

На данный момент доступны ТОЛЬКО следующие типы полей с соответствующими кодами:

- SenderName — Имя отправителя;
- Subject — Тема сообщения;
- PhoneNumberFrom — Телефон клиента;
- SenderEmail — Эл. почта клиента;
- Message — Описание;
- Attachments — Файлы;
- MetabotLeadId — MetabotLeadId (передача ID лида Metabot, с которым связана задача) обязательное поле;
- OpenOrClose — Открыта / Завершена.

5 кастомный текстовых поля, которые можно переименовать, сохранив коды без изменений:

• CustomFields1 — Кастомное поле 1, тест;
• CustomFields2 — Кастомное поле 2, тест;
• CustomFields3 — Кастомное поле 3, тест;
• CustomFields4 — Кастомное поле 4, тест;
• CustomFields5 — Кастомное поле 5, тест.

Все остальные добавляются по запросу.

Обязательным для заполнения полем является только поле MetabotLeadId, менять код поля запрещено! По  сопоставлению данного поля происходит связка лида в Метабот и в Pyrus.

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

В текущей настройке расширения доступны следующие переменные, которые будут записаны в соответствующие поля формы.

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

При передаче и обновлении данных в Pyrus отображается комментарий по данному действию.

Работа в Форме задачи в Pyrus

При переводе диалога из канала связи чат-бота в Pyrus, в преднастроенной форме создается задача. В блоке Форма по полям прописываются переменные, которые собраны ботом в ходе диалога при текущем обращении пользователя или при ранее созданных обращениях. Эти переменные хранятся на платформе Metabot и передаются в Pyrus в момент работы скрипта интеграции. 

Ответственный менеджер ведет переписку с пользователем в блоке Metabot.

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

LiveTex

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

История диалогов с ботами автоматически сохраняется в архиве.

Подключение интеграции

Создайте новый аккаунт LiveTex или войдите в существующий.

Если аккаунт только создан, то необходимо активировать пробный период.

В разделе Главная необходимо добавить новую точку контакта.

Нажмите на кнопку Добавить.

Новая точка контакта должна быть с типом Messaging API, наименование можно указать произвольное.

Нажмите на кнопку Ключ доступа и сгенерируйте ключ доступа.

У созданной точки необходимо скопировать ключ доступа. 

На платформе Metabot24 в настройках своего бота необходимо выполнить следующие действия:

1. Перейти в раздел Настройки бота подраздел Каналы.
2. Нажать кнопку Новая привязка и выбрать канал LiveTex (Chat Center).

В диалоговом окне указать следующие параметры:

• Канал — по умолчанию подставляется наименование создаваемого канала;
• Заголовок сообщений бота — произвольная фраза, которая будет отображаться в чат-центре над сообщениями от Бота, рекомендуем вставить эмодзи для визуальной наглядности;
• Заголовок сообщений лида — произвольная фраза, которая будет отображаться в чат-центре над сообщениями от Лида, рекомендуем вставить эмодзи для визуальной наглядности;
• Исключаемые каналы — установить активность чекбокса на тех каналах, которые не должны попадать в чат-центр LiveTex:
  • Umnico, Bitrix, Jivo, Webim — каналы, в которых реализованы чат-центры, рекомендуем на них установить активность чекбокса;
  • Telegram, Metabot Widget, Viber, Vk — прямые каналы, которые можно объединить в чат-центр LiveTex;
• Токен — скопировать из буфера обмена ключ доступа сгенерированный при создании точки контакта в LiveTex.

Сохранить настройки.

Далее нажмите пункт Вебхук, тем самым Metabot24 через API настроит канал на отправку оповещений.

Настройка чат-центра

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

Произведите настройки аккаунта LiveTex для дальнейшей интеграции с платформой Metabot24, перейдя в раздел Настройки, подраздел Сотрудники, добавьте дополнительных операторов, нажав на кнопку Добавить сотрудника.

Далее в разделе Настройки подразделе Маршрутизация на правой секции Сотрудники группы добавить заведённого сотрудника в список, нажав кнопку Добавить. В левой секции по умолчанию только одна группа Группа для Messaging API.

На текущий момент в Metabot24 при работе с LiveTex выбирается первая группа по порядку (не по имени или коду), то есть заложен функционал работы с одной группой.

После подключения канала все сообщения пользователя начинают отправляться в LiveTex. При этом, если по сценарию взаимодействие происходит с Ботом, то есть не выполнен перевод на Оператора, то Операторы не видят эти сообщения в LiveTex. История переписки появляется у Оператора только после переключения диалога с бота.

Дополнительные возможности

1. Реализована поддержка следующих типов сообщений с платформы Metabot24:

• Текстовое сообщение;
• Передача изображений, видео;
• "Меню", выводится в виде текста;
• Вложения различных типов.

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

2. При переводе диалога на Оператора пользователь получает сообщение Диалог переведён на оператора. Далее при прочтении первого сообщения Оператором пользователь получает сообщение Оператор <имя оператора> подключился к диалогу.

3. Поддерживается перевод чатов между Операторами. Если был произведён перевод чата на другого оператора, то после прочтения диалога опять выводится сообщение Оператор <имя оператора> подключился к диалогу.

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

5. На платформе Metabot24 поддерживается функциональная возможность передачи атрибутов Лида для LiveTex. Для этого имеется функция setLiveTexAttr.

Все переданные атрибуты будут отображены в шапке диалога в LiveTex. Пример вызова:

attr = {
 'номер_заявки': 705,
 'имя_заявки': 'Test',
 };
 lead.setLiveTexAttr(attr);

Функция записывает данные параметры в атрибуты лида с ключом sys_livetex_attrs с типом system. При переводе диалога на Оператора они считываются и передаются в LiveTex.

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

7. Имеется возможность выполнить проверку доступности операторов и после этого определить, какой скрипт запустить с типом Перевод на оператора (онлайн) или Перевод на оператора (оффлайн).

Каналы связи LiveTex

На текущий момент LiveTex обеспечивает следующий список каналов связи для возможного подключения:

Webim

Интеграции сервиса Webim с Metabot24 позволяет подключить бота в диалоги с клиентами в любых каналах связи. При этом, все новые диалоги вначале будут отправляться боту. По сценарию бот может переключить диалог на оператора.

История диалогов с ботами автоматически сохраняется в архиве.

Подключение интеграции

Создайте новый аккаунт Webim или войдите в существующий.

Произведите настройки аккаунта Webim для дальнейшей интеграции с платформой Metabot24, перейдя в раздел Отделы:

Для реализации работы с переводом на оператора необходимо создать в аккаунте Webim, как минимум 2 отдела: 

1. Один отдел с сотрудником без бота.
2. Второй отдел с ботом. Для того, чтобы по умолчанию диалог стартовал с ботом, надо ему выставить более высокий приоритет в поле Порядок сортировки.

Например, можно произвести минимальные настройки отделов в такой форме:

Далее перейдите в раздел Сотрудники:

Для работы необходимо зарегистрировать как минимум 3-х сотрудников:

1. Первый сотрудник, он же может быть и администратором аккаунта Webim, должен быть включен в отдел Операторы.
2. Второй сотрудник, через которого будет работать бот, должен быть включен в отдел бот, с наивысшим приоритетом в поле Порядок сортировки.
3. Третий сотрудник, это будет оператор, на которого будет переводиться диалог, должен быть включен в отдел Операторы.

Для регистрации нового сотрудника нажмите кнопку Зарегистрировать нового сотрудника:

Далее перейдите в раздел Боты:

Нажмите кнопку Создать нового бота и установите первоначальные настройки.

В диалоговом окне указать следующие параметры:

• Оператор для бота — указать имя сотрудника, под которым будет работать бот;
• Тип бота — Умный бот;
• Порядок сортировки — по умолчанию 100;
• Версия — указать параметр 2;
• Ссылка на внешний API — указать любое значение, например, https://ya.ru, в дальнейшем будет редактироваться;
• Токен авторизации — будет заполнен автоматически после сохранения настроек.

Сохранить настройки.

Скопируйте в буфер обмена токен из меню Редактирования бота, который сгенерируется после создании бота в Webim:

На платформе Metabot24 в настройках своего бота необходимо выполнить следующие действия:

Перейти в раздел Настройки бота подраздел Каналы;

Нажать кнопку Новая привязка и выбрать канал Webim.

В диалоговом окне указать следующие параметры: 

• Имя хоста — это адрес, который отображается при входе в личный кабинет Webim в адресной строке браузера. Вводится без протокола и закрывающей косой, например, metabot3.webim.ru.;
• Логин — логин администратора учётной записи Webim;
• Пароль — пароль администратора учётной записи Webim;
• Код отдела для перевода на оператора — буквенный идентификатор отдела, на который будет переведен диалог при вызове команды Перевести на оператора. Код отдела отображается в Webim на странице редактирования отдела, например, operatory:
• Установить активность параметра Использовать inline-кнопки;
• Токен — вставить из буфера обмена токен сгенерированный при создании бота в Webim.

Сохранить настройки.

Далее нажмите пункт Вебхук и скопируйте сгенерированный вебхук. При копировании обратите внимание, чтобы не было в начале и в конце строки знаков «пробел».

Перейдите в личный кабинет Webim в раздел Боты и нажмите редактирование бота:

В поле Ссылка на внешний API вставьте скопированный вебхук с платформы Metabot24 и сохраните настройки.

Настройка каналов общения

После подключения интеграции с Metabot24 необходимо произвести настройку каналов общения в Webim. Для этого перейдите в раздел Общие настройки:

Перейдите в подраздел Каналы общения и произведите настройки каналов, согласно документации и рекомендациям Webim, например, Telegram:

Необходимо указать название бота и скопировать токен из @BotFather и сохранить настройки. Бот подключен.

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

• Начало чата — к адресу на конце надо дописать "?event=chat_started" без кавычек; 
• Подключение оператора — к адресу на конце надо дописать "?event=chat_assigned" без кавычек;
• Завершение чата — к адресу на конце надо дописать "?event=chat_closed" без кавычек.

Сохранить настройку.

На этом всё. Бот подключен и готов к работе. Мы рекомендуем вам провести несколько тестовых диалогов, чтобы убедиться в правильности настройки сценариев. Увидеть активность пользователей при взаимодействии с ботом вы можете в разделе Лиды в личном кабинете Metabot24.

Дополнительные возможности

Если чат переведён на оператора, для того чтобы вернуть его обратно на бота, нужно в панели Webim начать набирать ответный текст. При этом появляется функциональная кнопка Перенаправить, нажав на которую нужно выбрать оператора, на которого настроен бот. 

Реализована поддержка следующих типов сообщений с платформы Metabot24:

• Текстовое сообщение;
• Кнопочное меню;
• Вложения различных типов.

Если чат переведен на оператора лидом или ботом через скрипт на платформе, то диалог должен закрыть оператор по кнопке Закрыть или он закроется автоматически по таймеру — Тайм-аут автозакрытия чата с момента последней активности. Таймеры настраиваются в разделе Общие настройки, подраздел Тайм-ауты и сообщения:

После выполнения тайм-аута окончательного закрытия чата, если по лиду установлен параметр Чат передан оператору, то данный признак сбрасывается и выполняется скрипт с типом Возврат.

Каналы связи Webim

На текущий момент Webim обеспечивает следующий список каналов связи для возможного подключения:

Размещение чата на сайте

Для того, чтобы получить код чата для размещения на сайт, необходимо перейти в раздел Настройки — Кнопки и размещения:

В блоке Код для сайта размещен HTML-код, который необходимо вставить в код веб-страниц вашего сайта, лучше всего в шаблон.

Параметр Обращение для отдела необходимо оставить по умолчанию без отдела.

Viber

Создать новый или настроить существующий бот Viber можно по ссылке: https://partners.viber.com/account/create-bot-account 

Для интеграции канала Viber c платформой Metabot24 необходимо зайти в аккаунт Viber по ссылке выше и в открывшемся блоке Создать бот установить следующие параметры:

• Account Image — картинка, которая будет являться аватаркой бота;
• Account Name — имя вашего бота латинскими буквами или на английском языке;
• Url — заполняется автоматически по имени бота;

Внимание!!! Поле Url в дальнейшем изменить нельзя, не редактируемое.

• Category — категория вашего бизнеса;
• Language — используемый язык;
• Account Description — описание вашего бота;
• Website Address — адрес вашего сайта. Не обязательное для заполнения;
• Email Address — адрес электронной почты;
• Location — местоположение вашей компании на карте.

Далее активируйте все чекбоксы и нажмите кнопку Create.

В информационной окне появится токен нового бота, его необходимо скопировать в буфер обмена.

Если бот уже ранее был создан и подключается к Metabot24, то необходимо скопировать ранее созданный токен.

Далее перейдите в настройки бота в раздел Настройки бота подраздел Каналы.

Нажмите кнопку Новая привязка и выберите канал Viber, вставьте токен и сохраните настройку.

Если у вас бот с меню самообслуживания, то можно установить активность параметра Использовать inline-кнопки.

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

Подключение к каналу Viber завершено.

Вы можете разместить на сайте кнопку со ссылкой на вашего бота в Viber, например, viber://pa?chatURI=metabot24, где metabot24 — это url вашего бота.