Docs

История релизов

НАЧАЛО РАБОТЫ С ПЛАТФОРМОЙ

ПЕРЕД СОЗДАНИЕМ АГЕНТА

КОНСТРУКТОР СЦЕНАРИЯ АГЕНТА

СОЗДАНИЕ АГЕНТА НА ПЛАТФОРМЕ

ОБУЧЕНИЕ И ТЕСТИРОВАНИЕ АГЕНТА

РАЗМЕЩЕНИЕ АГЕНТА В КАНАЛАХ

ЭКСПЛУАТАЦИЯ АГЕНТА

АНАЛИТИКА ОБЩЕНИЯ АГЕНТА

Explore

СЛОТЫ

Рассылки в WhatsApp| Слот Notification

ёНазначение и общая информация

⁠

@Слот⁠

Notification —

@Слот⁠

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

@Слот⁠

позволяет отправить сообщение в случае, когда

@Чат⁠

@Собеседник⁠

ом еще не создан (нет

⁠

), или

@Чат⁠

создан, но

@Агент⁠

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

@Чат⁠

первым после определенного таймаута (ограничение некоторых каналов).

@Слот⁠

позволяет обработать статусы на рассылочное сообщение.

Примечание: В данное время работает с
WhatsApp (360dialog)⁠
,
WhatsApp (Edna Platform)⁠
и
Chat2Desk⁠
.

Слот Notification принимает

@Запрос на рассылку⁠

с данными для рассылки из внешней системы (CRM, например), формирует и отправляет запрос в

@Канал Агента⁠

, затем получает ответ из

@Конечный канал⁠

и в зависимости от полученного статуса рассылки

@Общение⁠

переходит в один из

@Подслот⁠

ов.

Корректный

@Запрос на рассылку⁠

через

@Слот⁠

Notification создаст

@Чат⁠

, если его нет в

@Платформа⁠

, даже в случае, когда

@Собеседник⁠

а не существует в

@Конечный канал⁠

(например, номер телефона адресата в

@Запрос на рассылку⁠

корректный, но человек не зарегистрирован в WhatsApp)

⁠

@Слот⁠

Notification является комплексным

@Слот⁠

ом и не может существовать без трех

@Дочерний слот⁠

ов

@Notification fail⁠

@Notification no account⁠

@Notification success⁠

, которые начинают собственные ветки, в которые будет осуществлен переход после получения статуса рассылки.

Добавить другие дочерние слоты невозможно.

⁠

@Подслот⁠

@Notification fail⁠

предназначен для продолжения

@Сценарий⁠

, если не удалось отправить рассылку в

@Конечный канал⁠

⁠

@Подслот⁠

@Notification no account⁠

предназначен для продолжения

@Сценарий⁠

после рассылки, которая была успешно отправлена в

@Конечный канал⁠

, но

@Конечный канал⁠

сообщил, что получатель не найден (например, у получателя нет аккаунта WhatsApp при рассылках через WhatsApp).

⁠

@Подслот⁠

@Notification success⁠

предназначен для продолжения

@Сценарий⁠

после рассылки, которая была успешно отправлена в

@Конечный канал⁠

и был получен успешный статус либо ответ

@Собеседник⁠

а.

Особенности работы слота Notification в разных каналах

Особенности работы слота Notification в разных каналах

360dialog (Whatsapp)

Edna Pulse

Chat2Desk

Поддерживаемый канал

360dialog (Whatsapp)

Иконка в шапке слота

Ключевой идентификатор собеседника в конечном канале

Номер телефона в формате

Ключ идентификатора в теле запроса на рассылку

phone_number

Валидация Идентификатор собеседника в запросе на рассылку

Поле типа “текст”;

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

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

Пример входящего запроса на рассылку

POST <URL>
headers: {"Content-Type": "application/json"}
body: {
"phone_number": "79291642944",
"is_urgent": true,
"extra": {
"foo": 42
}
}

Notification success

В виду особенностей работы 360dialog, порядок получения статусов-ответов на рассылку может быть спутан, либо статусы прийти после ответа собеседника, поэтому для перехода в ветку Notification success учитываем первое из следующих событий, поступившее из канала после отправки рассылки

статус sent на рассылку

статус delivered на рассылку

статус read на рассылку

⁠

@Сообщение собеседника

⁠

Из-за особенностей 360dialog, если до ответа

@Собеседник

⁠

а на рассылку

@Агент

⁠

попытается отправить новые сообщения методом обычной отправки, а не рассылки (если после

@Подслот

⁠

@Notification success

⁠

стоят

@Слот

⁠

@Text

⁠

@Attachment

⁠

@Button Menu

⁠

), то канал ответит ошибкой и не примет их.

Notification fail

Реализация

@Слот

⁠

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

@Активный диалог

⁠

, то придет текст и success, а если такого нет, то ошибка и ветка failed

Notification no account

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

Проверка наличия

@Чат

⁠

а в

@360dialog (Whatsapp)

⁠

360dialog предоставляет специальный метод, позволяющий проверить наличие аккаунта:

Если метод возвращает информацию об отсутствии аккаунта, то

@Сценарий

⁠

идет по ветке

@Подслот

⁠

@Notification no account

⁠

@Контекстная переменная

⁠

@notification_raw_status

⁠

записывается {‘description’:’no account on <номер телефона\ключевой идентификатор собеседника>’, ‘channel_response’: тело ответа от канала as is (объект) }(если application/json = объект, если text = str; в иных cлучаях записывается null).

@Контекстная переменная

⁠

@notification_status

⁠

записывается ‘no_account’.

В выгрузке истории сообщений будет записано Check account <номер телефона>: No account.

Если аккаунт найден, то выполняется рассылка.

Show hidden columns

⁠

Создание и настройки слота

Атрибуты слота

Вкладка General

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

@Слот⁠

а.

Вид вкладки:

⁠

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

Name* — название

@Слот⁠

а, которое будет отображено в

@Дерево сценария⁠

. Максимальная длина значения поля — 40 символов.

Destination channel* —

@Конечный канал⁠

, через который будет осуществляться рассылка.

Chatme webhook — вебхук, на который

@Агент⁠

будет получать

@Запрос на рассылку⁠

. Значение появится в поле после сохранения и повторного открытия

@Слот⁠

а. Вебхук начнет работать после

@Обучение⁠

@Агент⁠

а.

⁠

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

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

⁠

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

Кнопка GENERATE NEW WEBHOOK.

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

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

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

@Агент⁠

а.

Вкладка Incoming Data

Вкладка Incoming Data предназначена для настроек парсинга тела

@Запрос на рассылку⁠

для последующего использования полученных данных в

@Сценарий⁠

Вид вкладки:

⁠

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

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

Context key — имя

@Контекстная переменная⁠

для парсинга;

Request key — ключ из тела

@Запрос на рассылку⁠

, значение которого будет записано в Context key либо

@Выражение⁠

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

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

Вкладка Destination

На вкладке Destination происходит настройка отправки рассылочных сообщений в выбранный на вкладке General

@Конечный канал⁠

, исходя из его требований.

Вкладка Destination для разных каналов

Вкладка Destination для разных каналов

360dialog (Whatsapp)

Edna Pulse

Chat2Desk

360dialog (Whatsapp)

Destination

Вкладка Destination в для канала Whatsapp (Dialog360)

Вид вкладки: ⁠⁠

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

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

Template name* — название шаблона в

360dialog⁠

, по которому происходит рассылка (поле Name в аккаунте

@360dialog (Whatsapp)⁠

. Подробнее:

https://coda.io/d/_dQZi0KPCnEG/_suV8E#_luF5N⁠

)

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

Строка;

⁠

@Выражение⁠

в синтаксисе.

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

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

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

@Запрос на рассылку⁠

. Подробнее:

https://coda.io/d/_dQZi0KPCnEG/_suV8E#_luF5N⁠

⁠

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

Строка;

⁠

@Выражение⁠

в синтаксисе.

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

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

@Запрос на рассылку⁠

. Подробнее:

https://coda.io/d/_dQZi0KPCnEG/_suV8E#_luF5N⁠

⁠

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

Строка;

⁠

@Выражение⁠

в синтаксисе.

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

TEMPLATE PARAMETERS — параметры для подстановки в шаблон рассылки, указанный в поле Template name*, массив пар Template parameter — Value: ⁠⁠

Синтаксис соответствует

документации WhatsApp⁠

Template parameter — тип параметров. Порядок указания параметров в

@Слот⁠

е должен соответствовать порядку параметров в шаблоне.

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

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

image — для подстановки изображения;

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

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

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

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

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

Количество параметров данного типа не ограничено. ⁠⁠

button_url — для подстановки кнопки.

Максимальное количество кнопок, поддерживаемое

@360dialog (Whatsapp)⁠

— 3 штуки.

Value — точное значение,

@Выражение⁠

или

@Контекстная переменная⁠

, которая должна быть подставлено в шаблон.

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

@Конечный канал⁠

⁠

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

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

Show hidden columns

⁠

Подслоты Notification fail, Notification no account и Notification success.

⁠

При создании слота автоматически генерируются три

@Дочерний слот⁠

@Notification fail⁠

@Notification no account⁠

@Notification success⁠

Эти

@Дочерний слот⁠

ы не подлежат изменению и их можно удалить только с

@Родительский слот⁠

ом.

Расположение

@Дочерний слот⁠

ов определяется автоматически, перемещать их нельзя:

@Notification fail⁠

всегда является самым верхним

@Подслот⁠

ом в данном

@Комплексный слот⁠

;

⁠

@Notification no account⁠

всегда является вторым по порядку

@Подслот⁠

ом в данном

@Комплексный слот⁠

;

⁠

@Notification success⁠

всегда является самым нижним

@Подслот⁠

ом в данном

@Комплексный слот⁠

Добавлять новые

@Подслот⁠

ы в

@Родительский слот⁠

Notification нельзя.

Атрибуты подслотов

Notification Fail

⁠

Name* — название

@Подслот⁠

а, которое будет отображено в

@Дерево сценария⁠

. Максимальная длина значения поля — 40 символов.

Подсказка с текстом “You’ll get variable notification_status=”failed” in chat context. Having it you can check the error description in variable notification_raw_status”.

Notification No Account

⁠

Name* — название

@Подслот⁠

а, которое будет отображено в

@Дерево сценария⁠

. Максимальная длина значения поля — 40 символов.

Подсказка с текстом “You’ll get variable notification_status=”no_account” in chat context. Having it you can check the error description in variable notification_raw_status”.

Notification Success

⁠

Name* — название

@Подслот⁠

а, которое будет отображено в

@Дерево сценария⁠

. Максимальная длина значения поля — 40 символов.

Подсказка с текстом “This slot will be executed in case of receiving any first positive status (sent, delivered, read etc) of sending notification from the messenger. Sometimes statuses come in wrong order, e.g “read” comes earlier than “sent”. Only the first status will be proceeded, next ones will be ignored.”

Запрос на рассылку на вебхук слота Notification

⁠

@Слот⁠

Notification позволяет

@Агент⁠

у принять

@Запрос на рассылку⁠

в виде

@Входящий запрос⁠

на Chatbot webhook (из вкладки General), в т.ч. в несуществующий

@Чат⁠

(в таком случает

@Чат⁠

будет создан)

⁠

@Запрос на рассылку⁠

должен обязательно включать идентификатор

@Собеседник⁠

а в конечном канале, он входит в состав

@channel_chat_id⁠

и используется для генерации

⁠

(например, это номер телефона в случае c WhatsApp). По этому идентификатору

@Платформа⁠

вычислит

@Чат⁠

или в случае, если он не существует, создаст новый

@Чат⁠

для отправки запроса

⁠

@Запрос на рассылку⁠

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

значение true — для срочного

@Запрос на рассылку⁠

— выполняется незамедлительно и прерывает

@Активный диалог⁠

значение false — для несрочного

@Запрос на рассылку⁠

— выполняется после закрытия

@Диалог⁠

а.

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

Важно: в
@Notification⁠
поиск параметра "is_urgent" будет осуществляться только по телу запроса, в отличие от
@Incoming Request⁠
, где поиск параметра "is_urgent" происходит и в теле, и в параметрах запроса в URL.

Требования к

@Запрос на рассылку⁠

POST-запрос с валидным телом JSON и заголовком "Content-Type": "application/json"

В теле

@Запрос на рассылку⁠

на первом уровне JSON-а должен быть валидный идентификатор

@Собеседник⁠

а в

@Конечный канал⁠

, название ключа зависит от типа

@Конечный канал⁠

. Требования к идентификаторам отражены таблице

Особенности работы слота Notification в разных каналах⁠

⁠

@Лимит на запросы на рассылку⁠

по умолчанию — 20 запросов в секунду на

@Компания⁠

. Лимит можно изменить через техподдержку.

Пример

@Запрос на рассылку⁠

@360dialog (Whatsapp)⁠

: POST <http://localhost:10040/notification/13::9de6d0fbc9a547659457a0f7a0e21eda/chat> headers: {"Content-Type": "application/json"} body: { "phone_number": "79291642944", "is_urgent": true, "extra": { "foo": 42 } }

Пример

@Запрос на рассылку⁠

@Edna Pulse⁠

: POST <https://admin.chatme.ai/api/notification/42282::0a04b116e59032ef014d649602cc0b54/chat'> headers: {"Content-Type": "application/json"} body: { "phone_number": "79291642944", "is_urgent": true }

Пример

@Запрос на рассылку⁠

@Chat2Desk⁠

: POST <https://admin.chatme.ai/api/notification/42282::0a04b116e59032ef014d649602cc0b54/chat'> headers: {"Content-Type": "application/json", "Authorization: 3cb81e05cf1679e1af9e5d9164ab89"}

Токен авторизации берется из личного кабинета Chat2Desk⁠

body: { "phone_number": "79291642944", "is_urgent": true }

Работа слота

Работа слота начинается с момента получения

@Платформа⁠

@Запрос на рассылку⁠

из внешней системы.

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

Выполняются следующие операции в указанном порядке:

Проверка размера тела запроса:

Происходит проверка размера тела

@Запрос на рассылку⁠

В случае, если размер тела

@Запрос на рассылку⁠

превышает 100 КБ: Тело запроса заменяется на {}.

В ином случае происходит переход к следующей операции

Проверка

@Лимит на запросы на рассылку⁠

;

В случае, если

@Лимит на запросы на рассылку⁠

превышен: Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

со статусом: HTTP status: 404

В ином случае происходит переход к следующей операции

Проверка метода

@Запрос на рассылку⁠

;

В случае, если

Запрос на рассылку⁠

не с POST-методом: Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

со статусом: HTTP status: 405

В ином случае происходит переход к следующей операции

Проверка заголовка content-type: application/json;

В случае, если в

@Запрос на рассылку⁠

нет заголовка content-type: application/json Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

со статусом: HTTP status: 400

В ином случае происходит переход к следующей операции

Валидация корректности JSON;

В случае, если обнаружен невалидный JSON в теле

@Запрос на рассылку⁠

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

@Запрос на рассылку⁠

со статусом: HTTP status: 400

В ином случае происходит переход к следующей операции

Поиск идентификатора собеседника;

В случае, если идентификатор

@Собеседник⁠

а не был найден или он невалидный Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

со статусом: HTTP status: 405

В ином случае происходит переход к следующей операции

Поиск

@Слот⁠

@Notification⁠

;

В случае, если не найден обученный

@Агент⁠

со

@Слот⁠

ом

@Notification⁠

с указанным в запросе вебухом Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

: HTTP status: 404 Not Found BODY: “status”: “Notification not found”

В ином случае происходит переход к следующей операции

Поиск активного

@Канал Агента⁠

;

В случае, если

@Канал Агента⁠

данного слота Notification удален\неактивен Прекращается выполнение обработки запроса. Отправка ответа на

@Запрос на рассылку⁠

: HTTP status: 404 Not Found BODY: “status”: “There is no active channel for received event”

В ином случае происходит переход к следующей операции

Определение или создание

@Чат⁠

а;

Система находит существующий

@Чат⁠

по идентификатору

@Собеседник⁠

а (“phone_number”) или генерирует новый, если

@Чат⁠

не найден.

Поиск параметра is_urgent;

Создание

@Задача на рассылку⁠

;

создается

@Задача на рассылку⁠

с уникальным task_id, который записывается в

@Системные контекстные переменные⁠

⁠

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

@Задача на рассылку⁠

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

Ответы на запрос на рассылку⁠

Ответы на запрос на рассылку

Ответы на запрос на рассылку

Ответ, полученный на запроса на рассылку

Расшифровка ответа

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”:

⁠

@Запрос на рассылку

⁠

поставлен в очередь на выполнение

There are no rows in this table

⁠

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

Инициализация системных переменных;

Парсинг пользовательских переменных Слот Notification парсит данные из

@Запрос на рассылку⁠

@Контекстная переменная⁠

согласно настройкам на вкладке Incoming Data:

⁠

Если данные не удалось спарсить и

@Контекстная переменная⁠

существует, то ее значение не меняется;

Если данные не удалось спарсить и

@Контекстная переменная⁠

не существует, то она не создается.

Подготовка запроса в канал Слот Notification собирает запрос в

@Конечный канал⁠

из параметров на вкладке Destination и идентификатора собеседника (phone_number):

⁠

Если не удалось составить запрос, по какой-либо причине, то выполнение

@Слот⁠

а завершается с ошибкой, отправка запроса в

@Конечный канал⁠

не произойдет, и происходит переход в ветку

@Notification fail⁠

. При этом:

⁠

записывается {‘description’:’failed to build request’};

⁠

записывается ‘failed’.

Если запрос удалось составить, его тело записывается в

⁠

Отправка запроса на рассылку в канал и обработка ответов канала на запрос Слот Notification выполняет отправку запроса на рассылку в выбранный в поле Destination Channel

@Конечный канал⁠

Если

@Конечный канал⁠

принял запрос и ответил успешным ответом, то:

⁠

записывается {‘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 Fail происходит в случае возникновения любых проблем, относящихся к данной конкретной задаче на рассылку, кроме отсутствия аккаунта на данном идентификаторе

@Собеседник⁠

а. В случае такой ошибки:

⁠

записывается {‘description’:’channel couldn’t sent message’, ‘channel_response’: тело ответа от канала as is (объект)} Если в ответе на запуск рассылки пришел JSON-объект, то в ’channel_response’ сохраняется этот JSON-объект. Если в ответе пришел текст, то сохраняется текст. В ином случае сохраняется None

⁠

записывается ‘failed’

Переход в ветку Notification no account происходит в случае отсутствия аккаунта на данном идентификаторе

@Собеседник⁠

а (в случае WhatsApp — номере телефона). При этом:

⁠

записывается {‘description’:’no account on <номер телефона\ключевой идентификатор собеседника>’, ‘channel_response’: тело ответа от канала as is (объект)} (если application/json = объект, если text = str; в иных cлучаях записывается null).

⁠

записывается ‘no_account’;

Переход в ветку Notification Success происходит при получении

@Технический статус рассылки⁠

— статусы отправки, доставки и прочтения сообщения

@Собеседник⁠

ом в мессенджере (’sent’, ‘delivered’, ‘read’), или

@Сообщение собеседника⁠

В случае если переход в

@Notification success⁠

произошел из-за получения

@Технический статус рассылки⁠

⁠

записывается {‘description’:’success’,‘channel_response’: тело ответа от канала (объект)} (если application/json = объект, если text = str; в иных cлучаях записывается null).

Ожидание остальных

@Технический статус рассылки⁠

прекращается, ожидаются только

@Сообщение собеседника⁠

;

⁠

записывается ‘delivered’;

В случае если переход в

@Notification success⁠

произошел из-за получения

@Сообщение собеседника⁠

(т.е.