02. Учимся на примерах

Введение в основы разработки на платформе Metabot через практические примеры

• Урок 1: Бот за 5 минут
• Урок 2: Меню самообслуживания
• Урок 3: Вывод фото в боте по REST API
• Урок 4: Бот-магазин — списание остатков и блокировки двойных продаж
• Урок 5: Автоматизируем службу поддержки
• Урок 6: Магазин в боте
• Урок 7: Регистрация в боте
• Урок 8: Диалоговый интерфейс к ИТ системам
• Урок 9: Создание интеллектуального квиза для путешественников — интеграция Manychat с Metabot
• Урок 10: Создание PHP плагина Metabot для расширения бота и платформы

Урок 1: Бот за 5 минут

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

В этом уроке мы создадим простое приложение «Мой первый бот» для мессенджера Telegram и познакомимся с интерфейсом и функционалом Metabot.

Для начала зарегистрируйте бесплатную учетную запись на странице https://app.metabot24.com/register. Подтвердите свой адрес электронной почты, войдите в систему и следуйте инструкциям ниже.

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

Инструкция по разработке: Подготовка бота

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

1. Давайте создадим нового чат-бота с помощью ссылки Создать нового бота... в раскрывающемся меню Выбор бота.

2. При создании бота задайте необходимые параметры:

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

Остальные опции оставим за рамками этого урока. Вы узнаете их позже.

3. Выберите вновь созданного бота в раскрывающемся меню Выбрать бота.

Создание скрипта

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

Также рекомендуем ознакомиться с документацией по Скриптам

2. Укажите название скрипта. Например: «Старт». Остальные параметры оставьте без изменений.

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

Мы также рекомендуем вам ознакомиться с документацией по Редактору скриптов

4. Добавьте команду Отправить текст, нажав кнопку Добавить команду и выбрав ее в открывшемся окне.

В качестве текста предлагаем вам отправить традиционное послание «Hello Humans! 🤖», что является ответом на знаменитое «Hello World! 🌎», с которого многие программисты начинают изучение нового языка программирования и которое давно стало частью культуры программистов.

Мы также рекомендуем вам прочитать документацию по команде Отправить текст

Если все сделано правильно, команда появится в редакторе скрипта.

Создание маршрута

1. Перейдите в Настройки бота > Маршруты и создайте новый маршрут, нажав кнопку Создать маршрут.

Мы также рекомендуем вам прочитать документацию по Маршрутам

2. Введите параметры, как показано на изображении ниже.

3. Введите "Приветствие" в качестве Названия.

4. В качестве Скрипта выберите скрипт, который вы только что создали.

5. В Регулярном выражении напишите точку-звездочку ".*" без кавычек. Это выражение означает, что бот запустит этот маршрут в ответ на любой текст от пользователя.

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

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

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

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

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

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

3. Ввести имя нового бота и ID для мессенджера, оно может совпадать с именем бота для удобства и должно заканчиваться на bot.

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

5. Перейдите в Настройки бота> Каналы и создайте новый канал, нажав кнопку Новая привязка.

Мы также рекомендуем вам прочитать документацию по Каналам

6. Введите параметры, как показано на изображении ниже.

7. Выберите Telegram в качестве Канала.

8. Включите Использовать inline-кнопки.

9. Введите скопированный ранее в Telegram токен в поле Токен.

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

Не пропустите этот шаг! Если вы не установите вебхук, то ваш чат-бот не сможет получать сообщения из канала.

Поищите в Интернете «что такое вебхуки и зачем они нужны», чтобы узнать о них, если вы еще не знакомы с этим понятием. Вебхуки широко используются в сфере интеграции различных интернет-сервисов, а поскольку чат-бот — это пользовательский интерфейс к системам и сервисам, при разработке чат-ботов вы будете постоянно сталкиваться с настройкой вебхуков. Поэтому мы настоятельно рекомендуем вам разобраться, что такое вебхуки, где они растут и как их готовить. 🙂

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

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

Вы так же можете посмотреть наш пример данного бота в Telegram: @HelloHumanMetabot

Урок 2: Меню самообслуживания

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

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

Подробнее изучить работу бота вы можете с помощью нашего примера — бота в Telegram: @MenuMetabot

Инструкция по разработке: Подготовка бота

1. Первым делом требуется создать бота и скрипт-приветствие в нем.

Как это сделать вы можете узнать из урока "Hello Humans: ваше руководство по быстрому старту"

2. В созданном скрипте добавьте команду Отправить текст, нажав на кнопку Добавить команду и выбрав ее в открывшемся окне. Напишите текст сообщения. Текст может содержать эмодзи для эмоционального окраса вашего приветствия.

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

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

Создание разделов меню

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

Блок Команды в данном скрипте оставляем пустым, а в блоке Меню добавим пункты меню.

Для данного бота достаточно создать меню из 4-х разделов:

• О нас;
• Контакты;
• Каталог;
• Сделать заказ.

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

2. Откройте редактор скрипта, нажав на кнопку Перейти в редактор скрипта, расположенную напротив только, что созданного пункта меню О нас.

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

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

3. Далее перейдем в скрипт Контакты.

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

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

В качестве меню можно указать 2 товара и возврат в меню:

• Торт "Сердце";
• Торт "Звезда";
• Вернуться в меню.

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

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

Обратим внимание, что пункт меню Вернуться в меню обязательно надо создавать, так как при вложенном подменю возврат в главное меню автоматически не производится!

5. Пункт меню Заказать — это пункт, который будет содержать скрипт с ответом на вопрос пользователя и переводом диалога на оператора:

• Добавьте команду Установить статус лида со статусом Заказ;
• Добавьте одну или несколько команд Отправить текст, разместив там инструкции для действия пользователя;
• Добавьте команду Стоп.

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

• Добавьте команду Выполнить скрипт, в качестве выполняемого скрипта указать скрипт Меню;
• Так же добавьте команду Установит статус лида со статусом Первичное касание.

7. Создайте последний скрипт в вашем боте, который будет выполняться в том случае, если пользователь выбрал не верный пункт меню:

• Укажите название скрипта. Например: "Некорректный ввод";
• Тип скрипта - Fallback;
• Остальные параметры без изменения.

Добавьте команду Отправить текст, в которой вы сообщите пользователю, что его вопрос не распознан. Напишите текст сообщения, например, "Вы ввели неправильную цифру. Попробуйте, пожалуйста, ещё раз.";

Добавьте команду Повторить вопрос.

Внимание! Команда Повторить вопрос вернет пользователю предыдущее меню.

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

Создание маршрутов

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

Как это сделать вы можете узнать из инструкции "Маршруты"

2.  Создайте маршрут, который будет запускаться когда пользователь передумал общаться с оператором и решил позвать бота.

• В качестве Названия укажите "Меню";
• В качестве скрипта выберите скрипт Меню;
• В Регулярном выражении напишите фразу: \s*бот\s*|\s*меню\s*
• В качестве статуса выберите Заказ.

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

Запуск бота в Telegram

1. Создадим канал Telegram.

Как это сделать вы можете узнать из инструкции "Интеграция канала Telegram с платформой Metabot"

2. Далее перейдите в приложение Telegram, откройте ваш бот и нажмите кнопку /start. Если вы все сделали правильно, ваш бот поприветствует вас.

Поздравляем вас с созданием вашего бота с меню самообслуживания на платформе Метабот24!

Рекомендуем так же ознакомиться с остальными нашими уроками по созданию ботов, например Урок 3: Вывод фото в боте по REST API

Урок 3: Вывод фото в боте по REST API

Подробнее изучить работу бота вы можете с помощью нашего примера — бота в Telegram: @Metabot101Metabot или Chat Widget

• Как разрабатывается REST API интеграция с помощью вызова точек интеграции, называемых "endpoints";
• Как использовать JavaScript для обращения к сторонним ресурсам;
• Как работать с данными, которые хранятся в лиде (lead) и во временной памяти (memory);
• Как работать с режимом отладки кода, который позволит вам получать уведомления об ошибках выполнения вашего кода.

Инструкция по разработке: Подготовка бота

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

Как это сделать вы можете узнать из урока "Hello Humans: ваше руководство по быстрому старту"

Для нашего бота в начальном скрипте понадобится только команда отправки текста. Примерное содержимое команды может быть таким: "Приветствую! Это бот для просмотра фотографий на сервисе Unsplash.com".

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

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

В данном боте будет создано два канала: Telegram и Metabot Widget

1. Создадим канал Telegram.

Как это сделать вы можете узнать из инструкции "Интеграция канала Telegram с платформой Metabot"

2. Создадим канал Metabot Widget.

Как это сделать вы можете узнать из инструкции "Metabot Widget"

Подключение маршрутов

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

Как это сделать вы можете узнать из инструкции "Маршруты"

Запускаем первую версию бота

1. Находим бот в Telegram и запускаем /start.

2. В справочнике каналов открываем канал «Metabot Widget» и в справочнике каналов последовательно нажимаем на кнопку «Предварительный просмотр».

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

Включение режима отладки

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

1. Для включения отладки следует зайти в меню "Лиды" и нажать на кнопку переключения отладчика.

2. Затем нужно выбрать уровень отладки. В данном случае выбирайте уровень "editor".

Если режим отладки включен, в мессенджер или виджет (в зависимости от канала, с которым связан лид), то в случае ошибок в JS-коде, будут выдаваться сообщения об ошибках. Если лид, под которым выполнялась отладка находится на продуктовом сервере, после завершения разработки отладчик следует отключить.

Расширяем скрипт с приветствием и меню

1. Добавляем пункты меню "Выбрать тему" и "Следующее фото" в стартовый скрипт.

Как это сделать вы можете узнать из инструкции "Создание меню"

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

2. Следующим шагом отредактируем свойства автоматически созданных скриптов, а точнее их имя и JS-код. Это делается при помощи кнопки редактирования в меню скриптов.

• Название — это имя скрипта, которое может содержать в себе любые символы. Скриптам связанные с интеграциями, которые содержат большой объем JavaScript команд, рекомендуется присваивать англоязычные имена, так как это область работы JS программистов;
• Код — это дополнительный уникальный идентификатор. Используется для поиска скрипта, например, в JavaScript функциях, а также для поиска и запуска скрипта через NLP. Он всегда обозначается одним словом без пробелов.

3. Для скрипта выбора темы вводим в поля название и код значение select_theme_photo, а в скрипт переключения на следующее фото значение show_next_photo.

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

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

Теперь мы готовы выполнить интеграцию с сервисом Unsplash.com.

Подключаемся к API Unsplash.com

Для начала получим токен к API Unsplash.com.

1. Переходим к документации API Unsplash.com по ссылке: https://unsplash.com/documentation

2. Регистрируемся на платформе.

3. Для работы с API нам нужно получить специальный ключ-токен для доступа к методам API. Переходим в раздел "Ваши приложения" и нажимаем на окошко "Новое приложение".

4. Затем заполняем информацию о том для чего будет использован ключ, прокручиваем страницу ниже и как результат получаем Access Key. Он и будет использован для доступа к API.

5. В документации Unsplash указано два способа применения Access Key:

• При помощи заголовка авторизации:

Authorization: Client-ID YOUR_ACCESS_KEY

• Используя client_id параметр запроса:

https://api.unsplash.com/photos/?client_id=YOUR_ACCESS_KEY

Мы используем второй вариант и просто добавим Access Key как параметр URL. Для этого зайдем в «Настройки бота» меню «Атрибуты» создадим системный атрибут sysApiHeaders и присвоим ему значение:

client_id=4ERbUpdlr1g8asSD6c_Evz9Ap1L-cl0ZZj0RzrKJFpc. 

Подробнее про атрибуты вы можете узнать из инструкции Атрибуты

Иcследуем endpoints API Unsplash.com

1. На главной странице документации в разделе Schema находим базовый URL для работы с фото.

2. Аналогично предыдущему пункту, в «Настройки бота» меню «Атрибуты» заносим системный атрибут sysApiHttpClientConfig  и присваиваем значение: https://api.unsplash.com/

В итоге имеем в нашем боте следующие атрибуты:

Подробнее про работу с API на платформе Metabot вы можете узнать из инструкции Конструктор API

Заполняем скрипт select_theme_photo

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

1. Для реализации данного функционала создадим команду "Запросить значение". Зададим команде параметр "Имя переменной" = photoTheme. Именно в этом атрибуте будет храниться результат запроса.

Подробнее о команде "Запросить значение" вы можете узнать из соответствующей инструкции.

2. Следующей командой будет "Выполнить JavaScript". Она будет содержать JS код для доступа к API.

// раздел 1: подготовка параметров REST запроса

var photoTheme = lead.getAttr('photoTheme');
var url = bot.getAttr("sysApiHttpClientConfig") + "search/photos?" + bot.getAttr("sysApiHeaders") + "&query=" + photoTheme + "&per_page=1";

//--------------------------------------------------------

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

var total_results = 0;
lead.setAttr('url', url);
memory.setAttr('rsps.description', '');
lead.setAttr('rsps.totalResults', 0);
memory.setAttr('rsps.photographer', '');
memory.setAttr('rsps.full', '');
memory.setAttr('rsps.raw', '');
lead.setAttr('photoThemeIndex', 1);

//--------------------------------------------------------

В разделе 1 выбирается из атрибутов лида введенная ранее пользователем тема photoTheme и подготавливаются параметры REST запроса. Здесь же мы добавляем ранее созданные системные атрибуты в URL запроса. Так же добавляем в URL атрибуты запроса: тему фото и количество выводимых фото.

Ниже подробно расписаны все возможные атрибуты запроса:

В разделе 2 присваиваем начальные значения атрибутов:

• url — REST запрос;
• total_results – всего фото по заданной теме;
• photo_theme_found — признак, что запрос вернул фото;
• next_page — следующая страница;
• photographer – фотограф;
• original — cсылка на оригинальное фото;
• medium — ссылка на уменьшенную копию medium;
• photo_theme_index — текущиее фото в теме.

При этом одни переменные сохраняются в атрибутах лида, а другие во временном хранилище в памяти (в memory). 

Примечание: Переменные, которые необходимы для выполнения алгоритма скрипта лучше сохранять в memory, чтобы не засорять атрибуты лида ненужными данными. В тоже время необходимо помнить, что при запуске нового скрипта по кнопке, по намерению NLP или по маршруту memory очищается, а lead очистить можно только принудительно командой. Поэтому переменные, которые используются в различных скриптах, сохранять в memory не нужно. В тоже время скрипт, который запускается из некоторого скрипта командой запустить скрипт имеет доступ к переменным в memory скрипта, который его запустил и всех остальных его запустивших.

Примечание: для отладки удобно временно сохранять переменную в lead вместо memory, так как переменные lead можно просматривать в справочнике атрибутов лидов.

Используются некоторые параметры из JSON объекта, который возвращает REST запрос.

Ниже приведена полная структура ответа:

{
  "total": 133,
  "total_pages": 7,
  "results": [
    {
      "id": "eOLpJytrbsQ",
      "created_at": "2014-11-18T14:35:36-05:00",
      "width": 4000,
      "height": 3000,
      "color": "#A7A2A1",
      "blur_hash": "LaLXMa9Fx[D%~q%MtQM|kDRjtRIU",
      "likes": 286,
      "liked_by_user": false,
      "description": "A man drinking a coffee.",
      "user": {
        "id": "Ul0QVz12Goo",
        "username": "ugmonk",
        "name": "Jeff Sheldon",
        "first_name": "Jeff",
        "last_name": "Sheldon",
        "instagram_username": "instantgrammer",
        "twitter_username": "ugmonk",
        "portfolio_url": "http://ugmonk.com/",
        "profile_image": {
          "small": "https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=32&w=32&s=7cfe3b93750cb0c93e2f7caec08b5a41",
          "medium": "https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=64&w=64&s=5a9dc749c43ce5bd60870b129a40902f",
          "large": "https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=128&w=128&s=32085a077889586df88bfbe406692202"
        },
        "links": {
          "self": "https://api.unsplash.com/users/ugmonk",
          "html": "http://unsplash.com/@ugmonk",
          "photos": "https://api.unsplash.com/users/ugmonk/photos",
          "likes": "https://api.unsplash.com/users/ugmonk/likes"
        }
      },
      "current_user_collections": [],
      "urls": {
        "raw": "https://images.unsplash.com/photo-1416339306562-f3d12fefd36f",
        "full": "https://hd.unsplash.com/photo-1416339306562-f3d12fefd36f",
        "regular": "https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=92f3e02f63678acc8416d044e189f515",
        "small": "https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=263af33585f9d32af39d165b000845eb",
        "thumb": "https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=8aae34cf35df31a592f0bef16e6342ef"
      },
      "links": {
        "self": "https://api.unsplash.com/photos/eOLpJytrbsQ",
        "html": "http://unsplash.com/photos/eOLpJytrbsQ",
        "download": "http://unsplash.com/photos/eOLpJytrbsQ/download"
      }
    },
    // больше фото ...
  ]
}

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

// раздел 3: выполнение REST запроса

memory.setAttr('photoThemeFound', 0);
let jsonResponse = api.getJson(url);
if (jsonResponse) {

//------------------------------------------------
  
// раздел 4: сохранение результата запроса в атрибутах лида
  
  var rsps = jsonResponse;
  totalResults = rsps['total'] * 1;
  if (totalResults > 0) {
    memory.setAttr('photoThemeFound', 1);
    lead.setAttr('rsps.totalResults', totalResults);
    lead.setAttr('rsps.photographer', rsps['results'][0]['user']['username']);
    lead.setAttr('rsps.description', rsps['results'][0]['description']);
    lead.setAttr('rsps.full', rsps['results'][0]['urls'][ 'full' ]);
    lead.setAttr('rsps.raw', rsps['results'][0]['urls'][ 'raw' ]);
  }
  
//------------------------------------------------

// раздел 5
  
  memory.setJsonAttr("lastHttpResponse", api.getLastResponseContent());
  memory.setAttr("lastHttpResponseCode", api.getLastResponseCode());
}

//------------------------------------------------

В разделе 3 выполняется REST запрос к сервису и проверяется что запрос выполнился.

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

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

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

4. Далее выводим ответ в канал, используя данные, сохраненные в атрибутах лида. Для этого используем две команды вывода текста с условием. Одна срабатывает когда атрибут photoThemeFound равен 1, вторая, наоборот, когда не равен 1.

Так выглядят данные команды после создания:

Вы можете скопировать данные команд из таблицы:

Заполняем скрипт show_next_photo

1. Входим в редактор команд скрипта и набираем скрипт, который аналогично предыдущему состоит из трех частей: 

• 1 извлечение из лида параметров запроса;
• 2 выполнение запроса и заполнение атрибутов в memory и lead;
• 3 сохранение переменных для отладки. 

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

// раздел 1: подготовка параметров REST запроса

var photoTheme = lead.getAttr('photoTheme');
var photoThemeIndex = lead.getAttr('photoThemeIndex') * 1;
photoThemeIndex++;
var url = bot.getAttr("sysApiHttpClientConfig") + "search/photos?" + bot.getAttr("sysApiHeaders") 
+ "&query=" + photoTheme + "&page=" + photoThemeIndex + "&per_page=1";

//----------------------------------------------------------

// раздел 2

lead.setAttr('url', url);
memory.setAttr('photoThemeFound', 0);
jsonResponse = api.getJson(url);
if (jsonResponse) {
  var rsps = jsonResponse;
  totalResults = rsps['total'] * 1;
  if (totalResults > 0 && photoThemeIndex <= totalResults) {
    memory.setAttr('photoThemeFound', 1);
    lead.setAttr('photoTheme', photoTheme);
    lead.setAttr('photoThemeIndex', photoThemeIndex);
    lead.setAttr('rsps.totalResults', totalResults);
    lead.setAttr('rsps.photographer', rsps['results'][0]['user']['username']);
    lead.setAttr('rsps.description', rsps['results'][0]['description']);
    lead.setAttr('rsps.full', rsps['results'][0]['urls'][ 'full' ]);
    lead.setAttr('rsps.raw', rsps['results'][0]['urls'][ 'raw' ]);
  }
  
//----------------------------------------------------------
  
// раздел 3
  
  memory.setJsonAttr("lastHttpResponse", api.getLastResponseContent());
  memory.setAttr("lastHttpResponseCode", api.getLastResponseCode());
}

//----------------------------------------------------------

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

Вы можете скопировать данные команд из таблицы:

Бот готов! Теперь можно переходить к его тестированию.

Запускаем бот!

1. Запускаем бот в канале Telegram.

Запрашиваем у бота тему фото, которое мы хотим получить. Если фото по теме найдены, то бот выводит количество найденных фото по теме и индекс выведенного фото. Ниже указывается username фотографа, название фото и ссылки на него в обычном и HD формате.

2. Запускаем бот в канале виджета Metabot.

Бот в виджете работает по тому же принципу: запрос темы и вывод ссылок на фото.

Поздравляем с успешным созданием бота!

Рекомендуем так же ознакомиться с остальными нашими уроками по созданию ботов, например Автоматизируем службу поддержки

Урок 4: Бот-магазин — списание остатков и блокировки двойных продаж

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

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

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

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

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

Подробнее познакомиться с блокировками вы можете из инструкции Блокировки как средство управления параллелизмом

Подробнее изучить работу бота вы можете с помощью нашего примера — бота в Telegram: @BlockingMetabot

В ходе урока вы узнаете:

• Как работать с кастомными таблицами и создать с их помощью БД соответствующую вашим потребностям;
• Как контролировать параллельные процессы в ботах при помощи блокировок.

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

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

Пора перейти к практике!

Перед началом следует ознакомиться с предыдущими уроками Hello Humans: ваше руководство по быстрому старту и Metabot 101: Вывод фото в боте по REST API

Создание скриптов

1. Чтобы не отвлекаться на это в будущем, сразу создадим стартовый скрипт с приветствием, маршрут связанный с ним и канал Телеграм, при помощи которого будем тестировать бота, как мы делали это в предыдущих уроках.

Нам потребуются следующие скрипты:

• Стартовый скрипт;
• Меню;
• Скрипты категорий;
• Скрипты выбора товара;
• Скрипт оформления заказа.

Перейдем к их созданию

Стартовый скрипт и меню

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

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

2. Таким образом в скрипте меню нам нужно добавить команду отправки сообщения-подсказки, например: "Какие товары вас интересуют?", и кнопки меню соответствующие каждой категории.

Скрипты категорий

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

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

3. Чтобы это сделать создайте раздел при помощи кнопки Создать раздел. Введите название раздела и подтвердите действия кнопкой Создать.

4. Далее в редакторе свойств скрипта из выпадающего списка Раздел выберите созданный ранее раздел.

Теперь ваше рабочее пространство будет лучше организованно и с ним будет удобнее работать.

5. Но вернемся к наполнению скриптов категорий.

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

В команде Выполнить JavaScript в атрибуты бота будут добавлены две переменные:

• category — переменная в которой будет храниться наименование выбранной лидом категории;
• productNum — переменная в которой будет храниться начальный номер выводимого продукта.

Ниже вы можете скопировать код с фото.

lead.setAttr('category', 'mugs');
lead.setAttr('productNum', 0);

Перед созданием оставшихся скриптов следует реализовать БД для магазина.

Создание кастомных таблиц

Платформа Metabot предоставляет возможность создания своей БД при помощи кастомных таблиц.

Подробнее познакомиться с кастомными таблицами вы можете из инструкции Кастомные таблицы

1. Чтобы перейти в меню кастомных таблиц в верхнем меню бота из выпадающего списка Таблицы выберите Конструктор таблиц.

Для нашего бота нужны следующие таблицы:

• Таблица товаров;
• Таблица заказов.

Перейдем к их созданию.

Таблица товаров

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

• Наименование — название таблицы используемое в JS методах (должно состоять только из латинских букв без пробелов);
• Заголовок в интерфейсе — название таблицы отображаемое в интерфейсе (может состоять из любых символов).

3. Остальные поля оставьте без изменения и нажмите кнопку Создать.

4. После создания перейдем в структуру таблицы по соответствующей кнопке в конструкторе таблиц.

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

5. Для этого в меню структуры таблицы нажимаем на кнопку Создать. В открывшемся окне заполняем следующие поля:

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

6. Таким же образом создаем остальные поля таблицы товаров:

• Категория — категория товара (в нашем случае plates или mugs);
• Количество — количество товаров данного типа оставшихся на складе;
• Цена — цена товара;
• Фото — ссылка на изображение товара.

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

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

Таблица заказов

8. По тому же принципу создаем таблицу заказов со следующими полями:

• ФИО — имя заказчика;
• Адрес — адрес на который нужно прислать товар;
• Телефон — номер телефона заказчика;
• Категория — категория из которой был заказан товар;
• Товар — id товара в таблице товаров.

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

Работа с методами таблиц 

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

Скрипт вывода товаров

В скрипте вывода товара при помощи обращения к таблице товаров и команды отправки текста лиду будет выведена вся информация о товаре.

1. Для начала добавим команду Выполнить JavaScript со следующим кодом:

let category = lead.getAttr('category');
let productNum = lead.getAttr('productNum')

let item = table.find("products", [], [["category", "=", category]]);

lead.setAttr('productNumber', parseInt(productNum) + 1);
lead.setAttr('productName', item[productNum].name);
lead.setAttr('productQua', item[productNum].qua);
lead.setAttr('productPrice', item[productNum].price);
lead.setAttr('productPhoto', item[productNum].photo);

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

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

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

В строках 5-8 из записи под номером productNum в массиве записей запоминаем в атрибутах лида все данные о товаре. Эти данные затем будут выведены в диалог с лидом при помощи команды отправки текста.

2. После JS команды добавляем команду Отправить текст со следующим содержимым:

Таким образом у нас получается следующий набор команд:

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

• Следующий заказ — будет ссылаться на скрипт для вывода следующего товара;
• Оформить товар — будет ссылаться на скрипт оформления заказа;
• Выбрать другую категорию — будет ссылаться на скрипт меню.

Скрипт перехода на следующий товар

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

4. Для начала добавим команду Выполнить JavaScript со следующим кодом:

let category = lead.getAttr('category');
let productNum = lead.getAttr('productNum');

let item = table.find("products", [], [["category", "=", category]]);

if (item.length > productNum + 1){
  lead.setAttr('productNum', parseInt(productNum) + 1);
} else {
  lead.setAttr('productNum', 0);
}

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

5. После JS команды добавляем команду Выполнить скрипт — Вывод товара и переходим к созданию следующего скрипта.

Работа с блокировками

Перейдем к созданию последнего скрипта в нашем боте — Оформление заказа.

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

1. Первым делом создадим три команды Запросить значение. Из них мы узнаем имя, адрес и телефон заказчика.

2. Затем перейдем к созданию команды Выполнить JavaScript. Одной из основных ее частей будет являться работа с блокировками.

let customer = lead.getAttr('customer');
let address = lead.getAttr('address');
let phone = lead.getAttr('phone');
let category = lead.getAttr('category');
let productNum = lead.getAttr('productNum');

// Запись для таблицы заказов

let order = {
  "name": customer,
  "address": address,
  "phone": phone,
  "category": category,
  "product_id": productNum
}

//----------------------------

let isLocked = false

// Получаем блокировку по боту

bot.sendText('Рассматриваем ваш заказ! Ожидайте подтверждения');

isLocked = bot.waitForBotLock('my_lock', '', 20, 300);

//----------------------------

if (isLocked) {
  
  // Проверяем остались ли товары на складе
  
  let item = table.find("products", [], [["category", "=", category]]);

  if (item[productNum].qua > 0){
    
  //----------------------------
    
  // Обновляем данные на складе и создаем запись в таблице заказов
    
    item[productNum].update({"qua": item[productNum].qua - 1});
    
    table.createItem("orders", order);
    
  //----------------------------
    
    bot.sendText('Заказ оформлен');
    
  } else {
    
    bot.sendText('К сожалению данного товара уже нет на складе');
  
  }
} else {
  
  bot.sendText('Время ожидания истекло, попробуйте еще раз');

}

// Освобождаем блокировку полученную в данном скрипте

let hasLock = bot.hasLockForBot('my_lock');

if (hasLock) {
  
  bot.releaseCurrentLockForBot('my_lock');

}

//----------------------------

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

Далее переходим к работе с блокировками.

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

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

В конце скрипта происходит проверка на существование ранее захваченной блокировки и ее удаление. 

3. После JS команды добавляем команду Выполнить скрипт — Меню.

Бот готов к тестированию.

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

Проверим как работает наш бот.

1. Выберите категорию в меню. У вас должны вывестись данные о товаре.

2. Нажмите на кнопку Следующий товар. У вас должны вывестись данные о другом товаре.

3. Нажмите на кнопку Оформить заказ. Бот должен запросить у вас данные и прислать сообщение о принятии заказа.

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

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

Поздравляем вас с прохождением урока!

Урок 5: Автоматизируем службу поддержки

Цели и задачи

Вы когда-нибудь задумывались, как происходит работа в службе поддержки в большинстве компаний?

А ведь иногда это работа в качестве живых автоответчиков. Потому что большинство запросов, которые персоналу приходится разрешать — это стандартные вопросы и типовые проблемы, которые смог бы разрешить и чат-бот.

Согласно многочисленным опросам, почти 70% людей при обращении в поддержку хотят, чтобы проблемы решались моментально и им не важно, кто именно их будет решать. Они не хотят ждать, пока их вопрос пройдет длинных путь через  одного или нескольких специалистов, вернется к ним с постоянным повторением ситуации. Время — ценный товар, к которому люди в современном мире не относятся легкомысленно. 

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

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

Задайте себе вопрос, как клиент компании (или пользователь сервиса), обратившись с проблемой в поддержку, в каком случае вы себя будете чувствовать лучше: когда к вам относятся как к очередной заводской операции, обслуживаемой копи-пастом, или когда к вам отнесутся с пониманием и уделят качественное внимание?

Приведем пару интересных исследований касаемо плохого клиентского опыта (CX):

• После более чем одного неудачного опыта около 80% потребителей говорят, что они предпочли бы иметь дело с конкурентом. (Zendesk);
• 1 из 3 клиентов покинет любимый бренд после всего лишь одного неудачного опыта, а 92% полностью покинут компанию после двух или трех негативных взаимодействий. (PwC).

Что можно отнести к плохому клиентскому опыту?

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

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

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

Согласно данным, собранным Salesforce, 64% сотрудников признают, что благодаря чат-ботам у них появилось больше времени, чтобы сосредоточиться на общей картине. И наоборот, в компаниях без чат-ботов только 50% сотрудников могут сказать то же самое.

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

Как работает

Достаточно хорошо обученный чат-бот для самообслуживания на базе технологии распознавания естественного языка (NLP), которой вы сейчас овладеете, по нашему опыту, способен обрабатывать до 70-90% рутинных обращений в службу поддержки. 

Чат-бот обладает следующим функционалом:

• Встраивается в любой канал: чат на сайте, мессенджеры и социальные сети;
• Работает 24/7 без выходных и перерывов и мгновенно отвечает на запросы;
• Умеет отвечать на вопросы, заданные в свободной форме;
• Содержит меню с кнопками для популярных запросов;
• Бесшовно переводит диалог на персонал контакт-центра и обратно, в случае необходимости, предварительно собрав данные о запросе;
• Умеет опрашивать пользователя и передавать анкету в CRM и CDP системы по API;
• Способен интегрироваться c cистемами компании по API, например, для проверки статуса заказа.

Инструкция по разработке: Подготовка бота

В этом уроке мы покажем, как создается чат-бот на базе NLP c помощью Dialogflow от Google. Мы создадим бот для небольшой фирмы межевания, который даст возможность клиентам получить быстрые ответы на базовые вопросы о месте, времени работы и оказываемых услугах, а так же разгрузит работу операторов. Если ответ бота не устроит пользователя, то у него будет возможность поговорить с оператором.

1. Первым делом создайте бота на платформе Metabot.

Вы можете узнать как создать самого простого бота из урока Hello Humans: ваше руководство по быстрому старту

2. Следующим этапом является создание скриптов. Нашему боту потребуются такие скрипты, как:

• Стартовый скрипт — стандартный скрипт приветствия;
  
• Скрипт с NLP распознаванием — в этом скрипте бот будет получать вопрос от пользователя и отправлять его в Dialogflow на распознавание;
• Скрипты-NLP намерения — когда намерение в Dialogflow распознано, оно ищется по базе скриптов, используя поле NLP Намерение в свойствах скрипта по полному совпадению;
• Перевод на оператора — переключение на оператора. Данная задача легко реализуется с помощью команды Перевести на оператора, которую нужно будет разместить в этот скрипт.
• Вызов бота — скрипт необходим для перевода с оператора на бота по просьбе пользователя;
• Некорректный ввод — скрипт с типом Fallback, который бот выполняет, когда не распознано намерение пользователя.

Перед тем как идти дальше рекомендуем ознакомиться со статьями Скрипты и Редактор скрипта.

Создание скриптов

Стартовый скрипт

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

• Отправить текст с тем содержимым, которое вам нравится;
  
• Выполнить скрипт "Задать вопрос" — скрипт с NLP распознаванием.

Скрипт с NLP распознаванием

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

• Включить NLP — чтобы распознавание срабатывало внутри скрипта;
• Включить NLP Action — чтобы внутри скрипта можно быть распознавать NLP Action (функционал Small Talk от Dialogflow и другие action);
• Остальные параметры оставить без изменений.

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

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

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

Скрипт-NLP намерение

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

4. В данном боте мы создадим подобные скрипты трех типов:

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

Главным условием работы данных скриптов является установка значения в поле NLP Намерение. Когда намерение в Dialogflow найдено, оно ищется по базе скриптов и сравнивается со значениями полей NLP Намерение. Если найдено полное совпадение, то скрипт с совпадающим значением вступает в работу. 

NLP намерение лучше называть по аналогии с названием скрипта, но без пробела. Например для скрипта "Заказать услугу" намерение лучше назвать "заказать_услугу".

Рекомендуем также прописывать нумерацию намерений, чтобы легче работать с базой. Например: 01_заказать консультацию.

Рассмотрим примеры каждого типа скрипта:

Скрипт простого ответа на вопрос должен содержать команду с выводом атрибута {{$nlpLastResponseText}}. Данный атрибут будет возвращен DF после распознавания вопроса и содержать ответ на вопрос указанный в намерении DF.

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

Отдельные скрипты-ответы в поле NLP Намерение должны содержать намерение соответствующее названию скрипта и могут содержать одну или несколько команд, например:

• Отправить текст: "Я Ваш личный бот-помощник и я готов принять Ваш заказ прямо сейчас! Просто ответьте на мои вопросы."
• Запросить значение:  "Одним сообщением укажите Ваши данные (ФИО, адрес, индекс и номер телефона) и какую услугу Вы хотите заказать." и т.д.
• Перевести на оператора — выполнение данной команды приведет к переводу лида на оператора. Она обязательна.
• Стоп — выполнение данной команды приведет к остановке работы бота. Она также обязательна.

По тому же принципу создается скрипт "Перевод на оператора":

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

Вызов бота

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

5. В редакторе скрипта добавьте такие команды, как:

• Вернуть боту - для передачи диалога обратно боту;
  
• Отправить текст, в которой вы уведомите пользователя о том, что с ним снова общается бот. Например, текст "Я здесь, с вами снова общается бот.";
• Выполнить скрипт "Задать вопрос".

Некорректный ввод

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

6. В свойствах данного скрипта следует установить тип Fallback:

7. Далее в редакторе скрипта добавьте команду Отправить текст. В данной команде необходимо сообщить пользователю, что его запрос не распознан и порекомендовать его перефразировать, например, "Извините не понял. Сформулируйте свой вопрос по-другому."

8. Последним этапом добавьте команду Повторить вопрос.

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

Создание маршрутов

Перед прочтением рекомендуем ознакомиться со статьей Маршруты

1. Нам понадобится создать всего два маршрута:

• Маршрут, который будет запускать скрипт приветствия. В Регулярном выражении напишите .*. Это выражение означает, что бот будет реагировать на любой текст от пользователя;
• Маршрут, который будет запускаться при вызове бота и скрипта Позвать бота. В Регулярном выражении напишите слово "бот". Это выражение означает, что бот будет реагировать на ввод текста "бот" от пользователя. В качестве опции выберите из выпадающего списка значение Оператор.

Приступим ко второй части нашего урока — созданию базы знаний и модели Dialogflow.

Создание намерений в Dialogflow

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

Для работы нам понадобится сервис Dialogflow.

Перед тем как приступать к созданию намерений пройдите уроки Начало работы с Dialogflow и Интеграция с Dialogflow

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

2. Для каждого скрипта с NLP намерением в боте создаем свое намерение DF с идентичным наименованием.

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

3. В раздел Training phrases надо добавить различные варианты на тему того, что могут написать пользователи. Например для намерения вызова оператора:

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

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

4. Для намерений с однозначным ответом в поле Responses добавьте текстовый ответ. Он и будет выводиться в атрибут nlpLastResponseText.

5. В процессе обучения бота нужно проверять правильность вводимых значений. Для этого, в поле Try it now необходимо указать один из введенных вариантов обращения и система должна предоставить ссылку на нужное намерение.

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

7. Таким же образом создайте остальные намерения для вашего бота.

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

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

Проверим как работает наш бот.

1. Задайте вопрос боту. Бот должен распознать намерение и отправить соответствующий ответ на вопрос.

2. Попросите бота перевести вас на оператора. Бот должен остановить свою работу.

3. Попросите бота вернуться к диалогу. Бот должен возобновить свою работу.

Если все работает правильно, то поздравляем вас с созданием вашего бота c NLP на платформе Metabot24!

Вы так же можете попробовать в действии тестовый NLP бот, созданный командой Metabot24, набрав в Telegram логин @NLPDialogflowMetabot.

Урок 6: Магазин в боте

В данном уроке вы узнаете как создать собственный интернет-магазин на платформе Metabot.

Мы создадим интернет-магазин и бот, который будет давать ссылку на него. В магазине можно будет просматривать товары, делать заказы и оплачивать их. Все пользователи будут попадать в магазин из бота с помощью отправленной им ссылки и автоматически будут авторизованы в магазине под аккаунтом Telegram. 

Подробнее изучить работу бота вы можете с помощью нашего примера — бота в Telegram: @ShopinbotMetabot

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

Подробнее познакомиться с магазином вы можете из инструкции Магазин в боте

Перед началом следует ознакомиться с предыдущими уроками Hello Humans: ваше руководство по быстрому старту и Metabot 101: Вывод фото в боте по REST API

Инструкция по разработке: Подготовка заявок

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

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

1. Переходим в меню видов заявок: в разделе Заявки и персоны в верхнем меню бота, нажимаем на Виды заявок.

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

2. Для создания нового вида нажмите на кнопку Создать в меню видов заявок. В открывшемся окне заполните следующие поля:

• Наименование — название вида;
• Заказ в магазине — отметьте галочкой этот пункт, для создания заказов от магазина в боте.

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

В результате в боте будет создан вид заявки:

4. Далее перейдем к созданию статусов. Для этого перейдем в меню Статусы заявок.

Нашему боту понадобится пять статусов:

• Новый;
• Ожидает оплаты;
• Оплачен;
• Отменен;
• Ошибка оплаты.

5. Для создания нового статуса нажмите на кнопку Создать в меню статусов заявок. В открывшемся окне заполните следующие поля:

• Наименование — название статуса;
• Тип — тип статуса соответствующий вышеперечисленным пяти статусам.

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

В результате в боте должны созданы следующие статусы заявки:

Создание товаров

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

1. Начнем с заполнения медиагалереи. Она находится в верхнем меню бота на вкладке Магазин.

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

Обратите внимание на то, что изображение не должно занимать больше 10 мегабайт!

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

4. Далее перейдем к созданию категорий. Их так же можно создать неограниченное количество.

Меню категорий находится в верхнем меню бота на вкладке Магазин.

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

• Наименование — название категории;
• slug — настройка конечного url для категории;
• Порядковый номер — порядок в котором будут располагаться категории в магазине.

Остальные поля можно оставить без изменений.

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

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

6. Переходим к созданию самих товаров.

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

7. Для создания нового товара нажмите на кнопку Создать. В открывшемся окне заполните следующие поля:

• Наименование — название товара;
• Главное медиа — отображается в списке товаров и как мини изображение товара в корзине;
  
• Основная категория — используется для формирования URL, если мы перейдем в товар из дополнительной категории то в URL увидим все равно SLUG основной категории;
• slug — настройка конечного url для товара;
• Цена — цена товара;
• Порядковый номер — влияет на порядок отображения товара в категории.

Остальные поля заполняются по желанию.

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

После создания всех товаров, перед нами будет примерно следующий результат:

Настройки магазина

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

1. В настройки магазина можно попасть из раздела Магазин в верхнем меню бота, нажав в выпадающем списке на Настройки магазина.

2. После перехода в настройки магазина откроется окно в котором нужно заполнить следующие поля:

• Тип заявки — выпадающий список с выбором вида заявки созданного ранее в боте;
• Начальный статус для заказа — выпадающий список с выбором статуса заявки созданного ранее в боте (при создании корзины);
• Начальный статус для размещения заказа — выпадающий список с выбором статуса заявки созданного ранее в боте (превращение корзины в заказ);
• Cтатус заказа после успешной оплаты счета — выпадающий список с выбором статуса заявки созданного ранее в боте;
• Cтатус заказа при отмене счета — выпадающий список с выбором статуса заявки созданного ранее в боте;
• Cтатус заказа при возникновении ошибки оплаты — выпадающий список с выбором статуса заявки созданного ранее в боте;
• Наименование — название магазина;
• slug — настройка конечного url, который будет иметь магазин test.metabot.dev/store/{SLUG}, задать можно только SLUG все остальное формируется автоматически.

Остальные поля заполняются по желанию.

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

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

Создание бота для авторизации

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

1. Для начала перейдем в меню ссылок в настройках бота.

2. Здесь при помощи кнопки Создать, добавим новую ссылку. В открывшемся окне заполним следующие поля:

• Имя — название ссылки;
• Тип ссылки — из выпадающего списка выберите Магазин — Главная.

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

4. Затем создаем стартовый скрипт и добавляем в него команду Отправить текст с макро-ссылкой: "Приветствую! Чтобы начать покупки в нашем магазине, перейдите по ссылке: {{^Магазин}}".

5. Последним этапом создаем маршрут на этот скрипт и канал Telegram в боте.

Таким образом мы получим бот, отправляющий ссылку на магазин.

При переходе по ссылке пользователю откроется созданный нами магазин.

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

Поздравляем вас с прохождением урока!

Урок 7: Регистрация в боте

В данном уроке вы узнаете как реализовать регистрацию и авторизацию в боте на платформе Metabot.

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

Подробнее изучить работу бота вы можете с помощью нашего примера — бота в Telegram: @RegistrationMetabot

В этом уроке вы познакомитесь с таким функционалом платформы как Персоны.

Перед началом следует ознакомиться с предыдущими уроками Hello Humans: ваше руководство по быстрому старту и Metabot 101: Вывод фото в боте по REST API

Инструкция по разработке: Создание скриптов

1. Чтобы не отвлекаться на это в будущем, сразу создадим стартовый скрипт с приветствием, маршрут связанный с ним и канал Телеграм, при помощи которого будем тестировать бота, как мы делали это в предыдущих уроках.

Нам потребуются следующие скрипты:

• Стартовый скрипт;
• Меню;
• Fallback;
• Скрипт с выбором регистрации\авторизации;
• Скрипты регистрации;
• Скрипты авторизации.

Перейдем к их созданию.

Стартовый скрипт и скрипт с выбором регистрации\авторизации

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

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

2. Для данного скрипта нам нужно добавить команду Отправить текст с объяснением, что пользователю делать дальше, и две кнопки меню: одна с переходом к регистрации, другая с переходом к авторизации.

Скрипт меню и Fallback

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

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

Скрипт Fallback — это скрипт, который будет выполняться в том случае, если пользователь ввел вопрос/намерение или фразу не заложенные в базе знаний вашего бота.

4. В свойствах данного скрипта следует установить тип Fallback:

В данном уроке мы попробуем интересный способ реализации данного скрипта.

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

var randomStrings = [
        "Извините, я Вас не понял. Следуйте указаниям меню.",
        "Попробуйте воспользоваться разделами меню.",
        "Можете выбрать один из предложенных вариантов ответов."
    ];

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

lead.setAttr('randomAnswer', randomStrings[randomIndex]);

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

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

Основные скрипты для работы бота созданы. Перейдем к созданию регистрации и авторизации.

Скрипты регистрации

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

Нам потребуются следующие скрипты:

• Скрипты сбора данных;
• Скрипт проверки;
• Скрипт проверки почты;
• Скрипт "Почта занята";
• Создание персоны.

Перейдем к их созданию.

Скрипты сбора данных

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

1. В таком скрипте нужно создать команду Запросить значение, команду перехода на следующий скрипт и команду перехода на скрипт проверки.

Для примера разберем скрипт сбора информации об имени:

1. Первым делом бот запрашивает имя пользователя.
2. Затем происходит проверка: если пользователь передумал и ввел одно из ключевых слов, указанных в условии, то регистрация прерывается и бот переходит к Скрипту выбора. Данную проверку можно добавлять после каждой команды Запросить значение.
3. Далее бот запрашивает фамилию пользователя и снова выполняет проверку.
4. Затем бот проверяет существует ли тег исправление. Если его нет, то происходит переход к следующему скрипту сбора данных.
5. Если же тег был найден, то бот переходит к скрипту проверки.

Проверка на прерывание регистрации:

if (['отмена','назад','выход','стоп'].indexOf(lead.getAttr('lead_name').toLowerCase()) >= 0) {
return true;
}

Данные скрипты необязательны и их может быть как много, так и вообще не быть.

Скрипт проверки

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

2. В скрипте проверки нужно создать две команды: команду Добавить тег исправление и Отправить текст со всеми ранее собранными данными.

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

Скрипт проверки почты

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

4. Первым делом нужно добавить команду Удалить теги и удалить тег исправление.

5. Затем запрашиваем почту у пользователя со следующим регулярным выражением: (отмена|[^@\s]+@[^@\s]+\.[^@\s]+).

6. Далее выполняем проверку на прерывание регистрации.

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

//Проверяем есть ли зарегистрованная почта

let lead_email = lead.getAttr('lead_email');

let persons = bot.findPersons([["email", lead_email]]);

if (persons.length == 0){
    lead.setAttr('email', null);
}

Этот код ищет персону с заданным email в боте, и если не находит, то возвращает null.

Скрипт "Почта занята"

8. Этот скрипт должен содержать всего две команды: отправка текста с оповещением и переход к скрипту запроса почты.

Скрипт создания персоны

В данном скрипте происходит создание персоны с заданной почтой и переход к авторизации.

9. Для создания команды с созданием персоны используйте данный код:

//Создаем для лида персону
lead.createPersonForCurrentLead({
  'is_external'         : 1,
  'firstname'           : lead.getAttr('lead_name'),
  'lastname'            : lead.getAttr('lead_surname'),
  'email'               : lead.getAttr('lead_email'),
  'comment'             : lead.getAttr('lead_birthday') + ', ' + lead.getAttr('lead_gender')
});

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

10. Затем отправляем текст с оповещением пользователя о завершении регистрации и добавляем в меню кнопку с переходом к авторизации.

Скрипты авторизации

В процессе авторизации бот будет узнавать почту у пользователя, затем проверять ее на занятость и отправлять PIN на нее для авторизации.

Нам потребуются следующие скрипты:

• Скрипт запроса почты;
  
• Скрипт проверки почты;
• Скрипт отправки PIN;
• Скрипт ввода PIN;
• Скрипт проверки PIN.

Перейдем к их созданию.

Скрипт запроса почты

В этот скрипт пользователь попадает из Скрипта выбора.

Тут повторяются команды из скрипта запроса почты для регистрации.

1. Запрашиваем почту у пользователя со следующим регулярным выражением: (отмена|[^@\s]+@[^@\s]+\.[^@\s]+).

2. Далее выполняем проверку на прерывание регистрации.

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

5. В меню данного скрипта добавляем кнопки перехода к следующему скрипту авторизации, замены почты и Скрипту выбора.

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

Скрипт проверки почты

Данный скрипт так же повторяет команды регистрации.

6. Создаем JS скрипт с проверкой на существование персоны с такой почтой и, в зависимости от ответа, выполняем скрипт отправки PIN или запроса почты.

//Проверяем есть ли зарегистрованная почта

let lead_email = lead.getAttr('lead_email');

let persons = bot.findPersons([["email", lead_email]]);

if (persons.length == 0){
    lead.setAttr('email', null);
}

Скрипт отправки PIN

7. В данном скрипте следует создать генератор PIN-кода и команду отправки письма на почту.

//Генерируем временный пароль------------------------------------------------------------

let password = String(Math.floor(Math.random() * (100000 - 10000 + 1) + 10000));

//---------------------------------------------------------------------------------------

lead.setAttr('password', password);

8. В меню добавляем кнопки перехода к следующему скрипту авторизации, повторной отправки PIN и Скрипту выбора.

Для повторной отправки PIN нужно добавить еще один скрипт, в котором будет находиться только команда перехода к скрипту отправки PIN.

Скрипт ввода PIN

9. В данном скрипте нужны команды запроса PIN и перехода к скрипту проверки PIN.

Скрипт проверки PIN и "Неверный PIN"

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

10. Для проверки добавляем команду с условием при выполнении которого будет вызываться скрипт "Неверный PIN".

Можно так же добавить тег авторизовался.

11. Последним делом добавляем команду перехода в меню.

12. В скрипте "Неверный PIN" добавляем команду отправки текста с оповещением о неправильном PIN-коде.

13. В меню добавляем следующие кнопки:

• Запрос PIN;
• Отправка PIN;
• Запрос почты;
• Скрипт выбора регистрации\авторизации.

Бот завершен! Теперь при регистрации в нем на вкладке Персоны платформы будут создаваться персоны:

Поздравляем вас с прохождением урока!

Урок 8: Диалоговый интерфейс к ИТ системам

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

Чат-бот выступает в качестве дополнительного сервиса, расширяющего основную систему, будто то ERP, Ecomm, Helpdesk или другая информационная система (далее просто — система), возможностью вести интерактивные диалоговые коммуникации с пользователями системы в мессенджерах, социальных сетях и онлайн-чате для сайта.

Что дают интеграции для бизнеса:

• Возможность реализовать бесшовный клиентский опыт по всему пути клиента, например, регистрация на сайте, прием тикетов в поддержку и др;
• Возможность отправлять сервисные и маркетинговые уведомления прямо из систем в мессенджеры на смартфоны клиентам при наступлении тех или иных событиях в основных системах. Например, оживление брошенной корзины;
• Сможете установить прямой канал связи с каждым пользователем ваших веб-сайтов, порталов, веб-сервисов с поддержкой интерактивных диалоговых коммуникаций;
• Возможность создать виртуальную личность бренда или виртуального помощника, взаимодействующего с бэк-энд системами компании и публичными Интернет-сервисами;
  
• Альтернативу мобильному приложению в мессенджере. При желании сможете добавлять много функционала и очень быстро. Сможете оперативно тестировать множество гипотез.

Ниже описаны основные принципы и важные нюансы, на которых строится интеграция основных системы и чат-бота и обмен данными между ними.

Коммуникации в чат-боте

Под коммуникацией подразумевается диалоговый сценарий или скрипт, заранее спроектированный и запускаемый на коммуникационной low-code платформе Metabot, на которой разрабатывается и выполняется чат-бот. Коммуникации могут быть абсолютно любыми и варьироваться от самых простых, таких как отправка текстового сообщения/уведомления, до более сложных и растянутых во времени, которые могут инициировать дополнительные вспомогательные коммуникации, например, напоминания, подтягивать данные с веб-сайта по API и прочее.

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

Карты коммуникации 

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

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

Пример карты коммуникаций для личного аккаунта пользователя:

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

Приведем пример еще одной карты коммуникаций, в этот раз для реального проекта — чат-бота для Семейного сайта https://fmlst.ru, который выступил мобильным интерфейсом с конструктору семейных веб-сайтов. При желании, можете попробовать чат-бот по адресу: https://t.me/MoyaSemiyaBot. 

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

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

Точки интеграции

Каждой коммуникации соответствует точка интеграции (integration endpoint). Коммуникации запускаются с помощью вызова нужной точки интеграции, название которой указывается в URL, а в теле запроса в script_request_params указываются параметры коммуникации, например, список ID всех пользователей, которых нужно уведомить. 

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

Взаимодействия портала и чат-бота происходят по протоколу REST API, а точки взаимодействия, в которых происходит обращение одной системы к ресурсам другой называются точками интеграции (или endpoints). 

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

Ниже показан пример описания точек интеграции для личного аккаунта пользователей:

Метод: POST
URL: {Server URL}/bots/{botId}/call/users/update
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>,
    "lastname": "<Фамилия>",
    "firstname": "<Имя>",
    "patronymic": "<Отчество>",
    "role": "<Роль/required>",
    "active": <Статус активности/bool>,
    "phone": "<Мобильный телефон>",
    "email": "<Email адрес>",
    "location": {
      "country": "<Страна местоположения>",
      "region": "<Регион>",
      "city": "<Город>"
    }
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/users/connect-bot
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Приведем еще несколько примеров:

Метод: POST
URL: {Server URL}/bots/{botId}/call/transaction/thank-you
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>,
    "orderId": <ID заказа/required>
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/post/new
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "postId": <ID публикации/required>,    
    "authorId": <ID автора публикации/required>,    
    "userIds": [
      <ID первого пользователя/required>,
      <ID второго пользователя>,
      ..
      <ID N-го пользователя>
    ]
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пост не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/comment/new
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "postId": <ID публикации/required>,    
    "authorId": <ID автора публикации/required>,    
    "commentAuthorId": <ID автора комментария>,
    "comment": "<комментарий>",
    "userIds": [
      <ID первого пользователя/required>,
      <ID второго пользователя>,
      ..
      <ID N-го пользователя>
    ]
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пост не найден"
}

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

Затем (точнее — все вместе) вы аналогичным образом вы планируете и специфицируете интеграцию в обратную сторону — от чат-бота к основной системе. Обратите внимание, что в примерах выше основная система передает не полную информацию, например, в точке интеграции для уведомления о новой публикации на сайте есть только ID публикации, ID автора и список ID пользователей, которых нужно уведомить, но отсутствует название и текст публикации.

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

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

{
  "userId": "<ID пользователя>",
  "email": "<Адрес электронной почты>",
  "phone": "<Телефонный номер>"
}

{
  "userId": 127,
  "surname": "Александр",
  "name": "Сергеевич",
  "patronymic": "Пушкин",
  "role": "user",
  "isActive": true,
  "phone": "79187777777",
  "email": "address@domain.ru",
  "location": {
    "country": "Россия",
    "region": "Ставропольский край",
    "city": "Ставрополь"
  }
}

{
  "firstname": "<Имя>",
  "lastname": "<Фамилия>", 
  "middlename": "<Отчество>",
  "role": "<Роль>",
  "phone": "<Мобильный телефон>",
  "email": "<Email адрес>",
  "location": {
    "country": "<Страна местоположения>",
    "region": "<Регион>",
    "city": "<Город>"
  }
}

{
  "userId": 1177,
}

Синхронизация данных

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

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

Например, если нужно отправить комментарий 50 пользователям о новости, чат-бот подгрузит данные только по новости, сделает рассылку пользователям в чат-боте и на этом все. Когда в системе произойдут новые изменения, система запустит новую коммуникацию и чат-бот снова подтянет нужные данные.

В ходе диалога с чат-ботом пользователи могут внести изменения в системе. Например, получив новость пользователи могут прокомментировать ее. В этому случае, чат-бот вызовет нужные методы API. Основная система зафиксирует изменения в базе данных и затем запустит новую коммуникацию. Цикл повторится.

Подготовка данных для обеспечения коммуникации чат-ботом осуществляется двумя способами:

• Данные, необходимые для обеспечения коммуникации, подгружаются чат-ботом с помощью API портала по необходимости (pull on demand):
  • Это наиболее часто используемый метод для уведомлений связанных с бизнес-логикой;
  • В этом случае, основная система вызывает нужную коммуникацию, передает ID сущности, ID пользователей (или одного пользователя). Затем чат-бот по ID cущности, подгружает (pull'ит) по API данные необходимые для обеспечения коммуникации;
    
• Все данные, необходимые для обеспечения коммуникации, целиком и полностью передаются в чат-бот в момент вызова коммуникации порталом (push):
  • Например, можно использовать этот метод используется для синхронизации данных о пользователях. Каждый раз сведения об учетных записях пользователя меняются в основной системе, необходимо их отправлять чат-боту для актуализации. 

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

Авторизация и регистрация пользователей 

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

После того, как пользователь портала привязал чат-бота к своей учетной записи, а говоря техническим языком, после того, как было установлено однозначное соответствие между идентификатором пользователя в чат-боте (personId/leadId в боте) c идентификатором пользователя в основной системе (userId в системе), можно переходить к коммуникациям. 

Таблица соответствия ID пользователей двух систем хранится в чат-боте. Хранить ID пользователя в чат-боте в БД основной системы нет необходимости.

Для отправки коммуникации системе достаточно сообщить в запросе к чат-боту ID пользователя в системе (userId), которому необходимо отправить коммуникацию. 

Суть интеграции заключается в использовании API для поиска пользователя системы по идентификатору: 

1. Чат-бот запрашивает у пользователя ID, email или телефон, ищет пользователя в основной системе по API, и если находит, переходит к двухфакторной авторизации через SMS.
2. В Telegram можно предложить вариант входа без SMS, сравнивая номер, привязанный к Telegram, с номером, привязанным в основной системе.
3. После подтверждения идентификации чат-бот должен сообщить системе, что пользователь привязал чат-бот. Это делается с помощью метода API системы user/connect-bot.
4. Метод user/connect-bot устанавливает признак того, что пользователь привязал чат-бот. Теперь система может отправлять сообщения (коммуникации) этому пользователю в чат-бот.

Аналогично работает регистрация через чат-бот:

1. Сначала пользователь вводит свои данные, чат-бот ищет пользователя в системе, а если не находит, то создает новую запись с помощью API. 
2. Система создает пользователя и возвращает идентификатор нового пользователя (userId).
3. Чат-бот выполняет запрос user/connect-bot, чтобы установить у пользователя признак, что чат-бот привязан.
4. Теперь канал прямой связи с пользователем установлен и можно вести диалог. 

Возможны и другие варианты интеграции — все зависит от технических возможностей системы и доступных ИТ ресурсов.

Структура API чат-бота

Узнать структуру запроса и проверить работу внутреннего API чат-бота можно с помощью Swagger, доступного по адресу платформы: https://app.metabot24.com/api/docs.

Доступ к Swagger могут получить только авторизованные пользователи, привязанные к проекту. Зарегистрируйтесь на платформе по адресу https://app.metabot24.com, подтвердите электронную почту, авторизуйтесь и затем перейдите по ссылке. 

Внимание! При работе в Swagger платформы будут выполняться реальные API запросы, а не эмуляция API.

Ниже показан пример из Swagger.

Обращение к чат-боту осуществляется через API платформы "POST ​/bots​/{botId}​/call​/{alias}", где:

1. В качестве метода используется POST.
2. Для идентификатора чат-бота botId на платформе укажите ID вашего бота на платформе, которого предварительно создайте в вашем аккаунте. 
   1. ID вы сможете узнать, наведя мышкой на название вашего бота в панели управления.
3. Уникальный идентификатор alias точки интеграции (эндпоинта), который соответствует конкретной коммуникации.
   1. Узнать название точки интеграции можно воспользовавшись описанием точек интеграции.
4. Абсолютно все остальные параметры запроса всегда передаются в тело запроса в массив script_request_params.
   1. Остальные параметры, которые по умолчанию выдает Swagger, можете игнорировать.
   2. Чтобы узнать точный список параметров запроса, воспользуйтесь таблицами с описанием точек интеграции.
   3. Пример body запроса:

   4. {
        "script_request_params": {
          "requestId": 100,
          "userId": 1707
        }
      }

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

Название точки интеграции (и одновременно название коммуникации) подчеркнуто красным, а содержимое script_request_params описано в центральной колонке. 

Авторизация запросов API

Адрес сервера API:

https://app.metabot24.com/api/v1 

Для авторизации запросов чат-бота используется Authorization Bearer Token. При каждом вызове API добавляйте заголовок авторизации, пример:

Authorization: Bearer <Access Token>
Accept: application/json
Content-Type: application/json
Access Token предоставляется администратором Metabot.

Обработка ошибок

В случае успеха, чат-бот возвращает код ответа 200 OK, а в теле запроса, содержится информация об успешном выполнении, например:

{ 
  "success": true
}

Если есть ошибка, то также возвращается 200 ОК и дополнительно возвращается текст ошибки в поле message, например:

{ 
  "success": false,
  "message": "Сообщение об ошибке"
}

{ 
  "success": false,
  "errorCode": 422,
  "message": "Ошибка валидации"
}

Все возможные коды ответа сервера:

Подробнее про интеграционные возможности платформы Metabot смотрите в разделе Конструктор API.

Архитектура чат-бота

В РАЗРАБОТКЕ. Обратитесь за шаблоном решения в поддержку.

Урок 9: Создание интеллектуального квиза для путешественников — интеграция Manychat с Metabot

В этой статье мы рассмотрим, как интегрировать Manychat, отличный инструмент для построения воронок, с платформой Metabot в качестве Low-code инструмента для бэкенд-разработки. Manychat обладает удобным интерфейсом для работы с пользователями, но не поддерживает написание кода. Metabot идеально дополняет Manychat, предлагая возможности быстрой разработки и легкой интеграции с чат-ботами.

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

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

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

Видео-инструкция по интеграции ManyChat и Metabot 

Обзор интеграции

1. Сначала нужно создать бота в системе Metabot.

2. Для авторизации запросов необходимо создать пользователя с типом API и сгенерировать токен.

3. В боте нужно создать endpoint, который будет обрабатывать запросы от Manychat.

4. Затем нужно написать код для обработки запросов. Пример кода показывает, как обработать запросы и вернуть результат в формате, подходящем для Manychat.

Пример кода эндпоинта

snippet('Business.Helpers.Response');

// Check if the necessary fields are present in the request
if (!request.json || 
    !request.json.destinationCoefficient ||
    !request.json.nights ||
    !request.json.travelers ||
    !request.json.averageSpendingScore ||
    !request.json.seasonCoefficient ||
    !request.json.tripPurposeCoefficient ||
    !request.json.familyTravelCoefficient ||
    !request.json.format) {
  return getErrorResponse("Required fields are missing");
}

// Ensure that format is either 'raw' or 'manychat'
if (request.json.format !== 'raw' && request.json.format !== 'manychat') {
  return getErrorResponse("Invalid format specified");
}

// Extract values from the request
const destinationCoefficient = request.json.destinationCoefficient;
const seasonCoefficient = request.json.seasonCoefficient;
const tripPurposeCoefficient = request.json.tripPurposeCoefficient;
const familyTravelCoefficient = request.json.familyTravelCoefficient;

// Base daily cost based on average spending score (example values)
let baseDailyCost;
if (request.json.averageSpendingScore <= 1.75) {
  baseDailyCost = 50; // Low spender
} else if (request.json.averageSpendingScore <= 2.5) {
  baseDailyCost = 100; // Moderate spender
} else if (request.json.averageSpendingScore <= 3.25) {
  baseDailyCost = 150; // High spender
} else {
  baseDailyCost = 200; // Ultra spender
}

// Calculating the total recommended amount
const totalAmount = (baseDailyCost * request.json.destinationCoefficient * request.json.nights * request.json.travelers) * 
                    seasonCoefficient * 
                    tripPurposeCoefficient * 
                    familyTravelCoefficient;

// Determine the response format
if (request.json.format === 'raw') {
  // Returning the calculated budget in raw format
  return getSuccessResponseWithJson({
    calculatedBudget: totalAmount
  });
} else {
  // Returning the calculated budget in Manychat format
  return {
    "version": "v2",
    "content": {
  /*    "messages": [
        {
          "type": "text",
          "text": `Ok! I got it`
        }
        // Additional messages can be added here
      ],*/
      "actions": [
        {
          "action": "set_field_value",
          "field_name": "budget_estimate_amount", // Custom field name in Manychat
          "value": totalAmount.toString()  // Setting the calculated budget as the value
        }
      ],
      "quick_replies": []
    }
  };
}

Обратите внимание, что мы возвращаем ответ в двух форматах:

• Raw Format — простой JSON. Для интеграции с Manychat он вам не понадобится;
• Manychat Format — формат, подходящий для динамических сообщений Manychat.
  

Код плагина Business.Helpers.Response

Плагин Business.Helpers.Response служит утилитой для стандартизации ответов API в бизнес-приложениях. Его основная цель - упростить создание последовательных и структурированных ответов для различных сценариев, возникающих во время взаимодействия с API.

Код плагина доступен в Библиотеке плагинов. Создайте плагин с таким же названием в вашем бизнесе на платформе Metabot, скопировав код плагина.

Интеграция с ManyChat

1. В Manychat реализуйте команду для динамического формирования контента, указав URL endpoint MetaBot.

Подробнее про эту команду: https://support.manychat.com/support/solutions/articles/36000143342-dev-tools-dynamic-block 

2. В Header запроса укажите токен авторизации, а в Body — параметры из воронки Manychat.

Подробнее про формат обмена REST API: https://manychat.github.io/dynamic_block_docs/ 

Metabot API Endpoint URL: https://app.metabot24.com/api/v1/bots/{BOT-ID}/call/{ENDPOINT-ADDRESS}

3. Настройте заголовок запроса:

4. Настройте тело запроса:

Пример тела запроса

{
  "script_request_params": {
    "destinationCoefficient": 1,
    "nights": 5,
    "travelers": 1,
    "averageSpendingScore": 2.25,
    "seasonCoefficient": 1.0,
    "tripPurposeCoefficient": 1.0,
    "familyTravelCoefficient": 1.0,
    "format": "manychat"
  }
}

Пример тела ответа

{
    "version": "v2",
    "content": {
        "actions": [
            {
                "action": "set_field_value",
                "field_name": "budget_estimate_amount",
                "value": "500"
            }
        ],
        "quick_replies": []
    }
}

Всегда оборачивайте все запросы к эндпоинтам вашего бота на платформы Metabot в "script_request_params"!

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

Урок 10: Создание PHP плагина Metabot для расширения бота и платформы

В этом уроке вы научитесь создавать PHP плагин для платформы Metabot и использовать его в JavaScript коде бота. Этот навык позволяет расширять функциональность платформы, добавляя новые возможности в платформу и ваши боты. Вы поймете, как безопасно и эффективно интегрировать PHP и JavaScript, обеспечивая гибкость и мощь в разработке ботов.

Урок состоит из двух частей. Сперва вы создаете условно бэк - сам PHP плагин. Затем вы подключаете его на фронте, в боте, для доступа к PHP через JS Low-Code.

Дополнительно смотрите разделы документации:

• Плагины
• Плагины PHP

1. Создание PHP плагина

PHP плагины могут быть только общими и добавляются только администраторами платформы из-за доступа к базе данных и другим ботам. Это мера предосторожности для обеспечения безопасности.

1. Создайте новый плагин, если необходимо. В этом уроке мы назвали плагин PluginBoilerplate.

2. В плагине создайте скрипт с расширением PHP (ОБЕРТКА ДЛЯ V8).

Metabot поддерживает три вида скриптов в плагине: JavaScript, PHP, PHP (ОБЕРТКА для V8). JavaScript — это обычный Low-Code, как и скриптах самого бота, в который вы можете вынести код для повторного использования в разных скриптах в боте или в других JS плагинах. PHP — это модуль PHP, который используется в других PHP модулях или в PHP обертках. PHP Wrapper for V8 или PHP (Обертка для V8)   —  это специальный модуль PHP, который доступен через JS на уровне бота, т.е. это некий промежуточный слой на PHP для которого можно определить JS интерфейс.

3. Скопируйте эту заготовку кода в скрипт вашей PHP обертки.

<?php
// Определяем пространство имен для плагина
namespace Plugins\Dynamic\Common\PluginBoilerplate\V8Wrapper;

// Подключаем необходимые классы
use App\Bot;
use App\Lead;
use App\Business;
use App\Modules\V8\Exception\UnauthotizedV8Exception;
use App\Modules\V8\ScriptBase;

// Определяем класс PhpPlugin, наследуя его от базового класса ScriptBase
class PhpPlugin extends ScriptBase {
    /** @var Business|null */
    protected $_business = null; // Свойство для хранения объекта бизнеса, с которым взаимодействует плагин

    /** @var Bot */
    protected $_bot = null; // Свойство для хранения текущего объекта бота, с которым взаимодействует плагин
    
    /** @var Lead */
    protected $_lead; // Свойство для хранения объекта лида, с которым взаимодействует плагин
    
    /** @var Bot */
    protected $_runFromBot = null; // Свойство для хранения объекта бота, от которого был запущен плагин    
    
    /**
     * Инициализация JavaScript обёртки
     *
     * @param array $params Параметры, передаваемые из JS скрипта
     *
     * @throws UnauthotizedV8Exception Выбрасывает исключение при нарушении политик безопасности
     */
    public function initializeJs($params)
    {
        // Инициализация свойств из переданных параметров
        $this->_business = $params['business'] ?? null;
        $this->_runFromBot = $params['bot'] ?? null;
        $this->_lead = $params['lead'] ?? null;
        
        // Установка объекта бота, если он доступен у лида
        if ($this->_lead && $this->_lead->bot) {
            $this->_bot = $this->_lead->bot;
        }

        // Вызов метода для проверки политик безопасности
        $this->checkPolicy();
    }    
    
    /**
     * Метод для проверки политик безопасности.
     * Этот метод гарантирует, что взаимодействие с плагином происходит в контексте 
     * правильно определенных объектов бизнеса, бота и лида. 
     * Выбрасывает исключение при обнаружении несоответствий, 
     * обеспечивая безопасное использование плагина.
     */
    protected function checkPolicy()
    {
        // Проверка на наличие и корректность объекта бизнеса
        if (empty($this->_business) || !($this->_business instanceof Business)) {
            throw new UnauthotizedV8Exception();
        }
        // Проверка на наличие и корректность объекта бота
        if (empty($this->_bot) || !($this->_bot instanceof Bot)) {
            throw new UnauthotizedV8Exception();
        }
        // Проверка на наличие и корректность объекта лида
        if (empty($this->_lead) || !($this->_lead instanceof Lead)) {
            throw new UnauthotizedV8Exception();
        }
        // Проверка на наличие и корректность объекта бота, который запустил плагин
        // Используется, например, когда: 
        //   нужно запустить скрипт в одном боте (_runFromBot),
        //   а получить тикет/др. сущности по другому боту (_bot).
        //   _bot и _runFromBot запоминают, что к чему принадлежит и откуда получено.
        if (empty($this->_runFromBot) || !($this->_runFromBot instanceof Bot)) {
            throw new UnauthotizedV8Exception();
        }        
      
      	// Проверка на на принадлежность бота, указанному бизнесу
        if (!empty($this->_bot) && $this->_bot->business_id != $this->_business->id) {
            throw new UnauthotizedV8Exception();
        }      
        
        // Здесь могут быть добавлены дополнительные условия безопасности
    } 
    
    // Метод для проверки работоспособности плагина
    public function itWorks() {
        $this->checkPolicy();  
      
        return "Plugin works!"; // Возвращаем подтверждающее сообщение
    }    
}

Создание PHP плагинов - ответственный процесс, требующий строгого контроля безопасности. Подробнее о checkPolicy() смотрите ниже.

4. Важно правильно указать namespace, иначе ваш плагин не подключится. Замените ИмяПлагина на название вашего плагина. В нашем примере это PluginBoilerplate.

namespace Plugins\Dynamic\Common\ИмяПлагина\V8Wrapper;

Указывайте имя плагина с учетом регистра. PluginBoilerplate и pluginBoilerplate это разные плагины!

5. Важно правильно указать имя класса в соответствии с названием скрипта плагина. 

Вместо ИмяКласса укажите название вашего класса.

class ИмяКласса extends ScriptBase {

Название класса должно совпадать с названием скрипта PHP обертки! В противном случае ваш плагин не будет работать!

6. Создайте JS скрипт в плагине. Выберите созданную ранее PHP обертку. Название может быть любое, но мы рекомендуем JS скрипт называть также как PHP скрипт, это поможет вам избежать путаницы в дальнейшем.

В итоге, у вас должен получиться плагин с двумя скриптами:

Дополнение: Важность методов initializeJs и checkPolicy

В создании PHP плагинов для Metabot, особое внимание следует уделить методам initializeJs и checkPolicy. Эти методы играют ключевую роль в обеспечении безопасности и правильной инициализации плагина.

Правильная реализация методов initializeJs и checkPolicy гарантирует, что ваш PHP плагин будет не только функциональным, но и безопасным для использования в рамках платформы Metabot. Это обеспечит стабильность и надежность ваших решений на платформе.

2. Использование PHP плагина

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

1. Создайте команды Вызвать JavaScript и разместите в ней следующий код.

// Подключаем PHP плагин. Эта команда загружает JavaScript обёртку для PHP плагина.
require("Common.PluginBoilerplate.PhpPlugin")

// Создаём переменную 'plugin', которая ссылается на экземпляр класса PHP плагина.
let plugin = CommonPluginBoilerplatePhpPlugin

// Вызываем метод 'itWorks()' у объекта плагина. 
let result = plugin.itWorks()

// Используем функцию 'debug' для вывода результата работы метода в отладочную консоль.
debug(result)

Разберем, что здесь происходит и обсудим важные нюансы.

1. Подключение JS Плагина.

require("Common.PluginBoilerplate.PhpPlugin")

Common.PluginBoilerplate.PhpPlugin — это идентификатор JS скрипта из нашего плагина в системе Metabot.

Обратите внимание, это название JS скрипта, который связан с PHP скрипом! Это не название PHP скрипта!

Регистр важен!

Не используйте `let plugin = require("Common.PluginBoilerplate.PhpPlugin")` синтаксис для подключения PHP. Используйте точный синтаксис require без присваивания переменной, 

2. Обращение к PHP плагину.

После вызова require, вы можете обращаться к экземпляру PHP класса.

Платформа автоматически создает экземпляр. Название формируется путём объединения названий уровня доступа ('Common'), названия плагина ('PluginBoilerplate') и самого класса PHP ('PhpPlugin').

let result = CommonPluginBoilerplatePhpPlugin.itWorks()

Либо вы можете присвоить экземпляр в более короткую переменную:

let plugin = CommonPluginBoilerplatePhpPlugin
let result = plugin.itWorks()

3. Базовая заготовка PHP Plugin Boilerplate содержит метод itWorks(), который возвращает сообщение о корректной работе плагина.

Если всё выполнено правильно, вы увидите сообщение "It works!" в вашем боте.

Дополнение: Кэширование PHP плагинов и перезапуск очереди

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

Когда вы вносите изменения в PHP код плагина, для того чтобы они вступили в силу, необходимо перезапустить очередь на платформе Metabot. Это можно сделать следующим образом:

1. Переход в Настройки Платформы:

   • Откройте раздел настроек платформы Metabot. Это центральное место, где управляются основные параметры вашего бота и платформы в целом.

2. Отключение и Включение Cron Scheduler:

   • Найдите опцию или раздел, относящийся к Cron Scheduler (планировщику заданий).
   • Сначала отключите Cron Scheduler. Это остановит текущую очередь заданий, включая выполнение задач связанных с PHP плагинами.
   • Затем включите Cron Scheduler обратно. Это инициирует новую сессию очереди, при этом кэш PHP плагинов будет очищен и ваши изменения начнут действовать.

3. Отладка PHP плагина

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

1: Проверка логов платформы

• Доступ к Логам: Обычно почти все ошибки можно получить через отладку бота(смотрите ниже). Однако, можно допустить ошибку, которая приведет к тому, что PHP на платформе не соберется и до уведомления в боте платформа просто не дойдет. В этом случае, запросите доступ к логам платформы Metabot. Обычно они находятся в /storage/logs. Логи могут предоставить ценную информацию о внутренних ошибках платформы и вашего плагина. 
• Чтение Логов: Ищите ошибки, связанные с вашим плагином, включая исключения, предупреждения и другие сообщения об ошибках.

2: Режим отладки бота

• Включение Режима Отладки: Включите режим отладки в настройках вашего бота. Это позволит получать подробные сообщения об ошибках.
• Отладка на Уровне Лида: Для конкретных лидов, активируйте высший уровень отладки. Это обеспечит детальную информацию об ошибках, возникающих при взаимодействии с вашим плагином.

3: Проверка конфигурации плагина

• Проверка Класса Обертки PHP: Убедитесь, что класс обёртки PHP правильно спроектирован. Название класса должно соответствовать названию скрипта обёртки.
• Обязательные Методы: Проверьте, что в вашем классе реализованы методы initializeJs и checkPolicy. Эти методы критически важны для функционирования плагина.

4: Проверка JavaScript интерфейса

• Создание JS Интерфейса: Убедитесь, что JavaScript интерфейс для доступа к PHP обёртке создан корректно.
• Синтаксис require: Проверьте, правильно ли вы используете require для подключения плагина. Удостоверьтесь, что название плагина и скрипта указаны верно.

5: Проверка интеграции PHP и JavaScript

• Название Класса PHP: Проверьте, что название PHP класса, которое склеивается из трех компонентов (уровень доступа, название плагина, название класса), указано верно.
• Тестирование Методов: Попробуйте вызвать различные методы вашего PHP класса через JavaScript, чтобы проверить их работоспособность.

6: Обращение за помощью

• Сообщество и Поддержка: Если вы столкнулись с трудноуловимыми или сложными проблемами, не стесняйтесь обращаться за помощью к сообществу Metabot или в службу поддержки.
• Документация: Периодически обращайтесь к официальной документации Metabot, где могут быть ответы на ваши вопросы.

Заключение

Поздравляем! Теперь вы умеете создавать PHP плагины для Metabot и интегрировать их в JS код бота. Это открывает новые возможности для расширения функционала платформы.