Salesbot

Начало работы с Salesbot

Salesbot - это бот, который можно запрограммировать на выполнение определенных действий. Он помогает получать от пользователей данные через мессенджеры (Telegram, Facebook Messenger, VK, Viber).

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

Подключение интеграции с чатами и настройка Salesbot на входящие обращения в Digital воронке

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

Подключение интеграции с чатами и настройка Salesbot на входящие обращения в Digital воронке

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

Настройка Salesbot в статусе в Digital воронке

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

Язык Salesbot

Языком управления Salesbot является структурированный JSON объект с определенными ключами.
Пример ниже задаст вопрос "Сообщите, пожалуйста, ваш номер телефона и e-mail" и проставит тег сделке Salesbot.
После ответа пользователя он провалидирует данные и ответит одним из указанных сообщений. Подробней про пресеты читайте в следующем разделе.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "show",
  6.                 "params": {
  7.                     "type": "text",
  8.                     "value": "Сообщите, пожалуйста, ваш номер телефона и e-mail"
  9.                 }
  10.             },
  11.             {
  12.                 "handler": "action",
  13.                 "params": {
  14.                     "name": "set_tag",
  15.                     "params": {
  16.                         "type": 2,
  17.                         "value": "salesbot"
  18.                     }
  19.                 }
  20.             }
  21.         ],
  22.         "answer": [
  23.             {
  24.                 "handler": "preset",
  25.                 "params": {
  26.                     "name": "contacts.validate_base_info",
  27.                     "params": {
  28.                         "empty_email": "Пришлите, пожалуйста, ваш e-mail",
  29.                         "empty_phone": "Пришлите, пожалуйста, ваш номер телефона",
  30.                         "invalid_phone": "Нам кажется, что в номере телефона ошибка",
  31.                         "success": "Спасибо",
  32.                         "empty_all": "Пришлите, пожалуйста, ваш номер телефона и e-mail"
  33.                     }
  34.                 }
  35.             }
  36.         ]
  37.     }
  38. ]

В объекте должен быть ключ question или answer.
Данные в объекте question отвечают за действия, которые будут происходить при отправке сообщения пользователю.
Данные в объекте answer отвечают за действия, которые будут происходить при ответе пользователя.

Ключей question или answer может быть более одного. Однако, существует ограничение на размер JSON, не более 64Кб.

В объекте question или answer должны находится обработчки. Обработчиком является объект с ключами handler и params.

Перед добавлением JSON объекта в бота, проверьте его на валидность. Также валидный объект можно получить, используя PHP. Вам необходимо создать массив Salesbot, а затем применить функцию json_encode c флагами JSON_PRETTY_PRINT и JSON_UNESCAPED_UNICODE.

Пример

  1. <?php
  2. $bot_text = 'Привет мир!';
  3. $salesbot = [
  4.     [
  5.         'question' => [
  6.             [
  7.                 'handler' => 'show',
  8.                 'params' => [
  9.                     'type' => 'text',
  10.                     'value' => $bot_text
  11.                 ]
  12.             ]
  13.         ],
  14.         'answer' => [
  15.             [
  16.                 'handler' => 'preset',
  17.                 'params' => [
  18.                     'name' => 'contacts.get_base_info',
  19.                 ]
  20.             ]
  21.         ]
  22.     ]
  23. ];
  24. echo json_encode($salesbot, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

Результатом выполнения кода выше будет валидный JSON объект, готовый для вставки в Salesbot'а Digital воронки.

Обработчики Salesbot

Код Описание
show Отправляет сообщение с текстом
buttons Обработка ответа, полученного от кнопок из мессенджеров (VK не поддерживает отображение кнопок)
action Действие
meta Обработка мета-данных
condition Условие
preset Обрабатывает данные по определенному алгоритму

Обработчик show

Внимание! Данный обработчик принимает неразобранное, в случае, если настроен в Salesbot'е входящих заявок.

Обработчик show отправляет сообщение или кнопки в чат с клиентом
Любой отправляемый текст на данный момент поддерживает слудующие элементы разметки:

  • {{contact.name}}, {{name}} - установка имени контакта
  • {{lead.id}} - установка id сделки
  • {{origin}} - установка источника сделки (telegram, vk, viber, facebook)
  • {{message_text}} - полученное сообщение клиента в логическом блоке ответа

Параметры обработчика для отправки текста

Пример

  1. {
  2.   "handler": "show",
  3.   "params": {
  4.     "type": "text",
  5.     "value": "Сообщите, пожалуйста, ваш номер телефона и e-mail"
  6.   }
  7. }
Параметр Тип Описание
typetextОтправка текста или кнопок
valuestringТекст, который будет отправлен пользователю

Параметры обработчика для отправки кнопок

Пример

  1. {
  2.   "handler": "show",
  3.   "params": {
  4.     "type": "buttons",
  5.     "value": "Выберите, пожалуйста, тип участия:",
  6.     "buttons": [
  7.       "Личное присутствие",
  8.       "Онлайн"
  9.     ]
  10.   }
  11. }
Параметр Тип Описание
type button Отправка текста или кнопок
value string Текст, который будет отправлен пользователю (В Messenger текст длинее 80 символов будет обрезан)
buttons array Массив, элементами которого являются тексты кнопок, которые будут отправленны

Обработчик buttons

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

Пример

  1. {
  2.   "handler": "buttons",
  3.   "params": [
  4.     {
  5.       "value": "Личное присутствие",
  6.       "params": [
  7.         {
  8.           "handler": "...",
  9.           "params": {...}
  10.         }
  11.       ]
  12.     },
  13.     {
  14.       "value": "Онлайн",
  15.       "params": [
  16.         {
  17.           "handler": "...",
  18.           "params": {...}
  19.         }
  20.       ]
  21.     }
  22.   ]
  23. }

Обработчик buttons ожидает на вход в параметры массив объектов, в которых можно вызвать любой из обработчиков, указанных на этой странице

Обработчик action

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

Код Описание
unsorted Действия я неразобранным
change_status Смена статуса
set_tag Установка тега
unset_tag Удаление тега
set_custom_fields Установка значений полей сделки/контакта
subscribe Подписка группы пользователей на чат в сущности

Действие unsorted

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

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "unsorted",
  5.     "params": {
  6.       "value": "accept"
  7.     }
  8.   }
  9. },
  10. {
  11.   "handler": "action",
  12.   "params": {
  13.     "name": "unsorted",
  14.     "params": {
  15.       "value": "decline"
  16.     }
  17.   }
  18. }
Параметр Тип Описание
value string accept/decline для принятия/отклонения

Действие change_status

Действие change_status позволяет сменить статус сделки

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "change_status",
  5.     "params": {
  6.       "value": 142
  7.     }
  8.   }
  9. }
Параметр Тип Описание
value int id статуса, в который будет переведена сделка

Действие set_tag

Действие set_tag установит сделке или контакту тег, имеет поддержку разметки {{origin}}, которая проставит источник сделки

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "set_tag",
  5.     "params": {
  6.       "type": 2,
  7.       "value": "Salesbot"
  8.     }
  9.   }
  10. },
  11. {
  12.   "handler": "action",
  13.   "params": {
  14.     "name": "set_tag",
  15.     "params": {
  16.       "type": 2,
  17.       "value": "{{origin}}"
  18.     }
  19.   }
  20. }
Параметр Тип Описание
type int Тип сущности, которой будет установлен тег (1 - контакт, 2 - сделка)
value string Название тега

Действие unset_tag

Действие unset_tag удалит тег у сделки или контакта

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "unset_tag",
  5.     "params": {
  6.       "type": 2,
  7.       "value": "Salesbot"
  8.     }
  9.   }
  10. }
Параметр Тип Описание
type int Тип сущности, у которой будет удален тег (1 - контакт, 2 - сделка)
value stringНазвание тега, который будет удален

Действие set_custom_fields

Действие set_custom_fields установит сделке или контакту значения кастомных полей.
ID полей можно узнать в разделе Настройки->Поля или используя метод GET accounts/current

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "set_custom_fields",
  5.     "params": {
  6.       "type": 2,
  7.       "value": "Значение поля",
  8.       "custom_fields_id": 123
  9.     }
  10.   }
  11. },
  12. {
  13.   "handler": "action",
  14.   "params": {
  15.     "name": "set_custom_fields",
  16.     "params": {
  17.       "type": 2,
  18.       "value": "{{message_text}}",
  19.       "custom_fields_id": 987
  20.     }
  21.   }
  22. }
Параметр Тип Описание
type int Тип сущности, которой будут заданы кастомные поля (1 - контакт, 2 - сделка)
value string Значение поля, которое будет установлено
custom_fields_id int id поля, в которое будет установлено значение

Действие subscribe

Действие subscribe подпишет группу пользователей на чат

Пример

  1. {
  2.   "handler": "action",
  3.   "params": {
  4.     "name": "subscribe",
  5.     "params": {
  6.       "type": "group",
  7.       "value": 111
  8.     }
  9.   }
  10. }
Параметр Тип Описание
type string В данный момент должно принимать значение group
value int id группы пользователей

Обработчик meta

Обработчик meta предназначен для обработки дополнительных данных, которые передаются при запуске чата

Подробней о передаче meta-данных читайте в документации мессенджеров:

Пример

  1. {
  2.   "handler": "meta",
  3.   "params": {
  4.     "delimiter": "-",
  5.     "values": [
  6.       "lead.tags",
  7.       "lead.custom_fields.123",
  8.       "lead.custom_fields.124",
  9.       "lead.tags"
  10.     ]
  11.   }
  12. }
Параметр Тип Описание
delimiter string Символ, по которому будет разделен входящий контент на элементы
values arrayМассив значений, в которые будут записаны элементы входящей информации.
Значения можно записать в теги или поля сделки

Обработчик condition

Обработчик condition предназначен для создания логических условий

Пример

  1. {
  2.   "handler": "condition",
  3.   "params": {
  4.     "term1": "lead.tags",
  5.     "term2": "telegram",
  6.     "operation": "=",
  7.     "result": [
  8.       {
  9.         "handler": "action",
  10.         "params": {
  11.           "name": "change_status",
  12.           "params": {
  13.             "value": 123
  14.           }
  15.         }
  16.       }
  17.     ]
  18.   }
  19. }
Параметры Тип Описание
term1 string Условие 1 (На данный момент только lead.tags, который возвращает список тегов)
term2 string Условие 2
operation string Оператор сравнения ('=' или '!=')
result array При успешном сравнении, массив обработчиков

Обработчик preset

Обработчик preset предназначен для обработки входящих сообщений по предустановленным шаблонам

Параметр Тип Описание
name string Название обработчика
params array Параметры обработчика

Пресет contacts.validate_base_info

Пресет contacts.validate_base_info позволяет получить и проверить информацию от пользователя, а затем дозапросить недостающую

Пример

  1. {
  2.   "handler": "preset",
  3.   "params": {
  4.     "name": "contacts.validate_base_info",
  5.     "params": {
  6.       "empty_email": "Пришлите, пожалуйста, ваш e-mail",
  7.       "empty_phone": "Пришлите, пожалуйста, ваш номер телефона",
  8.       "invalid_phone": "Нам кажется, что в номере телефона ошибка",
  9.       "success": "Спасибо",
  10.       "empty_all": "Пришлите, пожалуйста, ваш номер телефона и e-mail"
  11.     }
  12.   }
  13. }
Параметр Тип Описание
empty_email string Сообщение при отсутсвии email у контакта
empty_phone string Сообщение при отсутсвии телефона у контакта
invalid_phone string Сообщение при получении невалидного телефона
success string Сообщение после получения всех данных
empty_all string Сообщение при отсутсвии всех данных

Пресет contacts.get_base_info

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

Пример

  1. {
  2.   "handler": "preset",
  3.   "params": {
  4.     "name": "contacts.get_base_info"
  5.   }
  6. }

Примеры

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

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "action",
  6.                 "params": {
  7.                     "name": "subscribe",
  8.                     "params": {
  9.                         "type": "group",
  10.                         "value": 111
  11.                     }
  12.                 }
  13.             }
  14.         ]
  15.     }
  16. ]

Перевод сделки в нужный статус.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "action",
  6.                 "params": {
  7.                     "name": "change_status",
  8.                     "params": {
  9.                         "value": 142
  10.                     }
  11.                 }
  12.             }
  13.         ]
  14.     }
  15. ]

Отправка клиенту любого текста.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "show",
  6.                 "params": {
  7.                     "type": "text",
  8.                     "value": "Здравствуйте"
  9.                 }
  10.             }
  11.         ]
  12.     }
  13. ]

Отправка сообщения с кнопками выбора.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "show",
  6.                 "params": {
  7.                     "type": "buttons",
  8.                     "value": "Выберите, пожалуйста, тип участия:",
  9.                     "buttons": [
  10.                         "Личное присутствие",
  11.                         "Онлайн"
  12.                     ]
  13.                 }
  14.             }
  15.         ],
  16.         "answer": [
  17.             {
  18.                 "handler": "buttons",
  19.                 "params": [{
  20.                     "regex": "/личное/iu",
  21.                     "params": [{
  22.                         "handler": "action",
  23.                         "params": {
  24.                             "name": "set_custom_fields",
  25.                             "params": {
  26.                                 "type": 1,
  27.                                 "value": "Личное присутствие",
  28.                                 "custom_fields_id": 4242
  29.                             }
  30.                         }
  31.                     }]
  32.                 },
  33.                     {
  34.                     "regex": "/онлайн/iu",
  35.                     "params": [{
  36.                         "handler": "action",
  37.                         "params": {
  38.                             "name": "set_custom_fields",
  39.                             "params": {
  40.                                 "type": 1,
  41.                                 "value": "Онлайн",
  42.                                 "custom_fields_id": 4242
  43.                             }
  44.                         }
  45.                     }]
  46.                 }]
  47.             }]
  48.     }
  49. ]

Установка тега для сделки.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "action",
  6.                 "params": {
  7.                     "name": "set_tag",
  8.                     "params": {
  9.                         "type": 2,
  10.                         "value": "salesbot"
  11.                     }
  12.                 }
  13.             }
  14.         ]
  15.     }
  16. ]

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

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "action",
  6.                 "params": {
  7.                     "name": "set_custom_fields",
  8.                     "params": {
  9.                         "type": 2,
  10.                         "custom_fields_id": 123,
  11.                         "value": "Значение поля"
  12.                     }
  13.                 }
  14.             }
  15.         ]
  16.     }
  17. ]

Сохранение метаданных в карточку сделки.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "meta",
  6.                 "params": {
  7.                     "delimiter": "-",
  8.                     "values": [
  9.                         "lead.tags",
  10.                         "lead.custom_fields.123",
  11.                         "lead.custom_fields.124",
  12.                         "lead.tags"
  13.                     ]
  14.                 }
  15.             }
  16.         ]
  17.     }
  18. ]

Зарпос email и телефона, запись в карточку только из первого ответа.

Пример

  1. [
  2.     {
  3.         "question": [
  4.             {
  5.                 "handler": "show",
  6.                 "params": {
  7.                     "type": "text",
  8.                     "value": "Сообщите, пожалуйста, ваш номер телефона и e-mail"
  9.                 }
  10.             }
  11.         ],
  12.         "answer": [
  13.             {
  14.                 "handler": "preset",
  15.                 "params": {
  16.                     "name": "contacts.get_base_info"
  17.                 }
  18.             }
  19.         ]
  20.     }
  21. ]