Рассылки в 360dialog

В этой статье вы узнаете, как запустить рассылки через канал 360dialog (Whatsapp).Первым делом перед созданием Слота необходимо создать Канал Проекта 360dialog (Whatsapp) или 360dialog (cloud). Подробнее об этом: 360dialog (WhatsApp), 360dialog (cloud)

Создание шаблона рассылки

Шаблоны — это сообщения, с помощью которых Бот в WhatsApp стартует Чат с Собеседником. Чтобы произвести рассылку по Собеседникам в WhatsApp, необходимо создать шаблон, отправить на согласование, в случае неуспеха переформулировать и отправить новый шаблон, а в случае согласования инициировать рассылку с помощью Слота Notification.Подробнее: Создание и согласование шаблонов рассылочных сообщений в 360dialog

Создание слота

После создания шаблона рассылки, создайте Слот Notification и заполните поля Слота на всех вкладках.

Вкладка General

Вкладка General содержит основные настройки Слота.

1. Вид вкладки:

2. Элементы и поля вкладки:

3. 1. Name* — название Слота, которое будет отображено в Дерево сценария. Максимальная длина значения поля — 40 символов.

   2. Destination channel* — Конечный канал, через который будет осуществляться рассылка.

   3. Chatbot webhook — вебхук, на который Агент будет получать Запрос на рассылку. Значение появится в поле после сохранения и повторного открытия Слота. Вебхук начнет работать после Обучение Агента.

   4. Кнопка копирования вебхука.

   5. 1. По нажатию кнопки адрес вебхука копируется в буфер обмена.

      2. Кнопка становится доступной к нажатию, только когда поле Chatbot webhook заполнено значением вебхука.

   6. Кнопка GENERATE NEW WEBHOOK.

   7. 1. Кнопка становится доступной к нажатию, только когда поле Chatbot webhook заполнено значением вебхука.

      2. По нажатию кнопки происходит генерация нового вебхука.

      3. Изменения после перегенерации вебхука вступают в силу после переобучения Агента.

Вкладка Incoming Data

Вкладка Incoming Data предназначена для настроек парсинга тела Запрос на рассылку для последующего использования полученных данных в Сценарий агента.

1. Вид вкладки:

2. Поля вкладки:

3. 1. PARSE REQUEST BODY — массив пар Context key — Request key.

   2. 1. Context key — имя Контекстная переменная для парсинга;

      2. Request key — ключ из тела Запрос на рассылку, значение которого будет записано в Context key либо Выражение.

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

      4. Пример: {{ data["keys"] }}

Вкладка Destination

На вкладке Destination происходит настройка отправки рассылочных сообщений в выбранный на вкладке General Конечный канал, исходя из его требований.

1. Вид вкладки:
2. Поля вкладки:

3. 1. GENERAL PARAMETERS — общие настройки для отправки сообщения:

   2. 1. Template name* — название шаблона в 360dialog, по которому происходит рассылка (поле Name в аккаунте Whatsapp (360dialog). Подробнее: Создание и согласование шаблонов рассылочных сообщений в 360dialog )

      2. 1. Допустимые значения:

         2. 1. Строка;

            2. Выражение в синтаксисе.

         3. Валидация: по нажатию кнопки CREATE (при создании слота) или SAVE (при редактировании слота) проверяется наличие значения в поле:

         4. 1. при отсутствии значения в поле выводится ошибка Please enter text.

      3. Namespace* — название из параметра в аккаунте в 360dialog (поле Namespace), требуемое в Запрос на рассылку.

      4. 1. Допустимые значения:

         2. 1. Строка;

            2. Выражение в синтаксисе.

         3. Валидация: по нажатию кнопки CREATE (при создании слота) или SAVE (при редактировании слота) проверяется наличие значения в поле:

         4. 1. при отсутствии значения в поле выводится ошибка Please enter text.

      5. Language code* — название из параметра “язык шаблона” (поле Languages) в аккаунте в 360dialog, требуемое в Запрос на рассылку.

      6. 1. Допустимые значения:

         2. 1. Строка;

            2. Выражение в синтаксисе.

         3. Валидация: по нажатию кнопки CREATE (при создании слота) или SAVE (при редактировании слота) проверяется наличие значения в поле:

         4. 1. при отсутствии значения в поле выводится ошибка Please enter text.

   3. TEMPLATE PARAMETERS — параметры для подстановки в шаблон рассылки, указанный в поле Template name*, массив пар Template parameter — Value:
   4. 1. Синтаксис соответствует документации WhatsApp.

      2. Template parameter — тип параметров. Порядок указания параметров в Слоте должен соответствовать порядку параметров в шаблоне.

      3. 1. Возможные значения поля:

         2. 1. Параметры для подстановки медиа в шаблон:
            2. 1. image — для подстановки изображения;

               2. document — для подстановки документа;

               3. video — для подстановки видео.

               4. В шаблоне допустим только 1 параметр медиа.

            3. Параметры для подстановки текста и кнопок в шаблон:

            4. 1. body — для подстановки текстовых данных.

               2. Количество параметров данного типа не ограничено.
               3. button_url — для подстановки ссылки или номера телефона в кнопку.

               4. Максимальное количество кнопок, содержащих ссылку — 1.

               5. Максимальное количество, содержащих номер телефона — 1. Номер телефона подставляется в формате wa.me/[phone])

      4. Value — точное значение, Выражение или Контекстная переменная, которая должна быть подставлено в шаблон.

      5. 1. Возможно использование переменных из поля Context key вкладки Incoming Data , так как парсинг данных выполняется перед формированием запроса в Конечный канал

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

         3. Пример: {{ data["keys"] }}

Запуск рассылки

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

Формат запроса на рассылку

1. Запрос на рассылку должен обязательно включать идентификатор Собеседника в конечном канале на первом уровне JSON-а, случае c WhatsApp, это номер телефона. По этому идентификатору Платформа вычислит Чат или в случае, если он не существует, создаст новый Чат для отправки запроса. Название ключа зависит от Конечный канал.

2. 1. Формат идентификатора:

   2. 1. поле типа “текст”;

      2. От 10 до 18 цифр (от 11 до 19 с учетом +);

      3. Допускается знак + в начале.

3. Запрос на рассылку может быть срочным или несрочным (параметр "is_urgent"):

4. 1. значение true — для срочного Запрос на рассылку — выполняется незамедлительно и прерывает Активный диалог.

   2. значение false — для несрочного Запрос на рассылку — выполняется после закрытия Диалога.

   3. если ключ is_urgent не найден, используется значение по умолчанию false.

5. Запрос на рассылку должен быть POST-запросом с валидным телом JSON и заголовком "Content-Type": "application/json"

6. Лимит на запросы на рассылку по умолчанию — 20 запросов в секунду на Компания. Лимит можно изменить через техподдержку.

7. Пример запроса на рассылку: POST <http://localhost:10040/notification/13::9de6d0fbc9a547659457a0f7a0e21eda/chat> headers: {"Content-Type": "application/json"} body: { "phone_number": "79291642944", "is_urgent": true, "extra": { "foo": 42 } }

Работа слота

Работа слота начинается с момента получения Платформа Запрос на рассылку из внешней системы.

1. Обработка входящего запроса на рассылку

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

Ответ, полученный на запроса на рассылку	Расшифровка ответа
HTTP status: 429	Превышение Лимит на запросы на рассылку для Компания
HTTP status: 405	Запрос на рассылку не с POST-методом
HTTP status: 400	в Запрос на рассылку нет заголовка content-type: application/json невалидный JSON в теле Запрос на рассылку
HTTP status: 404	Не найдена Компания, связанная с Идентификатор рассылки (он содержится в вебхуке в поле Chatbot webhook)
HTTP status: 400 invalid BODY: “status”: “Recipient ID not found or invalid.”	идентификатор Собеседника не был найден или он невалидный
HTTP status: 404 Not Found BODY: “status”: “Notification not found”	нет обученного Агента со Слотом с таким вебхуком
HTTP status: 404 Not Found BODY: “status”: “There is no active channel for received event”	Канал Проекта данного слота Notification удален\неактивен
HTTP status: 200 OK BODY: “status”: “Accepted for execution” “task_id”:	Запрос на рассылку поставлен в очередь на выполнение

2. Выполнение задачи на рассылку

1. Слот Notification собирает запрос в Конечный канал из параметров на вкладке Destination и идентификатора собеседника (phone_number).
2. Далее слот Notification выполняет отправку запроса на рассылку в выбранный в поле Destination Channel Конечный канал.

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

Событие	Что записывается в переменную notification_raw_status	Что записывается в переменную notification_status	Переход по Сценарию Агента
Не удалось составить запрос по какой-либо причине, например, не удалось спарсить и создать переменную, которая используется в id шаблона	{‘description’:’failed to build request’}	‘failed’	переход в ветку Notification fail
Конечный канал принял запрос и ответил успешным ответом	{‘description’:’received by channel’, ‘channel_response’: тело ответа от канала (объект)}(если application/json = объект, если text = str; в иных cлучаях записывается null).	‘sent’	Агент ожидает статуса обработки рассылки от Конечный канал
Запрос в Конечный канал ушел, но в ответ получен response с кодом 4хх или 5хх	{‘description’:’channel error <код ответа> ’channel_response’: тело ответа от канала}Если в ответе на запуск рассылки пришел JSON-объект, то в ’channel_response’ сохраняется этот JSON-объект. Если в ответе пришел текст, то сохраняется текст. В ином случае сохраняется None.	‘failed’	переход в ветку Notification fail
Не удалось выполнить запрос в Конечный канал (канал недоступен, пинг не идет и т.д.)	{‘description’:’channel inaccessible’}	‘failed’	переход в ветку Notification fail

3. Переход в ветки подслотов и ответы из канала

После того как Конечный канал принял запрос на рассылку, происходит переход в один из Подслотов:

Переход в Подслот	Причины	Что записывается в переменную notification_raw_status	Что записывается в переменную notification_status
Переход в ветку Notification Fail	Любые проблемы, относящиеся к данной конкретной задаче на рассылку, кроме отсутствия аккаунта на данном идентификаторе Собеседника	{‘description’:’channel couldn’t sent message’, ‘channel_response’: тело ответа от канала}Если в ответе на запуск рассылки пришел JSON-объект, то в ’channel_response’ сохраняется этот JSON-объект. Если в ответе пришел текст, то сохраняется текст. В ином случае сохраняется None	‘failed’
Переход в ветку Notification no account	Отсутствие аккаунта на данном идентификаторе Собеседника (в случае WhatsApp — номере телефона)	не создается в Контекст Чата	‘no_account’
Переход в ветку Notification Success	Получение статуса отправки, доставки или прочтения сообщения Собеседником	{‘description’:’success’,‘channel_response’: тело ответа от канала (объект)} (если application/json = объект, если text = str; в иных cлучаях записывается null).	‘delivered’
Переход в ветку Notification Success	получение Сообщение собеседника	{‘description’:’success’, ‘channel_response’: тело принятного запроса от канала (объект), откуда распарсили текст Сообщение собеседника} (если application/json = объект, если text = str; в иных cлучаях записывается null).	‘delivered’