Как идентифицировать клиента из чат-бота

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

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

Рассмотрим на примере телеграма со связкой по номеру телефона.

Настройки в Mindbox

Для начальной интеграции Mindbox и Botmother (тип — «Другое»):

1. Создайте точку интеграции:

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

2. Создайте дополнительное поле типа «Идентификатор» для хранения идентификатора в мессенджере:

Далее настройки непосредственно для добавления и проверки клиентов из бота:

3. Создайте операцию для добавления клиента:

4. Создайте автоматическую SMS-рассылку для отправки кода подтверждения:

Параметр — ${Recipient.AuthentificationCode}

5. Создайте операцию для отправки кода подтверждения:

Настройки в Botmother и мессенджере

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

Стартовый экран — запрос номера и его передача в Mindbox

На стартовом экране (показывается при вводе /start):

1. Добавьте компонент «Кнопки с подсказками».
   1. Введите текст-обращение к пользователю.
   2. Нажмите «Добавить кнопку».
   3. Введите текст на кнопке.
   4. Тип кнопки — «Поделиться контактом».

2. Добавьте компонент «Ввод от пользователя».
   1. Задайте имя переменной, в которой будет храниться ответ пользователя, например usPhone
   2. Ожидаемый тип данных — Файл контакта.
   3. В настройках компонента можно указать текст, который будет выводится при невалидном ответе пользователя. Например, подсказать формат ввода номера.

3. Добавьте компонент «Запрос».
   Для его заполнения нужно будет обратиться к спецификации ранее созданной в Mindbox операции добавления клиента:
   1. Метод запроса — POST
   2. URL запроса — скопируйте из спецификации, указав корректную точку интеграции и синхронный тип вызова.
   3. Заголовки — скопируйте из спецификации JSON-формата. Секретный ключ точки интеграции можно взять с ее страницы.
   4. «Использовать парсер» — JSON
   5. Тело запроса — нужны только элементы для передачи идентификатора в телеграме и мобильного номера с параметрами Botmother в качестве их значений.

Подробнее по последнему пункту.

Шаблон тела запроса для передачи в Mindbox идентификатора и номера выглядит следующим образом:

{
  "customer": {
    "ids": {
      "telegramID": "<TelegramID>"
    },
    "mobilePhone": "<Мобильный телефон>"
  }
}

В значения полей нужно записать переменные Botmother:

• идентификатор в мессенджере — {{this_user.platform_id}}
• мобильный телефон — переменная, заданная на стартовом экране в кнопке с подсказками — {{usPhone}}

Код для компонента:

{
  "customer": {
    "ids": {
      "telegramID": "{{this_user.platform_id}}"
    },
    "mobilePhone": "{{usPhone}}"
  }
}

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

4. Добавьте компонент «Перемотка» для перехода на новый экран.

Создайте новый экран: нажмите «Добавить экран» в нижней части страницы, укажите его название и выберите его в «Перемотке» стартового экрана:

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

Или дополняется, если ранее на проекте был клиента с данным номером:

Второй экран — отправка кода авторизации

На новом экране:

1. Добавьте компонент «Запрос».
   Для его заполнения нужно будет обратиться к спецификации ранее созданной в Mindbox операции отправки кода авторизации.
   1. Метод запроса — POST
   2. URL запроса — скопируйте из спецификации, указав корректную точку интеграции и синхронный тип вызова.
   3. Заголовки — скопируйте из спецификации JSON-формата. Секретный ключ точки интеграции можно взять с ее страницы.
   4. «Использовать парсер» — JSON
   5. Тело запроса — в данном случае в запросе нужно передать только мобильный номер. Скопируйте тело из спецификации или из запроса выше, оставив в нем только узел для мобильного телефона:

{
    "customer": {
        "mobilePhone": "{{usPhone}}"
    }
}

Вызов операции запросит Mindbox сформировать код авторизации, отправить его пользователю и вернуть его в Botmother для дальнейшей проверки:

2. Добавьте компонент «Перемотка». Создайте новый экран и укажите его в «Перемотке» второго экрана:

Третий экран — ввод кода пользователем и его проверка

На новом экране:

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

2. Добавьте компонент «Ввод от пользователя».

   1. Задайте имя переменной, в которой будет храниться ответ пользователя, например code
   2. Ожидаемый тип данных — Число.

3. Добавьте компонент «Разливка».

   1. «Имя переменной, откуда развилка возьмет значение» — переменная из пункта выше, в которую записывается ответ пользователя.
   2. Переход по умолчанию — если клиент введет неправильный код, возвращаем его обратно на текущий же экран.
   3. Сообщение по умолчанию — сообщение клиенту о неправильном коде.
   4. Добавьте Цель1 — то, что хотим получить.
      1. Тип данных — число
      2. Значение — правильный код. Он был получен на предыдущем экране из Mindbox и хранится в переменной {{last_request.authenticationCode}}
      3. Переход — создайте экран для показа при правильном коде и укажите его здесь.

Четвертый экран — сообщение об успешной регистрации

На новом экране:

1. Добавьте компонент «Сообщение», чтобы сообщить клиенту об успешной регистрации.
2. Добавьте компонент «Перемотка», чтобы перевести пользователя, например, в Главное меню.

Повторная регистрация

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

Рассмотрим пример настройки для повторной регистрации.

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

Дополните созданный бот:

1. На экране подтверждения контакта в компонент «Развилка» впишите переменную, например, verified, со значение true:

2. На экране регистрации добавьте «Развилку», которая проверяет значение переменной verified и при значении true переводит на экран повторной регистрации:

3. На новом экране уточните у клиента по намерению и при подтверждении переводите на новый экран:

4. На новом экране добавьте компонент «Очистка переменных» со сбросом всех переменных и «Перемотку» на экран регистрации:

Блокирование использования бота до регистрации

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

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

Нажмите «Сохранить» в нижней части страницы.

Бот готов.