# Библиотека плагинов
# Плагин для Mindbox
| **Название плагина** | Mindbox |
| **Разработчик** | Официальные плагины от Metabot |
| **Авторы** | Петрова Ирина Дмитриевна ()
Гарашко Артем Юрьевич ([artem@metabot.org](mailto:artem@metabot.rg))
|
| **Дата создания** | 22 Ноября 2022 |
| **Последняя дата обновления** | 26 Ноября 2022 |
### Описание
Mindbox — это платформа автоматизации маркетинга и клиентских данных. Этот плагин к платформе Metabot позволяет интегрировать ваш чат-бот, разрабатываемый на Metabot, с платформой Mindbox. Подробнее с Mindbox можно ознакомиться на их официальном сайте: [https://mindbox.ru](https://mindbox.ru/).
Плагин позволяет автоматически добавлять клиентские данные, собранные чат-ботом в ходе диалога с клиентом, в Mindbox. С помощью плагина вы сможете организовать передачу данных в единый профиль клиента в Mindbox прямо из диалога в окне чата на сайте, в мессенджере или социальной сети.
### Подключение
Для интеграции Mindbox с вашим чат-ботом вам необходимо сделать несколько вещей:
1. На стороне Mindbox настройте все нужные точки интеграции и операции. Подробнее смотрите в [документации Mindbox](https://help.mindbox.ru/docs/%D0%BA%D0%B0%D0%BA-%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D1%82%D1%8C-%D0%B8-%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B8%D1%82%D1%8C-%D1%82%D0%BE%D1%87%D0%BA%D1%83-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8).
2. [Зарегистрируйтесь](https://app.metabot24.com/register) на платформе Metabot, подтвердите почту, [авторизуйтесь](https://app.metabot24.com/login) и создайте чат-бот.
3. Используйте готовый общий плагин или создайте плагин для своего бизнеса и скопируйте в него наш исходный код. Инструкции для обоих вариантов будут указаны ниже.
4. Создайте в чат-боте системный атрибут **mindbox.secretKey.<Системное имя точки интеграции>** и сохраните в него секретный ключ (токен) авторизации API запросов к Mindbox.
- Если у вас планируется несколько точек интеграции в чат-боте, то нужно задать свой ключ для каждой из них. Например, так:
- Mindbox.SecretKey.MyBusiness.Chatbot - атрибута с ключом для точки MyBusiness.Chatbot
- Mindbox.SecretKey.MyBusiness.Chatbot.Shop - атрибута с ключом для точки MyBusiness.Chatbot.Shop
- Внимание! Называйте атрибуты в точности и с учетом регистра именно так, как они указаны в Mindbox.
5. Реализуйте диалоговый сценарий (скрипт) с опросом данных пользователя (например, имя, фамилия, email адрес, телефон и прочее).
6. В конце диалога, обязательно (!) запросите согласие пользователя на обработку персональных данных и пришлите ссылку на положение о конфиденциальности компании. Если подписываете на маркетинговую рассылку, то дополнительно запросите согласие. Храните согласие в атрибуте лида вашего чат-бота на случай, если это понадобится юридической службе вашей компании.
7. Выберите универсальный или упрощенный метод для генерации запроса к Mindbox (смотрите детали ниже) и скопируйте код примера к себе в скрипт.
8. Кастомизируйте код интеграции под свои задачи. Если у вас возникнут затруднения, обратитесь за помощью в [Телеграм-чат](https://t.me/metabot_chatroom) cообщества или [поддержку Metabot](https://app.metabot24.com/help).
### Вызов в диалоге
Вы можете использовать одну из двух функций на ваш выбор. Первая - универсальная - принимает тело JSON запроса в качестве одного из параметров, вторая - параметризованная - принимает поля в качестве параметров и формируем тело запроса JSON с помощью первой функции.
#### Способ 1. Универсальная (JSON) функция
Первый способ использования плагина в диалоге — с помощью универсальной функции **callMindboxEndpoint()**. Вы сами формируете тело запроса в формате JSON и передаете его в функцию.
Пример использования универсального (JSON) метода:
```JavaScript
let email = lead.getAttr("email")
let phone = lead.getAttr("phone")
let lastName = lead.getAttr("lastName")
let firstName = lead.getAttr("firstName")
let endpointId = "<Идентификатор точки интеграции>"
let operation = "<Системное имя операции>"
let jsonBody = { "customer": {
"email": email,
"mobilePhone": phone,
"lastName": lastName,
"firstName": firstName,
"customFields": {
"AdCommunicationAgreement": true,
"PersonalDataAgreement": true
},
"subscriptions": [
{
"brand": "<Системное имя бренда подписки клиента>",
"pointOfContact": "<Системное имя канала подписки: Email, SMS, Viber, Webpush, Mobilepush>",
"topic": "<Внешний идентификатор тематики подписки>"
}
]
},
"pointOfContact": "<Внешний идентификатор точки контакта>"
}
// Подключаем сниппет кода из плагина Mindbox
snippet('Common.Mindbox.Operations')
// Вызываем точку интеграциии Mindbox и передаем нужный нам JSON
callMindboxEndpoint(endpointId, operation, jsonBody)
```
Функция требует передачи трех переменных **в строгом порядке**:
| endpointId | Уникальный идентификатор интеграции.
Не забудьте, что каждому endpointId соответствует свой secretKey, который нужно сохранить в системную атрибуту бота.
Интеграции настраивается в системе Mindbox.
|
| operation | Название операции в Mindbox. Каждому типу действия в Mindbox соответствует своя операция.
Список операций настраивается в системе Mindbox. |
| jsonBody | Тело запроса в формате JSON.
Формат тела запроса, различается в зависимости от типа операции. |
#### Способ 2. Альтернативная (параметризованная) функция
Второй способ использования плагина — с помощью альтернативной функции **callMindboxEndpointAlt()**, в которую вы передаете параметры запроса, а функция внутри себя формирует тело запроса в формате JSON и затем вызывает описанную выше универсальную функцию.
Пример использования альтернативного (параметризованного) метода:
```JavaScript
let email = lead.getAttr("email")
let phone = lead.getAttr("phone")
let lastName = lead.getAttr("lastName")
let firstName = lead.getAttr("firstName")
let endpointId = "<Идентификатор точки интеграции>"
let operation = "<Системное имя операции>"
// Подключаем сниппет кода из плагина Mindbox
snippet('Common.Mindbox.Operations')
// Вызываем точку интеграциии Mindbox и передаем нужные нам параметры
callMindboxEndpointAlt(endpointId, operation,
email, phone, lastName, firstName,
subscriptionTopic, pointOfContact)
```
Функция требует передачи нескольких переменных **в строгом порядке**. Добавляйте и удаляйте параметры по вкусу ;) но при этом не забудьте поменять в плагине код формирования JSON.
| endpointId | Уникальный идентификатор интеграции.
Не забудьте, что каждому endpointId соответствует свой secretKey, который нужно сохранить в системную атрибуту бота.
Интеграции настраивается в системе Mindbox.
|
| operation | Название операции в Mindbox. Каждому типу действия в Mindbox соответствует своя операция.
Список операций настраивается в системе Mindbox. |
| email | Email пользователя |
| phone | Мобильный телефон
|
| lastName | Фамилия
|
| firstName | Имя
|
| subscriptionTopic | Внешний идентификатор тематики подписки. Настраивается в Mindbox.
|
| pointOfContact | Внешний идентификатор точки контакта. Настраивается в Mindbox.
|
#### Варианты подключения плагина
Вы можете использовать один из двух вариантов: воспользоваться общим плагином без модификаций кода или же скопировать код плагина к себе и модифицировать код.
Вы можете использовать общий плагин и вызвать скрипт "Вызов операции" в точности следуя примерам выше. В этом случае, для использования общего плагина используйте вызов сниппета из коллекции общих плагинов **Common**:
```JavaScript
snippet('Common.Mindbox.Operations');
```
Либо, вы можете создать свой плагин в вашем бизнесе, скопировать наш и изменив код под себя, для этого:
1. Cоздайте плагин в вашем бизнесе и назовите его **Mindbox**.
2. Создайте в плагине скрипт и назовите его **Operations**.
3. Скопируйте код, размещенный ниже, в код нового скрипта.
В этому случае, в примерах, указанных выше, замените вызов общего сниппета на ваш собственный:
```JavaScript
snippet('Business.Mindbox.Operations');
```
В обоих случаях, перед вызовом сниппета требуется объявить все необходимые переменные и передать им соответствующие значения.
При успешном запросе во вкладке "Клиенты" в Mindbox будет создан клиент с переданными из чат-бота данными о нем:
[](https://docs.metabot24.ru/uploads/images/gallery/2022-11/qtyPh5FE7Vf8raIw-image.png)
Так же, во вкладке "Действия" вы сможете найти историю выполненной операции:
[](https://docs.metabot24.ru/uploads/images/gallery/2022-11/mZvbMZeFukIquXcl-image.png)
#### Обработка ошибок
В случае успешного выполнения оба метода возвращают **true**. В случае ошибки оба метода возвращают **false**, а в атрибутах лида и бота вы сможете найти информацию о последней ошибке. Название атрибуты и описание указано в таблице ниже.
| Хранилище | Название атрибута | Описание |
| lead | plugin.mindbox.lastError.code
| В случае ошибки, будет содержать код ошибки плагина. Смотрите таблицу ошибок ниже.
|
| bot |
| lead | plugin.mindbox.lastError.message
| В случае ошибки, будет содержать сообщение об ошибке плагина. Смотрите таблицу ошибок ниже.
|
| bot |
##### Список ошибок
В случае ошибки плагин может вернуть одну из следующих ошибок, а также вернет сообщение об ошибке. В таблице ниже представлены все возможные ошибки плагина и рекомендации, что вы можете сделать в каждом конкретном случае.
| Код ошибки | Сообщение об ошибке | Рекомендации |
| 1 | Ошибка вызова Mindbox API ({код ошибки}).
| Плагин вернет код ошибки Mindbox API. Поскольку чат-бот не запоминает детали вызова API потому что вызовы асинхронны (async), при получении данной ошибки детали смотрите на стороне Mindbox.
Все возможные коды ошибок Mindbox API cмотрите в документации к Mindbox: [https://developers.mindbox.ru/docs/error\_processing](https://developers.mindbox.ru/docs/error_processing)
Подробнее про вызов операции через Mindbox API, который применяется в этом плагине, смотрите по ссылке: [https://developers.mindbox.ru/docs/v3](https://developers.mindbox.ru/docs/v3)
|
| 2 | Не задан ключ интеграции {имя атрибута} в атрибутах бота.
| Проверьте не ошиблись ли вы в регистре символов или названии.
|
| 3 | Не заданы обязательные параметры параметризованного метода.
| Проверьте не пытаетесь ли вы передать пустые данные в Mindbox в одном из полей (смотрите поля в атрибутах лида). А если параметр допустимо передавать пустым, удалите соответствующую валидацию в коде в callMindboxEndpointAlt().
|
### Исходный код плагина
Cкопируйте указанный ниже код в скрипт Operations вашего плагина Mindbox и измените как вам требуется.
```JavaScript
/**
* Универсальная функция для регистрации операции в Mindbox через точку интеграции.
* Используется явное указание тела запроса в формате JSON.
* @param {string} endpointID - Идентификатор точки интеграции в Mindbox
* @param {string} operation - Системное имя операции
* @param {object} jsonBody - Тело запроса (берется из настроек операции в Mindbox)
* @returns {bool} - Результат выполнения функции: успешно (true), проблемы (false).
*/
function callMindboxEndpoint(endpointId, operation, jsonBody) {
// Считываем ключ авторизации из аттрибуты бота
let secretKey = bot.getAttr('mindbox.secretKey.'+ endpointId)
// Если ключ не настроен
if (!secretKey) {
outputError(endpointId, operation, '2', 'Не задан ключ интеграции plugin.Mindbox.secretKey в атрибутах чат-бота.')
return false
}
// Задаем заголовок запроса
api.setHeaders({'authorization':'Mindbox secretKey="' + secretKey + '"'})
// Задаем URL запроса (используем асинхронный 'async' метод)
let url = "https://api.mindbox.ru/v3/operations/async?endpointId=" + endpointId + "&operation=" + operation
// Выполняем запрос с помощью метода POST и запоминаем результат
let jsonResponse = api.postJson(url, jsonBody)
let jsonResponseCode = api.getLastResponseCode()
// Возникла ошибка
if (jsonResponseCode != 200) {
outputError(endpointId, operation, '1', 'Проблема вызова Mindbox API. Детали смотрите в Mindbox.')
return false // Выполнено с проблемами
}
return true // Все ок
}
/**
* Альтернативная (параметризованная) функция для регистрации операции в Mindbox, который подготавливает тело запроса.
* Адаптируйте эту функцию под свой проект или создайте копию.
* @param {string} endpointID - Идентификатор точки интеграции в Mindbox
* @param {string} operation - Системное имя операции
* @param {string} email - Email
* @param {string} phone - Мобильный телефон
* @param {string} lastName - Фамилия
* @param {string} firstName - Имя
* @param {string} subscriptionTopic - Внешний идентификатор тематики подписки
* @param {string} pointOfContact - Внешний идентификатор точки контакта
* @returns {bool} - Результат выполнения функции: успешно (true), проблемы (false).
*/
function callMindboxEndpointAlt(endpointId, operation, email, phone, lastName, firstName, subscriptionTopic, pointOfContact) {
// Если передали пустые значения
if (isStrEmpty(endpointId) ||
isStrEmpty(operation) ||
isStrEmpty(email) ||
isStrEmpty(phone) ||
isStrEmpty(lastName) ||
isStrEmpty(firstName) ||
isStrEmpty(subscriptionTopic) ||
isStrEmpty(pointOfContact))
{
outputError('3', 'Не заданы обязательные параметры параметризованного метода.')
return false
}
// Формируем тело запроса в JSON (в вашем проекте запрос может отличаться)
let jsonBody = {
"customer": {
"email": email,
"mobilePhone": phone,
"lastName": lastName,
"firstName": firstName,
"customFields": {
"AdCommunicationAgreement": true, // Согласие на рассылку
"PersonalDataAgreement": true // Согласие на обработку персональных данных
},
"subscriptions": [
{
"brand": "<Системное имя бренда подписки клиента>",
"pointOfContact": "<Системное имя канала подписки: Email, SMS, Viber, Webpush, Mobilepush>",
"topic": subscriptionTopic
}
]
},
"pointOfContact": pointOfContact
}
// Вызываем универсальную функцию и возвращем результат
return callMindboxEndpoint(endpointId, operation, jsonBody)
}
/**
* Вспомогательная функция, которая сохраняет сведения об ошибке в атрибутах лида и атрибутах бота.
* @param {string} endpointId - Точка интеграции
* @param {string} operation - Операция
* @param {string} code - Код ошибки
* @param {string} message - Сообщение об ошибке
*/
function outputError(endpointId, operation, code, message) {
// Добавляем в конце сообщения доп. инфу.
message = message + ' (точка=' + endpointId + ', операция=' + operation + ')'
lead.setAttr("plugin.Mindbox.lastError.Code", code)
lead.setAttr("plugin.Mindbox.lastError.Message", message)
bot.setAttr("plugin.Mindbox.lastError.Code", code)
bot.setAttr("plugin.Mindbox.lastError.Message", message)
}
/**
* Вспомогательная функцию, которая проверяет является ли строка пустой.
* @param {string} code - Код ошибки
* @returns {bool} - если строка пустая (true), иначе (false).
*/
function isStrEmpty(str) {
return (typeof str === 'string' && str.trim().length === 0) ? true : false
}
```
# Диалоговое путешествие (Dialog Journey)
| **Название плагина** | Диалоговое путешествие (Dialog Journey) |
| **Разработчик** | Официальные плагины от Metabot |
| **Авторы** | Гарашко Артем Юрьевич ([artem@metabot.org](mailto:artem@metabot.rg))
|
| **Дата создания** | 04 Января 2023 |
| **Последняя дата обновления** | 06 Января 2023 |
### Описание
Платформа Metabot — это платформа автоматизации коммуникаций. Плагин **Dialog Journey (DJ)** для платформы Metabot позволяет интегрировать в ваш чат-бот, разработанный на Metabot или на любой другой бот-платформе, поддерживающей вызовы и приемы API веб-хуков, возможность проектирования, отслеживания и визуализации клиентских путешествий, также называемых клиентскими путями (customer journeys).
Используя плагин и платформу Metabot, вы можете создавать диалоговые стратегии и путешествия клиентов, которые помогут вашим клиентам получать пользу, а вашей компании достигать поставленных целей, собирать аналитику о ходе продвижения клиентов по диалогам в чат-боте, отслеживать и визуализировать карты их путей.
Плагин позволит организовать развитие вашего чат-бота таким образом, чтобы все разрозненные диалоги объединялись в единую **коммуникационную стратегию** компании, представленную в виде путешествий (journeys), разбитых на фазы (phases) с целями (goals), предоставляемой пользой (values) и измеряемыми показателями (metrics). Более подробное описание концепции и устройства плагина, а также предлагаемой методологии маркетинговой стратегии смотрите ниже.
### Пример
Пример работы чат-бота с интегрированным плагином можете посмотреть перейдя по ссылке.
### Настройка
Для интеграции плагина DJ с вашим чат-ботом вам необходимо сделать следующее:
1. Создать кастомные таблицы и заполнить их, согласно схеме базы данных, опубликованной в разделе **Справочники**.
2. Спроектировать путешествия для ваших клиентских сегментов и настроить справочники, описания назначения которых смотрите ниже.
1. Классы персон.
2. Подклассы персоны.
3. Путешествия.
4. Фазы путешествия.
5. Польза.
6. Цели.
7. Показатели.
8. Активности.
3. Скачать готовый шаблон чат-бота, в который уже интегрирован плагин DJ, адаптировать его код и структуру под ваши задачи в своем чат-боте.
1. Ссылка.
4. Ознакомиться с примерами когда вызова методов DJ из вашего чат-бота в разделе **JS команды**.
5. Ознакомиться с инструкций как пользоваться аналитикой и отчетами в разделе **Аналитика и отчеты**.
Если разработка чат-бота ведется на сторонней платформе, в дополнение к шагам, описанным выше, вам также необходимо настроить точки интеграции от вашего чат-бота, созданного на сторонней платформе, к чат-боту, созданному на Metabot, работающему как внешнее хранилище данных для следующих целей:
1. Чтобы ваш чат-бот мог передавать в базу данных Мetabot все нужные вам события для аналитики, например, сообщать, что пользователь достиг цели или перешел к следующей фазе путешествия.
2. Чтобы ваш чат-бот мог запрашивать в базе данных Metabot информацию о состоянии путешествия пользователя, например, проверять достиг ли пользователь цели, были ли предоставлена польза, узнавать фазу путешествия на которой находится пользователь и так далее.
Инструкцию о том, как подключить Dialog Journeys к чат-боту (а может и не только к чат-боту), создаваемому на сторонней платформе, смотрите в разделе **Интеграция со сторонними системами**.
### Методология
#### Предисловие
Представленное решение — это уникальный синтез нашего собственного практического опыта и изысканий с идеями ведущих мировых теоретиков из сферы маркетинга, управления бизнесом и инноваций.
Возможно модель подойдет к вашей бизнес-практике идеально «как есть». Мы постарались сделать модель простой и в то же время достаточно гибкой — принципы, лежащие в ее основе, универсальны и действенны.
Возможно вы не согласитесь с представленной моделью работы с клиентами и решите сделать по-другому, либо захотите расширить или откорректировать модель. Вы вправе это сделать. Если вам потребуется разработка уникального плагина под ваше видение, обращайтесь в наш отдел разработки и мы сделаем решение «под ключ».
Методология маркетинга, на которой строится работа данного плагина, стоит на нескольких китах. Во-первых, это решение для современного маркетинга для «экономики связей» или «экономики подключения» (Connection Economy). Подробнее об этой концепции смотрите здесь.
Во-вторых, это решение строится на **маркетинге доверия**. Подробнее об этой концепции смотрите соответствующие обучающие материалы и экспертов. Например, здесь.
#### Справочники
##### Классы персон
Проектирование начинается с описания клиентских сегментов — мы их называем **Классы персон**. Подобно, RPG играм, опишите все классы, с которыми имеет дело ваш бизнес.
- Пример из сказочный: воин, лучник, волшебник;
- Пример из жизни: строитель, заказчик, партнер.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/Sh9KjRxQgzzGdChX-image.png)
##### Подклассы персон
Создайте **Подклассы персон**, если вам нужно разбить клиентов на более узкие сегменты и строить с ними более персонализированные отношения.
- Пример для класса лучника: стрелок, снайпер, охотник;
- Пример для класса строителя: индивидуальный строитель, профессиональная бригада, крупный застройщик.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/WmZdMtuyN11JGWvS-image.png)
##### Путешествия
Создайте все необходимые **Путешествия**, как общие для всех классов и подклассов, так и индивидуальные для каждого сегмента.
Если вы впервые сталкивайтесь с разработкой чат-ботов, мы рекомендуем не усложнять и начать автоматизацию с одного наиболее популярного и критичного путешествия, например, с вовлечения и онбординга нового пользователя.
В любое случае, рекомендуем обдумать все путешествия заранее, хотя бы верхнеуровнево, которые "проживают" или будут "проживать" ваши клиенты, взаимодействия с вашей компанией.
Примеры путешествий:
- Онбординг нового партнера;
- Путь к первой покупке;
- Путь к повторной покупке;
- Обучаем стрелять из лука.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/ROd2jqKsKenx4LLQ-image.png)
Плагин работает так, что запоминает один единственный раз, когда пользователь пустился в путешествие. Плагин на текущий момент не поддерживает повторные путешествия по одному и тому же путешествию. Если вам необходимо заново отправить пользователя в повторное путешествие, для этого создайте новое путешествие или очистите старые данные по путешествию в базе данных.
##### Цели
Следующим шагом, который на самом деле надо делать одновременно с предыдущим, мы рекомендуем заполнить **Цели** для путешествий. Мы же с вами занимаемся бизнесом и не хотим создавать бесцельные путешествия, верно?
Пример целей для онбординга партнеров:
- Регистрация в партнерской программе;
- Сертификация партнера.
Пример целей для обучения стрельбе из луков:
- Обучить лучника;
- Продать лук и стрелы;
- Продать билеты на соревнование по стрельбе.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/uUd9oJr3ecQ3Rcty-image.png)
Плагин работает так, что позволяет записать достижения цели по каждому путешествию для каждого пользователя только один единственный раз. Если в чат-боте пользователь несколько раз пройдет по сценарию, то повторные достижения одной и той же цели будут проигнорированы.
##### Фазы путешествия
Разбейте каждое путешествие на **Фазы**. Мы сознательно используем слово «фазы», а не «этапы» или «шаги», потому что оно нам больше нравится — ведь переход от фазы к фазе т.е. так называемый «фазовый переход» подразумевает некую качественно новую форму, например, лед при нагревании превращается в воду, а при еще большем нагревании в пар. Мы же с вами хотим строить диалоги с нашей аудиторией так, чтобы каждый раз выходить на новый уровень взаимоотношений, верно?
Пример фаз для онбординга нового партнера:
- Вовлечение;
- Знакомство;
- Сертификация;
- Первая транзакция.
Пример фаз для учебы стрельбе из лука:
- Изучает основы по стрельбе и безопасности;
- Учится делать DIY лук и стрелы;
- Учится стрелять;
- Сдать экзамен по стрельбе;
- Записать на соревнование по стрельбе.
Согласитесь, что каждая из фаз, приведенных в примерах выше, символизирует качественно новое состояние, дойдя до которого, наш пользователь, уже не сможет вернуться назад и забыть все то, что было до этого?
Наша цель при проектировании и разработке чат-ботов и авто-воронок заключается в том, чтобы выстраивать диалоговые коммуникации таким образом, чтобы они помогали пользователю двигаться от фазы к фазе, получая пользу, и тем самым доходить до завершения путешествия и помогая нам достигать бизнес-цели. Как именно строить такие коммуникации мы разберем ниже.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/PthMoEOsvxnffnIV-image.png)
Плагин работает так, что запоминает один единственный раз, когда пользователь завершал одну фазу путешествия и начинал новую. Плагин запоминает дату и время фазовых переходов, чтобы по ним строить аналитику. Если пользователь пришел в сценарий в чат-боте, в котором в DJ сообщается о смене фазы, то плагин проигнорирует повторные команды.
##### Польза
Теперь самое интересное. Мы расписали наши путешествия, фазы и цели. Теперь давайте подумаем о том, как же мы будем влиять на наших пользователей, чтобы они достигали нужных нам целей?
Спланируйте **Пользу**, которую будете предоставлять вашей аудитории, на каждой фазе путешествия, чтобы выстраивать доверительные отношения и двигаться вместе с ней к целям.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/Js3bL8UtCGl2GxTO-image.png)
Мы предлагаем воспользоваться следующими принципами современной научной теории маркетинга, который на самом деле, если хорошо подумать, представляют из себя обычный здравый смысл из сферы человеческих отношений и житейскую мудрость, а именно:
- **Эмпатия**
- Давайте мы будем пытаться понять кто перед нами, а не бомбардировать людей не актуальной для них информацией;
- Давайте понимать на каком этапе принятий решения о покупке (buyer's journey) находится человек, чтобы давать именно то, что нужно сейчас;
- Давайте стараться учитывать чувства и эмоции людей, чтобы отвечать корректно контексту ситуации;
- Здорово, что чат-боты помогают все это реализовать, ведь чат-бот это диалог, в котором можно задавать вопросы и запоминать ответы, а благодаря технологии распознавания естественного языка (NLP) можно понять намерение пользователя по свободному вводу и даже распознать эмоции;
- Пример для строительной сферы: в самом начале коммуникации с целевой аудиторией, задайте 2-3 квалифицирующих вопроса, которые помогут определить к какому сегменту (классу и подклассу) относится человек. Также, вы можете узнать квалификацию строителя (профессионал или новичок), чтобы в последствии вести каждый сегмент по своему уникальному пути.
- Пример для сказочной истории: аналогично, cоздайте квалификационную анкету, в которой будет несколько вопросов, которые помогут вообще понять кто перед нами. Вы не не захотите "впаривать" стрельбу из лука волшебнику 100500 уровня, который обидится и превратит вас в лягушку? =)
- **Персонализация**
- Раз мы можем говорить с пользователем и задавать интересующие нам вопросы, так давайте использовать полученную информацию для построения персонализированных диалогов. А если интегрировать чат-бот с корпоративными информационными системами, например, с E-Commerce веб-сайтом, где хранится история покупок пользователя, то можно строить еще более полезные персонализированные диалоги и предложения.
- Пример: как минимум, можно иногда обращаться по имени. Конечно, это не заставит пользователя прийти в восторг и сделать покупку, на, как минимум, повлияет на общее восприятие вашего бренда и позволит заработать очки доверия. Ведь мы же строим долгосрочные отношения на доверии, а значит должны всегда заботиться о целостности и последовательности наших коммуникаций.
- Пример из строительной отрасли: узнав сегмент, опыт строителя и регион, вы можете сделать персональное предложение, например, предложить партнерам присылать заявки на строительный заказы из этого региона, предложить горячие скидки на продукцию любимого бренда, пройти обучение для новичков и так далее.
- Пример для сказочной истории: узнав, что перед нами маг, мы можем предложить ему магазин для магов от наших партнеров или просто выпить чашечку кофе.
- **Такт и ритм**
- Мы настоятельно рекомендуем пользоваться житейским здравым смыслом и бизнес этикой при программировании автоматических коммуникаций.
- Также как и в реальных отношениях в нашей жизни, давайте cоблюдать чувство такта и ритма в цифровых отношениях, которые автоматизируем. Людям не понравится, если мы пишем им, как назойливая муха, с поводом или без повода. Также, люди могут про нас начитать забывать и контакт потом восстановить будет сложнее, если мы совсем перестанем общаться. Если же мы будем присылать информацию, которая не релеванта, не принимая обратную связь и не корректируя коммуникацию, то люди могут отправить нас "в баню". И так далее.
- Пример из строительной отрасли: когда мы узнаем темп обучения, который удобен коллеге-строителю для повышения своей квалификации, мы можем начать присылать ему обучающие материалы прямо в чат-бот так часто как будет удобно: раз в день, неделю, месяц.
- Пример из сказочной отрасли: узнав, что перед нами опытный следопыт, который отправляется в охотничьи вылазки раз в месяц, мы можем отправлять ему информацию о новинках прямо на кануне очередного похода, о котором можем узнать, спросив об этом.
- **Доверие**
- Доверие клиента или партнера — это самое главное конкурентное преимущество и один из самых главных активов. Никто не свяжет свою жизнь с человеком, в котором не уверен. То же самое происходит в бизнесе. Теряя доверие к бренду или компании, вы уходите к другим, верно? Ваши клиенты делают так же.
- Завоевание доверия это сложный и длительный процесс, требующим особого подхода. Большое доверие увеличивает продажи и доходы компании, а потеря доверия увеличивает расходы на рекламу и маркетинг. Доверие зарабатывается по крупицам, а потерять его можно в один момент.
- Конечно, доверие к бренду или компании складывается из многих факторов, на которые мы не можем влиять чат-ботом, например, из качества продукции. Если продукция плохая, чат-бот вряд ли сильно поможет в выстраивании доверия, какие бы красиво он не говорил.
- Однако, если в компании порядок с продукций и сервисом, то создание захватывающего, полезного и удобного клиентского опыта (CX) в виде бесшовного диалога в чат-боте, интегрированного в бизнес-процессы и информационные системы предприятия, может стать тем самым ключом к конкурентному преимуществу, который изменит баланс весов в пользу вашей компании.
- Пример доверия: хорошо понимать своих клиентов, проектировать правильные путешествия, которые дают пользу, помнить о долгосрочности диалогов и отношений, выстроить полезный сервис в чат-боте, которым хочется пользоваться и рассказать другим.
- Пример потери доверия: игнорировать запросы клиентов, не решать пожарные ситуации, долго строить отношения по стратегии, а потом начать рассылать спам и прочее.
- **Щедрость**
- Тоже не менее важный принцип, как и доверие. В эпоху перепроизводства и высокой конкурентности (когда в каждой категории на полке десятки и сотни продуктов), щедрость это то, что позволяет выстраивать доверительные отношения.
- Как и в жизни, так и в бизнесе, никто не захочет дружить с теми кто только «берет» и не готов «отдавать».
- Что означает щедрость в применении к чат-ботам: полезный контент, которым вы можете делиться; полезные вебинары; выставки; сервисы и так далее.
Аналогично целям, предоставление пользы фиксируется один единственный раз и повторные выдачи той же самой пользы не фиксируются в базе данных, поэтому вы можете не опасаться за то, что пользователь несколько раз обратился за одним и тем же контентом — это не собьет статистику. Предоставление пользы будет отслежено только самый первый раз.
##### Показатели
Спланируйте **Показатели** (или метрики), которые вам необходимо измерять.
Пример из жизни:
- Вы можете завести метрику, которая отображает % потребления контента, чтобы оценивать степень "созревания" пользователя;
- Индекс NPS (удовлетворенность компанией);
- Настроение, например, вы можете периодически опрашивать как у ваших пользователей дела ;
- Степень осведомленности о продукции компании (от 0 до 100).
Сказочный пример:
- Количество купленных стрел;
- Количество сломанных луков.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/xS7cTgNxYIH7N3xH-image.png)
Показатели, в отличие от Целей и Пользы, можно измерять сколько угодно раз и в любое время. То есть, если с течением времени показатель меняется, у вас будет вся история изменений.
В текущей версии плагина показатели закрепляются за путешествием и фазой во время которых они были собраны. В будущих релизах планируется сделать поддержку сбора общих показателей, не относящихся к конкретному путешествию или фазе.
##### Активности
**Активности** — это события, которые происходят в ходе путешествия или действия, которые совершает пользователя, во время путешествия.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/aaeDllQs2ESRs41o-image.png)
Существует 7 основных событий, которые позволяют управлять ходом путешествия и отслеживать его хронологию:
| ID | Код | Название | Пояснение |
| 1 | journeyStarted | Путешествие начато | Используется в самом начале путешествия, когда стало понятно, что пользователь "отправился в путешествие". |
| 2 | phaseStarted | Фаза начата | Используется при запуске следующей фазы, а также автоматически в начале путешествия. |
| 3 | phaseCompleted | Фаза завершена | Используется при запуске следующей фазы, завершая предыдущую, и при завершении всего путешествия. |
| 4 | phaseInterrupted | Фаза прервана | Используется при прерывании фазы, которое происходит либо при прерывании всего путешествия, либо когда по каким-то причинам в нам нужно будет прервать фазу. |
| 5 | phaseSkipped | Фаза пропущена | Используется по каким-то причинам когда вам необходимо пропустить целую фазу. |
| 6 | journeyCancelled | Путешествие отменено | Используется когда путешествие было отменено, например, пользователь передумал. |
| 7 | journeyCompleted | Путешествие завершено | Путешествие успешно завершено, пользователь дошел до победного конца. |
В одном из будущих релизов планируется возможность добавлять пользовательские активности, чтобы вы могли отслеживать промежуточные шаги во время фазы, если вам это понадобится.
### Журналы
Все что происходит в чат-боте сохраняется в несколько **Журналов**, а также сохраняется в **Состоянии пользователей в путешествии**. Это системные таблицы, в которых накапливаются исторические данные, которые вам не нужно трогать. На основе журналов и справочников, формируются аналитические отчеты и визуализации.
Ни в коем случае не нарушайте целостность данных, если уже запустили трафик и идет сбор данных о путешествиях пользователей. Если у вас есть журналы с данными, а вы решите удалить или изменить данные в **Справочниках**, отдавайте себе отчет, что это может повлиять на исторические данные, ранее собранные чат-ботом, а значит и на отчеты.
#### Журнал путешествий
В этом журнале хранится история фаз и активностей, а также начала и завершения путешествий.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/8KnvxY4wbhriKAQa-image.png)
#### Журнал пользы
В этом журнале хранится история предоставления пользы пользователям.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/llT4NajiENhoFm9i-image.png)
#### Журнал целей
В этом журнале хранится история достижения целей.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/4hTDFc35TETwFvRD-image.png)
#### Журнал показателей
В этом журнале хранятся собранные метрики.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/WGX6xcTZiEFYYItg-image.png)
#### Состояние пользователя в путешествии
В этой таблице хранится состояние пользователя в конкретном путешествии.
[](https://docs.metabot24.ru/uploads/images/gallery/2023-01/gphCiREYGeN217lY-image.png)
Ни в коем случае не трогайте эти данные на продакшене, кроме случаев отладки, иначе нарушите ход путешествия для пользователей.
### JS команды
Для отправления информации в плагин и фиксации данных в базе необходимо в нужном вам месте в чат-боте подключить плагин, инициализировать менеджер путешествий и выполнить нужную команды.
Список команд и примеры кода представлены в таблице ниже.
| № | Название метода | Пример кода |
| 1 | Начать путешествие
| ```JavaScript
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Начинаем новое
let isNewJourneyStarted = jm.startNewJourney("myJourney")
// Пишем результат в память
memory.setAttr("isNewJourneyStarted", isNewJourneyStarted)
```
При инициализации JourneyManager для лида будет создана персона, если она еще не была создана! В текущей версии плагин позволяет отслеживать пути персон и не возможно отслеживание путей лидов. Поэтому персона создается для каждого лида на самой ранней стадии пути, чтобы иметь возможность отслеживать путь как можно раньше - даже когда лид/персона еще не взаимодействовали с бизнесом.
В качестве роли персоны будет использована роль по умолчанию, которую необходимо задать в настройках чат-бота.
|
| 2 | Завершить путешествие
| ```JavaScript
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Выбираем путешествие
jm.selectJourney("myJourney")
// Завершаем выбранно путешествие
let isJourneyCompleted = jm.completeJourney()
// Пишем результат в память
memory.setAttr("isJourneyCompleted", isJourneyCompleted)
```
|
| 3 | Следующая фаза | ```JavaScript
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Выбираем путешествие
jm.selectJourney("myJourney")
// Запоминаем название текущей фазы
let oldPhaseName = jm.getCurrentPhase().name
// Стартуем новыую фазу путешествия
let isPhaseStarted = jm.startNextPhase("nextPhaseCode")
// Запоминаем название новой фазы (если она установилась, конечно)
let newPhaseName = jm.getCurrentPhase().name
// Пишем результат в память
memory.setAttr("isPhaseStarted", isPhaseStarted)
memory.setAttr("oldPhaseName", oldPhaseName)
memory.setAttr("newPhaseName", newPhaseName)
```
|
| 4 | Предоставить пользу | ```JavaScript
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Выбираем путешествие
jm.selectJourney("myJourney")
// Сообщаем менеджеру путешествия, что мы предоставили пользу
let isValueGiven = jm.giveValue("valueCode")
// Загружаем информацию о метрике из справочника
let valueInfo = jm.getValueInfo("valueCode")
// Загружаем информацию о собранной метрике
let value = jm.getValue("valueCode")
// Выводим результат работы
memory.setAttr("isValueGiven", isValueGiven)
memory.setAttr("valueName", valueInfo.name)
memory.setAttr("valueWeight", value.weight)
```
|
| 5 | Достигнуть цель | ```Java
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Выбираем путешествие
jm.selectJourney("myJourney")
// Сообщаем менеджеру путешествия, что мы достигли цели
let isGoalAchieved = jm.achieveGoal("goalCode")
// Загружаем информацию о цели
let goal = jm.getGoalInfo(goalCode)
// Выводим результат работы
memory.setAttr("isGoalAchieved", isGoalAchieved)
memory.setAttr("goalName", goal.name)
```
|
| 6 | Записать показатель | ```JavaScript
// Подключаем плагин
snippet("Common.DialogJourney.Manager")
// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)
// Выбираем путешествие
jm.selectJourney("myJourney")
// Считываем значение метрики
let metricValue = lead.getAttr("metricValue")
// Сохраняем метрику
let isMetricSaved = jm.saveJourneyMetric("metricCode", metricValue)
// Загружаем информацию о метрике из справочника
let metricInfo = jm.getMetricInfo("metricCode")
// Загружаем информацию о собранной метрике
let metric = jm.getLatestJourneyMetric("metricCode")
// Выводим результат работы
memory.setAttr("isMetricSaved", isMetricSaved)
memory.setAttr("metricName", metricInfo.name)
memory.setAttr("metricValue", metric.value)
```
|
Другие примеры кода с использованием плагина смотрите в шаблоне чат-бота, доступного для скачивания здесь.
### Интеграция со сторонними системами
Вы можете использовать DJ плагин для сбора данных о путешествии пользователей не только в чат-боте, созданном на платформе Metabot. Вы можете вести разработку на других бот-платформах и использовать Metabot для сбора и визуализации аналитики.
Также, вы можете отправлять в Metabot информацию о событиях из других систем, чтобы фиксировать прохождение пользователя по пути, когда пользователь совершает нужное целевое действие на сайте (например, размещает товар в корзину, но не оплачивает).
Для интеграции сторонних систем с вашим Dialog Journey в чат-боте на Metabot, необходимо настроить точки интеграции для всех необходимых событий, которые вам нужно регистрировать в Metabot. Информацию о точках интеграции смотрите в разделе [Точки интеграции и конструктор API](https://docs.metabot24.ru/books/metabot-platform/page/tocki-integracii-i-konstruktor-api "Точки интеграции и конструктор API"). В коде точки интеграции разработайте код согласно примерам выше.
# Business.Helpers.Response
Плагин Business.Helpers.Response служит утилитой для стандартизации ответов API в бизнес-приложениях. Его основная цель - упростить создание последовательных и структурированных ответов для различных сценариев, возникающих во время взаимодействия с API.
```JavaScript
/**
* Prepares and returns an API response object for a failed operation.
* This should be used when an operation does not complete successfully,
* with the provided error message included in the response.
*
* @param {string} errorMessage - The error message to be included in the response.
* @returns {Object} An object representing a failed operation response.
*/
function getErrorResponse(errorMessage) {
return {
success: false,
message: errorMessage
};
}
/**
* Prepares and returns an API response object for a successful operation.
* This should be used when an operation completes successfully
* and no additional data needs to be returned.
*
* @returns {Object} An object representing a successful operation response.
*/
function getSuccessResponse() {
return {
success: true
};
}
/**
* Prepares and returns an API response object for a successful operation
* with additional JSON data. This should be used when an operation completes
* successfully and there is additional data to return in the response.
*
* @param {Object} json - The JSON data to be included in the response.
* @returns {Object} An object representing a successful operation response with additional data.
*/
function getSuccessResponseWithJson(json) {
return {
...json,
success: true
}
}
```
# Интеграция с Google Sheets
Первым делом необходимо создать новую таблицу в Google Sheets и добавить нового редактора .
[](https://docs.metabot24.ru/uploads/images/gallery/2024-02/o7zUHZfmlqXpHIuj-image.png)
Далее копируем ID таблицы из адресной строки.
[](https://docs.metabot24.ru/uploads/images/gallery/2024-02/w1LvONxKtdNhOBuC-image.png)
Копируем название листа.
[](https://docs.metabot24.ru/uploads/images/gallery/2024-02/XH2zcN4vXSH6TU4E-image.png)
Копируем название столбцов в таблице.
[](https://docs.metabot24.ru/uploads/images/gallery/2024-02/kQKAKqYgTt3NZqSc-image.png)
### Метод для добавления нового столбца
Записываем в нужное место скрипта следующий код:
```JavaScript
var GoogleSheetsService = require('Common.Integrations.GoogleSheets') // Плагин для работы с Google Sheets
GoogleSheetsService.sheetId = '11muAnepqhpRQ9ElE9CzC3E-edmf9JbRE3gwmBTDa5pE' // ID скопированный из таблицы
GoogleSheetsService.listName = 'list' // Название листа
// Параметры где ключ - название столбца, значение - данные которые занесутся в строку
let params = {
"region": "Москвская область",
"name": 'Тест',
"age": "24",
"city": "Москва",
}
let result = GoogleSheetsService.addRow(params) // Функция для добавления строк в таблицу
debug(result) // Вернётся результат выполенния с Id в строки в которую записались данные
```
Пример ответа:
```JavaScript
{
"status": "success",
"message": "Row added successfully", // Сообщение, если есть ошибка - вернётся описание ошибки
"rowId": 8 // Id в строки в которую записались данные
}
```
### Метод для поиска и замены значения в ячейке
Записываем в нужное место скрипта следующий код:
```JavaScript
var GoogleSheetsService = require('Common.Integrations.GoogleSheets') // Плагин для работы с Google Sheets
GoogleSheetsService.sheetId = '11muAnepqhpRQ9ElE9CzC3E-edmf9JbRE3gwmBTDa5pE' // ID скопированный из таблицы
GoogleSheetsService.listName = 'list' // Название листа
// Параметры со настройками для замены
let params = {
colomn_search_name: 'region',
colomn_edit_name: 'region',
search_value: '123123',
match_entire_cell: true,
new_value: "Антон"
}
let result = GoogleSheetsService.searchAndEditRow(params) // Функция для поиска и замены строк
debug(result) // Вернётся результат выполенния или код ошибки
```
Пример ответа:
```JavaScript
{
"status": "success",
"message": 'Значение найдёно и измененно'
}
```