Библиотека плагинов

• Плагин для Mindbox
• Диалоговое путешествие (Dialog Journey)
• Business.Helpers.Response
• Интеграция с Google Sheets
• Документация Telegram-плагина

Плагин для Mindbox

Описание

Mindbox — это платформа автоматизации маркетинга и клиентских данных. Этот плагин к платформе Metabot позволяет интегрировать ваш чат-бот, разрабатываемый на Metabot, с платформой Mindbox. Подробнее с Mindbox можно ознакомиться на их официальном сайте: https://mindbox.ru.

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

Подключение

Для интеграции Mindbox с вашим чат-ботом вам необходимо сделать несколько вещей:

1. На стороне Mindbox настройте все нужные точки интеграции и операции. Подробнее смотрите в документации Mindbox.
2. Зарегистрируйтесь на платформе Metabot, подтвердите почту, авторизуйтесь и создайте чат-бот.
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. Кастомизируйте код интеграции под свои задачи. Если у вас возникнут затруднения, обратитесь за помощью в Телеграм-чат cообщества или поддержку Metabot.  

Вызов в диалоге

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

Способ 1. Универсальная (JSON) функция

Первый способ использования плагина в диалоге — с помощью универсальной функции callMindboxEndpoint(). Вы сами формируете тело запроса в формате JSON и передаете его в функцию.

Пример использования универсального (JSON) метода:

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)

Функция требует передачи трех переменных в строгом порядке:

Способ 2. Альтернативная (параметризованная) функция

Второй способ использования плагина — с помощью альтернативной функции callMindboxEndpointAlt(), в которую вы передаете параметры запроса, а функция внутри себя формирует тело запроса в формате JSON и затем вызывает описанную выше универсальную функцию. 

Пример использования альтернативного (параметризованного) метода:

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.

Варианты подключения плагина

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

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

snippet('Common.Mindbox.Operations');

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

1. Cоздайте плагин в вашем бизнесе и назовите его Mindbox.
2. Создайте в плагине скрипт и назовите его Operations.
3. Скопируйте код, размещенный ниже, в код нового скрипта.

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

snippet('Business.Mindbox.Operations');  

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

При успешном запросе во вкладке "Клиенты" в Mindbox будет создан клиент с переданными из чат-бота данными о нем: 

Так же, во вкладке "Действия" вы сможете найти историю выполненной операции:

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

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

Список ошибок

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

Исходный код плагина

Cкопируйте указанный ниже код в скрипт Operations вашего плагина Mindbox и измените как вам требуется.

/**
 * Универсальная функция для регистрации операции в 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)

Описание

Плагин позволит организовать развитие вашего чат-бота таким образом, чтобы все разрозненные диалоги объединялись в единую коммуникационную стратегию компании, представленную в виде путешествий (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 играм, опишите все классы, с которыми имеет дело ваш бизнес.

• Пример из сказочный: воин, лучник, волшебник;
• Пример из жизни: строитель, заказчик, партнер.

Подклассы персон

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

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

Путешествия

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

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

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

Примеры путешествий:

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

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

Цели 

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

Пример целей для онбординга партнеров:

• Регистрация в партнерской программе;
• Сертификация партнера.

Пример целей для обучения стрельбе из луков:

• Обучить лучника;
• Продать лук и стрелы;
• Продать билеты на соревнование по стрельбе.
  

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

Фазы путешествия

Разбейте каждое путешествие на Фазы. Мы сознательно используем слово «фазы», а не «этапы» или «шаги», потому что оно нам больше нравится — ведь переход от фазы к фазе т.е. так называемый «фазовый переход» подразумевает некую качественно новую форму, например, лед при нагревании превращается в воду, а при еще большем нагревании в пар. Мы же с вами хотим строить диалоги с нашей аудиторией так, чтобы каждый раз выходить на новый уровень взаимоотношений, верно?

Пример фаз для онбординга нового партнера:

• Вовлечение;
• Знакомство;
• Сертификация;
• Первая транзакция.

Пример фаз для учебы стрельбе из лука:

• Изучает основы по стрельбе и безопасности;
• Учится делать DIY лук и стрелы;
  
• Учится стрелять;
• Сдать экзамен по стрельбе;
• Записать на соревнование по стрельбе.
  

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

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

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

Польза 

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

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

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

• Эмпатия
  • Давайте мы будем пытаться понять кто перед нами, а не бомбардировать людей не актуальной для них информацией;
  • Давайте понимать на каком этапе принятий решения о покупке (buyer's journey) находится человек, чтобы давать именно то, что нужно сейчас;
  • Давайте стараться учитывать чувства и эмоции людей, чтобы отвечать корректно контексту ситуации;
  • Здорово, что чат-боты помогают все это реализовать, ведь чат-бот это диалог, в котором можно задавать вопросы и запоминать ответы, а благодаря технологии распознавания естественного языка (NLP) можно понять намерение пользователя по свободному вводу и даже распознать эмоции;
  • Пример для строительной сферы: в самом начале коммуникации с целевой аудиторией, задайте 2-3 квалифицирующих вопроса, которые помогут определить к какому сегменту (классу и подклассу) относится человек. Также, вы можете узнать квалификацию строителя (профессионал или новичок), чтобы в последствии вести каждый сегмент по своему уникальному пути.
  • Пример для сказочной истории: аналогично, cоздайте квалификационную анкету, в которой будет несколько вопросов, которые помогут вообще понять кто перед нами. Вы не не захотите "впаривать" стрельбу из лука волшебнику 100500 уровня, который обидится и превратит вас в лягушку? =)
• Персонализация
  • Раз мы можем говорить с пользователем и задавать интересующие нам вопросы, так давайте использовать полученную информацию для построения персонализированных диалогов. А если интегрировать чат-бот с корпоративными информационными системами, например, с E-Commerce веб-сайтом, где хранится история покупок пользователя, то можно строить еще более полезные персонализированные диалоги и предложения.
  • Пример: как минимум, можно иногда обращаться по имени. Конечно, это не заставит пользователя прийти в восторг и сделать покупку, на, как минимум, повлияет на общее восприятие вашего бренда и позволит заработать очки доверия. Ведь мы же строим долгосрочные отношения на доверии, а значит должны всегда заботиться о целостности и последовательности наших коммуникаций.
  • Пример из строительной отрасли: узнав сегмент, опыт строителя и регион, вы можете сделать персональное предложение, например, предложить партнерам присылать заявки на строительный заказы из этого региона, предложить горячие скидки на продукцию любимого бренда, пройти обучение для новичков и так далее.
  • Пример для сказочной истории: узнав, что перед нами маг, мы можем предложить ему магазин для магов от наших партнеров или просто выпить чашечку кофе.
• Такт и ритм
  • Мы настоятельно рекомендуем пользоваться житейским здравым смыслом и бизнес этикой при программировании автоматических коммуникаций.
  • Также как и в реальных отношениях в нашей жизни, давайте cоблюдать чувство такта и ритма в цифровых отношениях, которые автоматизируем. Людям не понравится, если мы пишем им, как назойливая муха, с поводом или без повода. Также, люди могут про нас начитать забывать и контакт потом восстановить будет сложнее, если мы совсем перестанем общаться. Если же мы будем присылать информацию, которая не релеванта, не принимая обратную связь и не корректируя коммуникацию, то люди могут отправить нас "в баню". И так далее. 
  • Пример из строительной отрасли: когда мы узнаем темп обучения, который удобен коллеге-строителю для повышения своей квалификации, мы можем начать присылать ему обучающие материалы прямо в чат-бот так часто как будет удобно: раз в день, неделю, месяц.
  • Пример из сказочной отрасли: узнав, что перед нами опытный следопыт, который отправляется в охотничьи вылазки раз в месяц, мы можем отправлять ему информацию о новинках прямо на кануне очередного похода, о котором можем узнать, спросив об этом.
• Доверие
  
  • Доверие клиента или партнера — это самое главное конкурентное преимущество и один из самых главных активов. Никто не свяжет свою жизнь с человеком, в котором не уверен. То же самое происходит в бизнесе. Теряя доверие к бренду или компании, вы уходите к другим, верно? Ваши клиенты делают так же.

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

  • Конечно, доверие к бренду или компании складывается из многих факторов, на которые мы не можем влиять чат-ботом, например, из качества продукции. Если продукция плохая, чат-бот вряд ли сильно поможет в выстраивании доверия, какие бы красиво он не говорил.
  • Однако, если в компании порядок с продукций и сервисом, то создание захватывающего, полезного и удобного клиентского опыта (CX) в виде бесшовного диалога в чат-боте, интегрированного в бизнес-процессы и информационные системы предприятия, может стать тем самым ключом к конкурентному преимуществу, который изменит баланс весов в пользу вашей компании.
    
  • Пример доверия: хорошо понимать своих клиентов, проектировать правильные путешествия, которые дают пользу, помнить о долгосрочности диалогов и отношений, выстроить полезный сервис в чат-боте, которым хочется пользоваться и рассказать другим. 
  • Пример потери доверия: игнорировать запросы клиентов, не решать пожарные ситуации, долго строить отношения по стратегии, а потом начать рассылать спам и прочее.
• Щедрость
  
  • Тоже не менее важный принцип, как и доверие. В эпоху перепроизводства и высокой конкурентности (когда в каждой категории на полке десятки и сотни продуктов), щедрость это то, что позволяет выстраивать доверительные отношения.
  • Как и в жизни, так и в бизнесе, никто не захочет дружить с теми кто только «берет» и не готов «отдавать».
  • Что означает щедрость в применении к чат-ботам: полезный контент, которым вы можете делиться; полезные вебинары; выставки; сервисы и так далее.

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

Показатели

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

Пример из жизни: 

• Вы можете завести метрику, которая отображает % потребления контента, чтобы оценивать степень "созревания" пользователя;
• Индекс NPS (удовлетворенность компанией);
• Настроение, например, вы можете периодически опрашивать как у ваших пользователей дела ;
• Степень осведомленности о продукции компании (от 0 до 100).

Сказочный пример:

• Количество купленных стрел;
• Количество сломанных луков.

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

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

Активности

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

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

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

Журналы

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

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

Журнал путешествий 

В этом журнале хранится история фаз и активностей, а также начала и завершения путешествий.

Журнал пользы

В этом журнале хранится история предоставления пользы пользователям.

Журнал целей

В этом журнале хранится история достижения целей.

Журнал показателей 

В этом журнале хранятся собранные метрики.

Состояние пользователя в путешествии

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

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

JS команды

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

Список команд и примеры кода представлены в таблице ниже.

// Подключаем плагин
snippet("Common.DialogJourney.Manager")

// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)

// Начинаем новое
let isNewJourneyStarted = jm.startNewJourney("myJourney")

// Пишем результат в память
memory.setAttr("isNewJourneyStarted", isNewJourneyStarted)

// Подключаем плагин
snippet("Common.DialogJourney.Manager")

// Создаем менеджер путешествия и передаем ему лид
let jm = new JourneyManager(lead)

// Выбираем путешествие
jm.selectJourney("myJourney")

// Завершаем выбранно путешествие
let isJourneyCompleted = jm.completeJourney()

// Пишем результат в память
memory.setAttr("isJourneyCompleted", isJourneyCompleted)

// Подключаем плагин
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)

// Подключаем плагин
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)

// Подключаем плагин
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)

// Подключаем плагин
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. В коде точки интеграции разработайте код согласно примерам выше.

Business.Helpers.Response

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

/** 
 * 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 и добавить нового редактора api@metabot.org.

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

Копируем название листа.

Копируем название столбцов в таблице.

Метод для добавления нового столбца

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

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 в строки в которую записались данные

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

{
    "status": "success",
    "message": "Row added successfully", // Сообщение, если есть ошибка - вернётся описание ошибки
    "rowId": 8 // Id в строки в которую записались данные
}

Метод для поиска и замены значения в ячейке

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

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) // Вернётся результат выполенния или код ошибки

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

{
    "status": "success",
    "message": 'Значение найдёно и измененно'
}

Документация Telegram-плагина

Описание

Этот плагин предоставляет удобный интерфейс для работы с Telegram Bot API. Он поддерживает отправку текстовых сообщений, фотографий, создание клавиатур и обработку ответов пользователя.

Основной класс TelegramMessage

Подключение и инициализация

let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()

Основные параметры

msg.text = "Ваше сообщение" // Текст сообщения
msg.parse_mode = "HTML" // Режим форматирования (HTML или MarkdownV2)
msg.protect_content = true // Защита контента от пересылки
msg.keyboard = "Да[yes]==Нет[no]" // Создание клавиатуры

Форматы клавиатуры

• Вертикальное разделение — используйте ==;

msg.keyboard = "Кнопка1[btn1]==Кнопка2[btn2]" // Кнопки будут расположены вертикально

• Горизонтальное разделение — используйте ||;

msg.keyboard = "Кнопка1[btn1]||Кнопка2[btn2]" // Кнопки будут расположены горизонтально

• Комбинированное разделение;

msg.keyboard = "Кнопка1[btn1]||Кнопка2[btn2]==Кнопка3[btn3]||Кнопка4[btn4]"

Специальные типы кнопок

• Запрос контакта:

msg.keyboard = "Отправить контакт[telegram_contact]"

• Запрос локации:

msg.keyboard = "Отправить локацию[telegram_location]"

• Ссылки:

msg.keyboard = "Посетить сайт[<https://example.com>]"

• Web App:

msg.keyboard = "Открыть приложение{<https://webapp-url.com>}"

• Ссылка на пользователя:

msg.keyboard = "Написать админу[tg://user?id=123456789]"

Примеры использования

Простое меню с обработкой ответов

Код будет работать корректно только в команде JS Callback.

let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()
msg.text = "Выберите действие:"
msg.keyboard = "Информация[info]==Помощь[help]==Настройки[settings]"
msg.parse_mode = "HTML"

switch (true) {
    case (isFirstImmediateCall):
        msg.send()
        return false

    case (msg.getMessagePayload()?.callback_data == "info"):
        msg.addReplyToText()
        bot.sendMessage("Информация о боте...")
        return false

    case (msg.getMessagePayload()?.callback_data == "help"):
        msg.addReplyToText()
        bot.sendMessage("Справка по использованию...")
        return false

    case (msg.getMessagePayload()?.callback_data == "settings"):
        msg.addReplyToText()
        bot.runScriptForLead(123, leadId) // Запуск скрипта настроек
        return false
}

Справочник методов

Основные методы отправки

• send() — отправка нового сообщения;
• edit() — редактирование существующего сообщения;
  
• addReplyToText() — добавление ответа к существующему сообщению;
  
• removeInlineKeyboard() — удаление клавиатуры.

Получение информации

• getMessagePayload() — получение информации о сообщении из вебхука:
  
  • message_id — ID сообщения;
    
  • text — текст сообщения/кнопки;
    
  • input_type — тип ввода ('write'/'press');
    
  • callback_data — данные колбэка;
    
  • payload — полные данные вебхука.

Обработка ответов пользователя

// Проверка типа ввода
if (msg.getMessagePayload()?.input_type == "write") {
    // Пользователь написал текст
}

// Проверка нажатия кнопки
if (msg.getMessagePayload()?.callback_data == "button_id") {
    // Пользователь нажал кнопку
}

Отладка

msg.debug("Отладочное сообщение") // Отправка отладочной информации. 
								  //Не отправляется пользователю но логируется в карточке лида

Лучшие практики

• Всегда проверяйте первый вызов:

if (isFirstImmediateCall) {
    msg.send()
    return false
}

• Добавляйте обработку текстовых сообщений:

if (msg.getMessagePayload()?.input_type == "write") {
    bot.sendMessage('Пожалуйста, используйте кнопки')
    return false
}

• Скрывайте клавиатуру после использования:

msg.addReplyToText() // После нажатия на кнопку записывает её в сообщение

Форматирование текста и entities

В плагине доступно два способа форматирования текста: HTML и MarkdownV2. По умолчанию параметр parse_mode не установлен — это сделано специально для возможности работы с entities (когда нужно сохранить форматирование текста, которое пользователь отправил в Telegram).

HTML форматирование

Документация: https://core.telegram.org/bots/api#html-style

msg.text = "<b>Жирный текст</b>\n<i>Курсив</i>\n<code>Моноширинный текст</code>"
msg.parse_mode = "HTML"

MarkdownV2 форматирование

Документация: https://core.telegram.org/bots/api#markdownv2-style

msg.text = "**Жирный текст**\n__Курсив__\n`Моноширинный текст`"
msg.parse_mode = "MarkdownV2"

Работа с entities

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

Пример сохранения форматированного сообщения пользователя:

let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()

msg.text = `Введите текст для рассылки`
msg.keyboard = `↩️ Назад[${backScripts}]`
msg.parse_mode = 'HTML'

switch (true) {
    case (isFirstImmediateCall):
        msg.send()
        return false

    case (msg.getMessagePayload()?.input_type == "write"):
        msg.removeInlineKeyboard()
        // Получаем webhook и извлекаем текст с entities
        let webhook = msg.getMessagePayload()
        let messageData = {
            "text": webhook?.payload?.message?.text,
            "entities": webhook?.payload?.message?.entities // Сохраняем entities для сохранения форматирования
        }

        // Сохраняем сообщение с форматированием в базу данных
        lead.setJsonAttr("messageData", messageData)

        bot.run({
            script_id: nextScript
        })
        return false

    default:
        msg.addReplyToText()
        bot.run({
            script_id: msg.getMessagePayload().callback_data
        })
        return true
}

В этом примере:

1. Когда пользователь отправляет форматированное сообщение, мы получаем не только сам текст, но и массив entities.
2. Entities содержат информацию о форматировании: жирный текст, курсив, ссылки и т.д.
3. Мы сохраняем и текст, и entities, чтобы позже можно было воспроизвести сообщение с точно таким же форматированием.
4. Важно: для работы с entities параметр parse_mode должен быть не установлен (режим по умолчанию).

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

let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()

let messageData = lead.getJsonAttr("messageData")

msg.text = messageData?.text
msg.entities = messageData?.entities

// Если попробовать использовать parse_mode то форматирование будет некорректным

Работа с файлами

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

Получение и обработка файлов

// Подключаем библиотеку
let TelegramMessage = require('Common.Integrations.Telegram')
let msg = new TelegramMessage()

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

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

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

msg.debug('Пользователь отправил файл: ' + uploadData.url)
msg.debug('Файл ID : ' + JSON.stringify(attachments[0]?.payload?.file_id)) // данная строка вспомогательная для
																		   // автоматизации вывода полученных 
lead.setAttr('file', uploadData.url)									   // файлов в других местах бота
// Запуск скрипта...
bot.runScriptByCodeForLead("recieveFile", lead.getData('id'))

bot.stop()
}

В этом примере:

1. Проверяем наличие прикрепленных файлов с помощью bot.getAllAttachments().
   
2. Если файл есть, скачиваем его через bot.downloadFileFromUrl().
   
3. Логируем получение файла с помощью msg.debug().
4. Сохраняем URL файла в атрибут лида.
5. Запускаем скрипт обработки файла.
6. Останавливаем текущий скрипт.

Дополнительный пример:

let TelegramMessage = require('Common.Integrations.Telegram')

let msg = new TelegramMessage()

msg.text = 'А теперь жду твоё фото 😉'
msg.keyboard = ``
msg.parse_mode = 'HTML'

let scriptCode = bot.getCurrentScriptCode()
lead.setAttr("script_code", scriptCode)

let data = bot.getAllAttachments()

switch (true) {

    case (isFirstImmediateCall):

        msg.send()
        return false
        break

    case (Boolean(data?.[0]?.type != 'image')):

        bot.sendMessage('Отправь сжатое изображение. Такой формат не подходит')
        return false
        break

    case (Boolean(data?.[0]?.type == 'image')):

        uploadData = bot.downloadFileFromUrl(data[0].url)
        msg.debug('Пользователь отправил файл: ' + uploadData.url)
        lead.setAttr('photo', uploadData.url)
        bot.sendMessage('Класс! Фото загрузил')
        return true
        break

    default:

        msg.addReplyToText()
        return true
}

Рекомендации по работе с файлами

• Всегда проверяйте наличие файлов перед их обработкой;
• Логируйте получение файлов для отладки;
• Сохраняйте URL файлов в атрибуты лида для дальнейшего использования;
• Запускайте отдельный скрипт для обработки файлов, чтобы разделить логику.