СЛОТЫ

icon picker
Рассылки и уведомления | Слот Incoming Request

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

@Слот
Incoming Request — позволяет
@Бот
у писать “первым номером” в
@Чат
при закрытых
@Диалог
ах. Наличие
@Слот
а Incoming Request дает возможность внешней системе активировать
@Агент
а в определенном
@Чат
е путем отправки http-запроса (POST или GET) на его вебхук, например, чтобы послать уведомление
@Собеседник
у о статусе его заказа. После получения
@Входящий запрос
@Агент
начинает
@Ветка сценария
, следующую за
@Слот
ом Incoming Request.
image.png

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

@Слот
Incoming Request можно создать только после слота
@Start
при наличии обычной ветки обработки входящих через
@Канал Агента
сообщений.
image.png
Разрешен только один
@Слот
Incoming Request в
@Сценарий
.

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

image.png
Name*название слота, которое будет отображено в
@Дерево сценария
. Максимальная длина значения поля — 40 символов.
Webhook* — адрес
@Вебхук слота Incoming Request
.
Поле пустое до момента сохранения
@Слот
а;
Поле недоступно для редактирования, но его содержимое доступно для копирования в буфер;
Адрес вебхука доступен в
@Системные контекстные переменные
.
Вебхук начинает работать после обучения
@Агент
а.
Массив пар Context key Request key для парсинга данных из параметров
@Входящий запрос
в
@Пользовательские контекстные переменные
для последующего использования их
@Сценарий
. Подробнее о парсинге: .
Context key — название
@Пользовательские контекстные переменные
, в которую будет записано значение.
Request key — ключ из параметров
@Входящий запрос
,
@Выражение
или
@Выражение с управляющей конструкцией
, значение которого будет записано в Context key. Подробнее:
Обрезка пробелов: по нажатию кнопки CREATE (при создании слота) или SAVE (при редактировании слота) обрезаются пробелы и переносы строк в начале и в конце поля Request key.

Вебхук слота Incoming Request

@Вебхук слота Incoming Request
генерируется только после сохранения
@Слот
а.
@Вебхук слота Incoming Request
становится доступен в окне редактирования
@Слот
а при его открытии после сохранения.
image.png
Значение поля WEBHOOK представляет с собой url адрес (ссылку), который необходимо скопировать и передать внешней системе для отправки
@Входящий запрос
, пример https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4
@Вебхук слота Incoming Request
по ссылке становится активен после сохранения
@Сценарий
, но отвечает ошибкой на все запросы до момента
@Обучение
@Агент
а.
Адрес активного
@Вебхук слота Incoming Request
доступен в
@Контекст Чата
в
@Контекстная переменная
и выгружается в .
В адрес
@Вебхук слота Incoming Request
можно подставлять query_params, например
и is_urgent (парсинг других параметров из URL пока не поддерживается) ​например, если предполагается отправка GET-запросов из внешней систему на
@Вебхук слота Incoming Request
@Агент
а, или если по какой-то причине в теле POST-запроса нельзя указать эти ключи (см. раздел )
@Вебхук слота Incoming Request
можно перегенерировать при помощи кнопки GENERATE NEW WEBHOOK, он будет отвечать после сохранения
@Слот
а (ошибкой), но обрабатывать запросы начнет после переобучения
@Агент
а.
Примечание: При этом от момента сохранения
@Слот
а до момента переобучения
@Агент
а будут работать оба
@Вебхук слота Incoming Request
: старый продолжит принимать и обрабатывать запросы в
@Обученная модель агента
, новый — будет отвечать ошибкой на запросы. После переобучения
@Агент
а старый
@Вебхук слота Incoming Request
будет удален и перестанет отвечать, а новый начнет принимать и обрабатывать запросы
@Вебхук слота Incoming Request
не выгружается в файл-конфиг при экспорте
@Агент
а, при импорте конфига генерируется новый
@Вебхук слота Incoming Request
для созданного импортом
@Агент
а.
При замене
@Сценарий
@Агент
а конфигом с
@Incoming Request
:
Если в
@Сценарий
@Агент
а до замены уже присутствовал
@Слот
@Incoming Request
, адрес
@Вебхук слота Incoming Request
в новом
@Сценарий
останется таким же, как до замены.
Если в
@Сценарий
@Агент
а до замены не было
@Слот
а
@Incoming Request
, будет сгенерирован новый адрес
@Вебхук слота Incoming Request
для этого
@Слот
а.

Использование синтаксиса в Слоте Incoming Request

В
@Слот
е допустимо использование
@Выражение
и
@Выражение с управляющей конструкцией
в поле Request key. Подробнее: .
Результат вычисления шаблона будет сохранен в
@Контекст Чата
по аналогии со слотом
@Memory
.
ВАЖНО: для парсинга полей is_urgent / chat_id допускается использование только
@Выражение
. Использование
@Выражение с управляющей конструкцией
не допускаются.
ВАЖНО: при парсинге тела запроса “переменные”, указанные в поле Request key, не являются
@Контекстная переменная
, а являются обращениями к объектам body, headers, query — частям
@Входящий запрос
— и их свойствам. Подробнее:

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

@Входящий запрос
представляет собой HTTPS-запрос, отправляемый на
@Вебхук слота Incoming Request
с целью активации
@Ветка сценария
, следующей после
@Incoming Request
в определенном
@Чат
е данного
@Агент
а. Идентификатор целевого
@Чат
а —
— обязательно должен быть указан в теле запроса либо в параметрах url (query params).

Формат входящего запроса

Протокол: HTTPS
Метод запроса: POST \ GET
Тело POST запроса: JSON
Авторизация: токен авторизации является частью URL
@Вебхук слота Incoming Request
Атрибут запроса chat_id*:
Атрибут chat_id содержит идентификатор
@Чат
а (значение переменной
), в котором необходимо начать
@Ветка сценария
@Слот
а
@Incoming Request
.
Обязательный атрибут. Расположение: ключ "chat_id" в теле
@Входящий запрос
(body) или параметр chat_id в параметрах url
@Входящий запрос
(query params)
Порядок поиска chat_id и приоритет выбора:
Для POST-запроса:
Приоритет 1 — по указанному пути в теле запроса: Пользователь может определить путь к ключу "chat_id" в настройках в
@Слот
е
@Incoming Request
— это приоритетный путь для поиска ​
image.png
Приоритет 2 — в параметре запроса: Если по указанному пользователем пути ключ "chat_id" не найден в теле (body) входящего POST-запроса, система будет искать параметр chat_id в query params в url адресе запроса - пример https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea
Приоритет 3 - на первом уровне тела запроса: Если ключ "chat_id" не найден по указанному пользователем пути в теле запроса, и не найден параметр chat_id в query params, происходит поиск ключа “chat_id” на первом уровне тела запроса
Для GET-запроса: поиск происходит только в параметрах URL
@Входящий запрос
Атрибут запроса is_urgent:
Атрибут is_urgent содержит признак срочности запроса. Необязательный атрибут, если не указан, принимает значение false
Допустимы значения:
true — признак входящего запроса - выполняется незамедлительно и прерывает
@Активный диалог
false — признак входящего запроса - выполняется после закрытия
@Диалог
а
Порядок поиска is_urgent и приоритет выбора:
Для POST-запроса:
Приоритет 1 — по указанному пути в теле запроса: Пользователь может определить путь к ключу "is_urgent" в настройках в слоте Incoming Request - это приоритетный путь для поиска
image.png
Приоритет 2 — в параметре запроса: Если по указанному пользователем пути ключ "is_urgent" не найден в теле (body) входящего POST запроса, система будет искать параметр is_urgent в query params в url адресе запроса - пример: https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?is_urgent=true
Приоритет 3 — на первом уровене тела запроса: Если ключ "is_urgent" не найден по указанному пользователем пути в теле запроса, и не найден параметр is_urgent в query params, происходит поиск ключа “is_urgent” на первом уровне тела запроса
Если атрибут is_urgent не найден вышеуказанными методами, он принимает значение false
Для GET-запроса: поиск происходит только в параметрах URL
@Входящий запрос
Важно:
* расположения chat_id и is_urgent могут совпадать (прим. https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea&is_urgent=true)
* расположения chat_id и is_urgent могут отличаться, например, is_urgent может быть передан в параметрах запроса, а путь к ключу “chat_id” (в теле запроса) может быть указан пользователем в настройках парсинга
Пользовательские данные во входящем запросе:
переменные, массивы и объекты - пары ключ-значение в теле запроса для передачи в контекстные переменные при в слоте Incoming Request. Необязательные поля.
Могут быть переданы только в POST запросе.

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

Параметры входящего запроса:
При поступлении входящего запроса возможно обращаться к его частям (заголовкам, телу, параметрам) как к объектам для парсинга содержимого этих частей.
Тело запроса
body — объект тела запроса. Формат: JSON.
Обращение к вложенным в тело (JSON) ключам соответственно body.<key>
image.png
Важно: Если размер тела
@Входящий запрос
превышает 10 КБ, то оно заменяется на пустое {}. (См.
@Лимит на размер получаемого тела в Incoming Request
)
Заголовки запроса
headers — объект, содержащий заголовки запроса. Обращение к заголовкам соответственно headers.<header name>
image.png
Параметры (query parameter) запроса
query — объект, содержащий query параметры из URL (после знака ? в URL)
Обращение к параметрам соответственно query.<parameter name>
image.png
Важно: объекты body, headers , query не сохраняются в
@Контекст Чата
, но доступны для парсинга в момент работы данного
@Слот
а
@Incoming Request
. При этом body, headers и query возможно целиком спарсить в
@Контекстная переменная
.
image.png
@Контекстная переменная
в поле Context key можно задавать имена, совпадающие с названиями частей запроса, например, парсить весь объект body в переменную body. ​
image.png
Особенности парсинга:
Возможен парсинг объектов, массивов и переменных любой вложенности;
Пример: {{ body.content.par1 }} — обращение к переменной par1, вложенной в content и body
Имена переменных и пути к значениям регистрозависимы;
Пример: {{ body.name }} и {{ body.Name }} — обращения к разным ключам (name и Name) в теле запроса.
Через точку (.) происходит обращение к ключам на нижних уровнях многоуровневого объекта\JSON;
Пример: {{ body.content.par1 }}
Обращение к соответствующему номеру элемента массива происходит с помощью чисел. Нумерация элементов массива начинается с нуля, поэтому обращение к первому элементу массива обозначается как 0.
Пример: {{ body.array.0.par1 }} — обращение к первому элементу массива array
Обращение к ключу объекта, если его имя совпадает с именем происходит через квадратные скобки и кавычки.
Пример: {{ data["keys"] }}

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

1) С chat_id и is_urgent в теле запроса
Ниже приведен пример входящего запроса и парсинг данных этого запроса в переменные
POST Запрос направлен на
@Вебхук слота Incoming Request
и содержит следующие query parameters: ...?bar=42&baz=aaa
Запрос содержит заголовок (header) Authorization со значением Token fjrv44344fjvr
Тело запроса:
{
"chat_id": "e2022b50f626d13b8fc12ee0ea2d7582dca09424",
"is_urgent": true,
"par": "value",
"content":
{
"par1": "value1"
},
"array": [
{
"par2": "value2"
},
{
"par3": "value3"
}
]
}
Парсинг данного запроса в переменные:
В примере, в случае с body и query в переменные записываются отдельные ключи и параметры, но возможен и парсинг объекта целиком, как это в примере ниже с headers.
image.png
В var1 будет записано значение value
В var2 будет записано значение value1
В var3 будет записано значение value2
В var4 будет записано значение(объект) {'Authorization': 'Token fjrv44344fjvr'}
В var5 будет записано значение 42

2) С chat_id и is_urgent в параметрах URL запроса
URL: https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea&is_urgent=false
BODY:
{
"message": "Новая акция для постоянных клиентов",
"name": "Игорь"
}
В данном примере входящий запрос адресован в
@Чат
с CHAT_ID = 1b7637033b3fc4c15a95bfad048ceb89244f6dea.
Этот запрос будет поставлен в очередь и будет выполнен после
@Закрытие диалога
, т.к. он несрочный (is_urgent = false).
Парсинг данного запроса в переменные:
Значения из ключей message и name будут спарсены в
@Пользовательские контекстные переменные
, если
@Слот
будет сконфигурирован, как указано на скриншоте ниже ​
image.png

Работа слота Incoming Request

Работа слота начинается с момента получения
@Платформа
@Входящий запрос
от внешнего сервиса на
@Вебхук слота Incoming Request
.
После получения запроса выполняются следующие операции в указанном порядке:
Проверка лимитов на запросы к API: для каждой
@Компания
установлен
@Лимит на входящие запросы
— 20
@Входящий запрос
в секунду в сумме на все вебхуки всех
@Слот
ов
@Incoming Request
во всех
@Агент
ах
@Компания
.
В случае, если лимит превышен: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 429
В ином случае происходит переход к следующей операции.
Проверка метода: Происходит проверка метода POST/GET в
@Входящий запрос
:
В случае, если был отправлен запрос с иным методом (не POST/GET): Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 405
В ином случае происходит переход к следующей операции.
Проверка заголовка content-type: application/json: если метод запроса POST, происходит проверка наличия заголовкаcontent-type: application/json:
В случае, если в
@Входящий запрос
нет заголовка content-type: application/json: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
: со статусом: HTTP status: 400 ​BODY: ​“status”: “Unsupported content-type.”
В ином случае происходит переход к следующей операции.
Проверка размера тела
@Входящий запрос
:
В случае, если размер тела
@Входящий запрос
превышает 10 КБ, то тело заменяется на {}.
В ином случае происходит переход к следующей операции.
Валидация корректности JSON: если метод запроса POST, происходит валидация тела
@Входящий запрос
на корректный JSON:
В случае, если не удалось распарсить тело
@Входящий запрос
, т.е. невалидный JSON: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 400 ​BODY: ​{"status": "Document parse error."}
В ином случае происходит переход к следующей операции
Поиск
@Слот
а
@Incoming Request
: система ищет среди
@Обученная модель агента
@Слот
а
@Incoming Request
, на
@Вебхук слота Incoming Request
которого поступил запрос:
В случае, если среди
@Обученная модель агента
не найден
@Слот
@Incoming Request
, на
@Вебхук слота Incoming Request
которого поступил запрос: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 404 ​BODY: ​{"status": "Incoming request not found."}
В ином случае происходит переход к следующей операции.
Поиск chat_id:
Если метод запроса GET, система ищет параметр chat_id в параметрах URL
@Входящий запрос
Если метод запроса POST, система ищет параметр chat_id в теле
@Входящий запрос
затем, если не найден, то в параметрах URL
@Входящий запрос
.
В случае, если параметр chat_id не найден: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 400 ​BODY: ​{"status": "No chat id passed."}
В ином случае происходит переход к следующей операции.
Поиск is_urgent:
Если метод запроса GET, система ищет параметр is_urgent в параметрах URL
@Входящий запрос
Если метод запроса POST, система ищет параметр is_urgent в теле
@Входящий запрос
затем, если не найден, то в параметрах URL
@Входящий запрос
.
В случае, если is_urgent нет или он есть, но не удалось прочитать корректную булеву, система считает его как false.
Поиск
@Чат
а по chat_id.
В случае, если
@Чат
по chat_id, полученному в теле или параметрах запроса (
), не найден: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 400 ​BODY: ​{"status": "Chat not found."}
В случае, если
@Чат
с идентификатором из атрибута chat_id найден, но
@Канал Агента
данного
@Чат
а удален: Прекращается выполнение обработки запроса. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 400 ​BODY: ​{"status": "There is no active channel for received event."}
В ином случае происходит переход к следующей операции.
Запуск сценария.
Если is_urgent == true, (
) то запускается
@Ветка сценария
@Incoming Request
. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 200 OK ​BODY: ​“status”: “Accepted for execution”
Если is_urgent == false, и в
@Чат
е нет
@Активный диалог
, то запускается
@Ветка сценария
@Incoming Request
. Отправка ответа на
@Входящий запрос
со статусом: HTTP status: 200 OK ​BODY: ​“status”: “Accepted for execution”
Если is_urgent == false и в
@Чат
е есть
@Активный диалог
, то запрос попадает в
@Очередь входящих запросов
и сработает в
@Неактивный чат
, когда подойдет его очередь.

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.