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

Metabot Widget

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

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

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

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

image.png

После выбора канала в окне появятся дополнительные поля:
  • Версия формата вебхука — по умолчанию V3, менять не рекомендуется;
  • Использовать Inline-кнопки — по умолчанию выключено. При включении в чате пункты меню будут отображены в виде кнопок, а не текста;
  • Отображать дату/время сообщений в виджете по умолчанию включено, отображает дату и время поступающих и отправленных сообщений в чате;
  • Отображать кнопки бота в одну колонку — по умолчанию выключено. При включении кнопки меню в виджете будет размещены в одну колонку, иначе на строке будет размещено столько кнопок, сколько поместятся по ширине виджета;
  • Автопрокрутка до последнего исходящего сообщения лида — по умолчанию выключено. При выключенном состоянии позиционирование производится в конец последней кнопки меню, если включить опцию, то позиционирование производится вначале последнего сообщения бота, что очень удобно при объемных текстовых сообщениях от бота;
  • Версия виджета  не редактируемое поле;
  • Заголовок — текстовое поле, которое будет отображаться в заголовке виджета. Не обязательно для заполнения;
  • Подзаголовок — текстовое поле, которое будет отображаться в подзаголовке виджета. Не обязательно для заполнения;
  • Подсказка для поля отправки текста — редактируемое текстовое поле. По умолчанию заполнено фразой "Введите сообщение...";
  • Всплывающая подсказка для поля отправки текста — редактируемое текстовое поле. По умолчанию заполнено фразой "Введите сообщение...";
  • Автогенерация списка диплинков — автоматическое заполнение списка диплинков, при этом, список диплинков, заполненный вручную не будет использоваться;
  • Список диплинков (JSON-массив) — список диплинков (массив в JSON-формате), указанные диплинки будут отображены при нажатии на значок чат-виджета. Нажатие на ссылку с диплинком запустит привязанный к диплинку маршрут. Привязка диплинка к маршруту устанавливается в "Настройках бота", на странице "Маршруты";
  • Разрешить отправку файлов — опция для включения или отключения отправки файлов в виджете;
  • Список поддерживаемых расширений файлов — список форматов файлов, которые могут быть отправлены в виджет. По умолчанию в поле указано: "png, jpg, gif, pdf, doc, docx, csv, xml, zip, 7zip, gzip, rar";
  • Реакция на файлы (документы) — выпадающий список с выбором реакции виджета на файлы;
  • Контекст NLP для файлов (документов) — NLP контекст для файлов в виджете;
  • Отключить Fallback для файлов (документов) — опция для включения или отключения Fallback для файлов в виджете.

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

image.png

image.png

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

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

Параметр Описание Пример:
title Заголовок виджета "Title"
subtitle Подзаголовок виджета "Subtitle"
initPayload Стартовое сообщение "/start"
inputTextFieldHint Приглашение ввести текст "Введите сообщение..."
inputTextTitle Всплывающее приглашение ввести текст "Введите сообщение..."
showMessageDate Показывать дату отправки сообщения showMessageDate
isButtonsInOneColumn Отображать все кнопки в 1 колонку false
isCustomScrolling При получении входящего сообщения в виджете (от бота/оператора) выполнять скроллинг к последнему исходящему сообщению Лида false



mainColor Основной цвет "#F69B1D"
userTextColor Цвет текста на кнопках "#FFF"
userBackgroundColor Цвет кнопок "#F69B1D"
attachments

enabled Вкл/откл отправки файлов в виджете "true"
extensions Список поддерживаемых расширений файлов "png,jpg,gif,pdf,doc,docx,csv,xml,zip,7zip,gzip,rar"
icon Ссылка на иконку для прикрепления файлов "default"
maxSize Максимальный размер файлов {
    all:  10485760,
    video: 20971520
}
errorMessage Сообщения об ошибке отправки файла

{
'default': 'Sorry, there was an error uploading the file',
'en': 'Sorry, there was an error uploading the file',
'en-US': 'Sorry, there was an error uploading the file',
'ru': 'Извините, произошла ошибка при загрузке файла',
'ru-RU': 'Извините, произошла ошибка при загрузке файла',
'zh-CN': '抱歉,上传文件时出错',
'zh-HK': '抱歉,上传文件时出错',
'zh-TW': '抱歉,上传文件时出错'

}

errorLargeFileMessage Сообщения о файле слишком большого формата {
'default': 'Maximum file size exceeded',
'en': 'Maximum file size exceeded',
'en-US': 'Maximum file size exceeded',
'ru': 'Превышен максимальный размер файла',
'ru-RU': 'Превышен максимальный размер файла',
'zh': '超出最大文件大小',
'zh-CN': '超出最大文件大小',
'zh-HK': '超出最大文件大小',
'zh-TW': '超出最大文件大小'
}

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

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

image.png

Например, вот так выглядит код виджета для бренда 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.

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

После создания канала появится HTML-код для вставки на страницу. Используя любой подходящий редактор вставьте данный код перед закрывающим тэгом </body>.

image.png


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

image.png


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

image.png


Нажмите на иконку чат-виджета и протестируйте вашего бота на ответы.

image.png


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

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

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

image.png


В Загрузчике выводится нужная одна строка-ссылка на CDN-скрипт. Выполняется автоматическая проверка доступности скрипта-загрузчика в CDN. Если всё работает правильно, то выводится зелёное "200", иначе - красное "404" или другой код ошибки.

image.png

Metabot Widget и GTM

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

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

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

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

изображение.png

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

изображение.png

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

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

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

изображение.png

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

изображение.png

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

изображение.png

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

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

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

изображение.png

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

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

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

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

изображение.png

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

изображение.png 

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png


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

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

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

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

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

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

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

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

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

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

  1. Разместим на тестовой странице сайта 2 кнопки с диплинками:
  • Демо-бот;
  • Поддержка.
  1. Создадим 3 ссылки в разделе Ссылки с именем диплинков, например, Deeplink1, Deeplink2, Deeplink3.

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

  • Имя — указать имя ссылки, например "Deeplink1";
  • Текст — текстовое сообщение, которое будет отображено в чат-виджете;
  • Тип ссылки — выбираем пункт Ссылка на бот-скрипт (Deep Link).

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


изображение.png

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

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

изображение.png

  1. Создадим маршруты в разделе Маршруты с регулярными выражениями соответствующими именам созданных ссылок.

ДЕМО-БОТ

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

изображение.png

ПОДДЕРЖКА

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

изображение.png

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

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

изображение.png

изображение.png

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

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

изображение.png

изображение.png


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

Добавляются 2 диплинка для ТЕСТОВОГО БОТА с таким условие (условия немного отличаются):
// Запуск диплинка ДЕМО-БОТ

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;
}
Смысл данного условия в том, что при клике на кнопку с диплинком с фронта передается параметр service.

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

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

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

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

изображение.png

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

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ка диплинков.

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

изображение.png

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

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

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

изображение.png

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

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

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

изображение.png

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

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

изображение.png

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

изображение.png

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

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

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

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

изображение.png

  {
        "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"
            }
        ]
    },

 изображение.png

 изображение.png

{
        "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"
            }
        },

изображение.png

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

На виджете так изображение.png

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

 изображение.png

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

изображение.png

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

изображение.png


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

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

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

изображение.png

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

{"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

Для интеграции канала Telegram c платформой Metabot24 необходимо создать аккаунт и задать адрес бота в Telegram.

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

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

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

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

image.png

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

метабот бот.png

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

image.png

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

метабот бот.png

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

image.png

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

image.png

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

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

image.png

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

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

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

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

Без имени.png

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

image.png

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

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

image.png

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

image.png

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

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

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

редактирование бота.png

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

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

image.png

image.png


image.png

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

метабот бот.png

метабот бот.png

image.png

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

command1 - Description

command2 - Another description

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

Для связи команд из botFather с платформой перейдите в маршруты. Документация

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

ВАЖНО: в маршруте с регулярным выражением подписи команды должен быть включен флаг Действует в диалоге.

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

image.png

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

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

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

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

Jivochat

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

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

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

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

image.png

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

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

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

image.png

image.png

image.png

image.png

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

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

Настройка Jivochat

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

дживо.png

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

вебхук дживо.png

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

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

image.png

image.png

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

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

вебхук дживо.png


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

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

вебхук дживо.png

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

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

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

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

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

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

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

Канал Кнопки Использовать inline-кнопки Регулярное выражение
Jivo Widget поддерживает Да ^https:\/\/metabot24\.info/.*$
Telegram поддерживает не более 7 Да telegram

Viber

поддерживает не более 7 Да ^metabotjivo$
ВКонтакте не поддерживает Нет ^Metabot.*$

Instagram

не поддерживает Нет ^Metabot.*$

Facebook

не поддерживает Нет ^Metabot.*$

Avito

не поддерживает Нет Avito

Apple Business Chat

не поддерживает Нет -

Одноклассники

не поддерживает Нет ^Metabot.*$

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

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

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

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

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

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

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

диалог дживо.png

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

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

диалог дживо.png

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

диалог дживо.png

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

диалог дживо.png

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

диалог дживо.png

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

диалог дживо.png

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

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

Работа с 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. Затем переходим в раздел Сообщества, на вкладку Управление и выбираем нужное для настройки канала сообщество.

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

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

изображение.png

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

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

изображение.png

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

изображение.png

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

изображение.png

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

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png

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

изображение.png


Umnico

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

image.png

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

image.png

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

image.png

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

меню.png

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

image.png

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

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

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

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

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

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

pdf,doc,docx,xls,xlsx,csv,txt,png,jpe,jpg,jpeg,gif,bmp,ico,svg,svgz,tif,tiff,jfif,ai,drw,pct,psp,xcf,psd,raw,webp,xbm,dib,pgp,apng,pjpeg,avif,avi,divx,flv,m4v,mkv,mov,mp4,mpeg,mpg,ogm,ogv,ogx,rm,rmvb,smil,webm,wmv,xvid,3gp,3g2,qt,asx

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

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

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

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

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

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() // погасит вывод меню с повтором вопроса
}
// Библиотека с помощью которой можно записать в карочку лида данные не отправля их в тг
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()
}
// Условие

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)
Текст команды
{{ $randomAnswer }}
// Условие

return (memory.getAttr('is_attachment')*1)
Получатель email, на который необходимо отправить письмо. ({{ $bot.botSupportMails }})
Тема *Название бота поддержки*: лид отправил в бота файл
Содержимое В чат-боте пользователь прислал в бота файл <br> <br>ID клиента для поиска в диалогах на платформе Metabot: {{ &$leadId }} <br> <br>Ссылка на файл: {{ $is_attachment }} <br> <img src="{{ $is_attachment }}" alt="Отправленный файл" width="400" height="341" /> <br> С уважением, <br> Ваш Metabot

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

Как достать данные вложений

Для Telegram используйте метод bot.getAllAttachments()

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.getWebhookPayload()

let attachments = bot.getWebhookPayload()

if(attachments.payload.attachments[0].url){

  uploadData = bot.downloadFileFromUrl(attachments.payload.attachments[0].url)

  lead.setAttr('file', uploadData.url)
}

В данных примерах в атрибут записывается url вложения для скачивания с помощью метода  bot.downloadFileFromUrl().

Битрикс24

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

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

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

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

image.png

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

image.png

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

image.png

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

image.png

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

image.png

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

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

image.png

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

image.png

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

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

image.png

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

image.png

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

image.png

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

image.png

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

image.png

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

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

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

image.png

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

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

image.png

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

image.png

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

image.png

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

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

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

image.png

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

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

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

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

image.png

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

image.png

Pyrus

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

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

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

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

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

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

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

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

Untitled-1.png

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


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

Untitled.png

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

Untitled-1.png

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

image.png

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

В Response Body добавьте код:
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. Сохраните создание эндпоинта.

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

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

image.png

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

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

Команду Выполнить 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 отличен от русского.

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

изображение.png

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

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

image.png

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

photo_2024-09-12_14-38-19.jpg

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

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

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

изображение.png

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

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

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

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

Untitled.png

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

Untitled.png

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

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

Untitled-1.png

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

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

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

Untitled.png

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

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

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

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

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

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

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

изображение.png

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

изображение.png

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

изображение.png

В настройках канала обязательно должна быть включены следующие опции: Реакция на фото, файлы и видео - Штатная (NLP и меню)

изображение.png

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

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

изображение.png

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

Untitled.png

изображение.png

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

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

изображение.png

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

Для того чтобы передать контактные или запрошенные у пользователя данные в соответствующие поля задачи по Форме, необходимо сохранить эти данные в переменную 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. В настройках шаблона просмотрите или измените коды полей.

изображение.png

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

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

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

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

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

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

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

изображение.png

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

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

изображение.png

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

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

изображение.png

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

изображение.png

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


LiveTex

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

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

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

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

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

image.png

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

image.png

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

image.png

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

image.png

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

image.png

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

image.png

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

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

image.png

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

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

image.png

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

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

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

image.png

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

image.png

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

image.png

На текущий момент в 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 обеспечивает следующий список каналов связи для возможного подключения:

image.png

Webim

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

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

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

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

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

Снимок экрана 2024-07-15 155621.png

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

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

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

image.png

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

Снимок экрана 2024-07-15 160140.png

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

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

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

image.png

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

Снимок экрана 2024-07-15 160535.png

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

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

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

image.png

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

Снимок экрана 2024-07-15 161140.png

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

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

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

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

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

image.png

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

Снимок экрана 2024-07-15 161816.png

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

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

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

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

Снимок экрана 2024-07-15 162245.png

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

Снимок экрана 2024-07-15 162344.png

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

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

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

Снимок экрана 2024-07-15 162655.png

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

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

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

image.png

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

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

Снимок экрана 2024-07-15 162925.png

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

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

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

image.png

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

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

Снимок экрана 2024-07-15 163424.png

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

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

Viber

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

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

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

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

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

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

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

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

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

image.png

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

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

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

Как из чат-бота создать лид в Битрикс24

Средства интеграции с внешними системами по API, доступные в платформе Метабота, позволяют выполнять обращения в сторонние системы в любом месте сценария диалога, если возникает такая необходимость.

Разработка интеграций осуществляется с помощью встроенного в ядро платформы V8 JavaScript Engine от Google. Благодаря встроенному языку программирования перед разработчиками открываются неограниченные возможности для профессиональной разработки чат-ботов и чат-приложений.

Наличие огромного количества материалов по JavaScript в профессиональных сообщества Интернета, таких как StackOverflow, делают разработку с помощью платформы Метабот такой же привычной и естественной как и разработка на чистых языка программирования.

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

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

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

Создайте новую интеграцию для входящего веб-хука, у которой настройте права на доступ к CRM.

Если вы это делаете впервые, воспользуйтесь статьей Веб-хуки. Быстрый старт.

Скопируйте «Вебхук для вызова rest api». На следующем шаге вам понадобится ввести этот адрес в настройках вашего бота в Метабот.

image.png

Добавьте системные атрибуты в бота на стороне Metabot

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

1. Заголовок API вызова

sys_api_headers: {"Accept":"application/json"}

image.png

2. Адреc веб-хука для вызова Rest API  

sys_api_http_client_config: {"base_uri":"https://ваш_домен.bitrix24.ru/rest/24/ccyr5i4ptyg4neyw/"}

image.png

Создайте в боте сценарий с анкетой

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

image.png

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

Добавьте в боте вызов API метода для создания лида в системе Bitrix24

Перед командой Стоп добавьте вызов JavaScript следующего вида:

image.png

Список и название полей в массиве fields будет зависеть от ваших настроек CRM. Используйте метод crm.lead.fields, чтобы узнать список всех полей и узнать требуемый формат полей.

// Добавляем лид в Bitrix24
api.getJson(‘crm.lead.add.json’, {}, [], {«query»: {
«fields»: {
«TITLE»: lead.getAttr(‘Компания’) + «: запрос в боте на консультацию»,
«NAME»: lead.getAttr(‘Имя’),
«COMMENTS»:
«Ниша: » + lead.getAttr(‘Ниша’) + «<br>» +
«Задача: » + lead.getAttr(‘Задача’),
«EMAIL»: [
{
«VALUE»: lead.getAttr(‘sys_email’),
«VALUE_TYPE»: «WORK»
}
],
«PHONE»: [
{
«VALUE»: lead.getAttr(‘sys_phone’),
«VALUE_TYPE»: «WORK»
}
]
}
}});

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

Аналогичным образом разрабатываются любые другие интеграции как с Битрикс24, так и с другими системами.