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

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

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

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

1. Слот Incoming Request можно создать только после слота Start при наличии обычной ветки обработки входящих через Канал Проекта сообщений.

2. 

3. Разрешен только один Слот Incoming Request в Сценарий агента.

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

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

2. Webhook* — адрес Вебхук слота Incoming Request.

3. 1. Поле пустое до момента сохранения Слота;

   2. Поле недоступно для редактирования, но его содержимое доступно для копирования в буфер;

   3. Адрес вебхука доступен в Системная контекстная переменная IR_url.

   4. Вебхук начинает работать после обучения Агента.

4. Массив пар Context key — Request key для парсинга данных из параметров Входящий запрос в Пользовательские контекстные переменные для последующего использования их Сценарий агента. Подробнее о парсинге: Параметры входящего запроса и их парсинг в контекстные переменные.

5. 1. Context key — название Пользовательские контекстные переменные, в которую будет записано значение.

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

   3. 1. Обрезка пробелов: по нажатию кнопки CREATE (при создании слота) или SAVE (при редактировании слота) обрезаются пробелы и переносы строк в начале и в конце поля Request key.

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

1. Вебхук слота Incoming Request генерируется только после сохранения Слота.

2. Вебхук слота Incoming Request становится доступен в окне редактирования Слота при его открытии после сохранения.
3. Значение поля WEBHOOK представляет с собой url адрес (ссылку), который необходимо скопировать и передать внешней системе для отправки Входящий запрос, пример https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4

4. Вебхук слота Incoming Request по ссылке становится активен после сохранения Сценарий агента, но отвечает ошибкой на все запросы до момента Обучение Агента.

5. Адрес активного Вебхук слота Incoming Request доступен в Контекст Чата в Контекстная переменная IR_url и выгружается в Выгрузка контекстных переменных чатов.

6. В адрес Вебхук слота Incoming Request можно подставлять query_params, например chat_id и is_urgent (парсинг других параметров из URL пока не поддерживается) https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=cvnj3Jb948Bb93b283b428883fhf&is_urgent=trueнапример, если предполагается отправка GET-запросов из внешней систему на Вебхук слота Incoming Request Агента, или если по какой-то причине в теле POST-запроса нельзя указать эти ключи (см. раздел Работа слота)

7. Вебхук слота Incoming Request можно перегенерировать при помощи кнопки GENERATE NEW WEBHOOK, он будет отвечать после сохранения Слота (ошибкой), но обрабатывать запросы начнет после переобучения Агента.

8. Примечание: При этом от момента сохранения Слота до момента переобучения Агента будут работать оба Вебхук слота Incoming Request: старый продолжит принимать и обрабатывать запросы в Обученная модель агента, новый — будет отвечать ошибкой на запросы. После переобучения Агента старый Вебхук слота Incoming Request будет удален и перестанет отвечать, а новый начнет принимать и обрабатывать запросы

9. Вебхук слота Incoming Request не выгружается в файл-конфиг при экспорте Агента, при импорте конфига генерируется новый Вебхук слота Incoming Request для созданного импортом Агента.

10. При замене Сценарий агента Агента конфигом с Incoming Request:

11. 1. Если в Сценарий агента Агента до замены уже присутствовал Слот Incoming Request, адрес Вебхук слота Incoming Request в новом Сценарий агента останется таким же, как до замены.

    2. Если в Сценарий агента Агента до замены не было Слота Incoming Request, будет сгенерирован новый адрес Вебхук слота Incoming Request для этого Слота.

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

В Слоте допустимо использование Выражение и Выражение с управляющей конструкцией в поле Request key. Подробнее: Синтаксис. Результат вычисления шаблона будет сохранен в Контекст Чата по аналогии со слотом Memory.

ВАЖНО: для парсинга полей is_urgent / chat_id допускается использование только Выражение. Использование Выражение с управляющей конструкцией не допускаются.

ВАЖНО: при парсинге тела запроса “переменные”, указанные в поле Request key, не являются Контекстная переменная, а являются обращениями к объектам body, headers, query — частям Входящий запрос — и их свойствам.

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

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

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

1. Протокол: HTTPS

2. Метод запроса: POST \ GET

3. 1. Тело POST запроса: JSON

4. Авторизация: токен авторизации является частью URL Вебхук слота Incoming Request

• Атрибут запроса chat_id*:

• 1. Атрибут chat_id содержит идентификатор Чата (значение переменной chat_id), в котором необходимо начать Ветка сценария Слота Incoming Request.

  2. Обязательный атрибут. Расположение: ключ "chat_id" в теле Входящий запрос (body) или параметр chat_id в параметрах url Входящий запрос (query params)

  3. Порядок поиска chat_id и приоритет выбора:

  4. 1. Для POST-запроса:

     2. 1. Приоритет 1 — по указанному пути в теле запроса: Пользователь может определить путь к ключу "chat_id" в настройках парсинга в Слоте Incoming Request — это приоритетный путь для поиска
        2. Приоритет 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. Приоритет 3 - на первом уровне тела запроса: Если ключ "chat_id" не найден по указанному пользователем пути в теле запроса, и не найден параметр chat_id в query params, происходит поиск ключа “chat_id” на первом уровне тела запроса

     3. Для GET-запроса: поиск происходит только в параметрах URL Входящий запрос

• Атрибут запроса is_urgent:

• 1. Атрибут is_urgent содержит признак срочности запроса. Необязательный атрибут, если не указан, принимает значение false

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

  3. 1. true — признак срочного входящего запроса - выполняется незамедлительно и прерывает Активный диалог

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

  4. Порядок поиска is_urgent и приоритет выбора:

  5. 1. Для POST-запроса:

     2. 1. Приоритет 1 — по указанному пути в теле запроса: Пользователь может определить путь к ключу "is_urgent" в настройках парсинга в слоте Incoming Request - это приоритетный путь для поиска
        2. Приоритет 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. Приоритет 3 — на первом уровне тела запроса: Если ключ "is_urgent" не найден по указанному пользователем пути в теле запроса, и не найден параметр is_urgent в query params, происходит поиск ключа “is_urgent” на первом уровне тела запроса

        4. Если атрибут is_urgent не найден вышеуказанными методами, он принимает значение false

     3. Для 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” (в теле запроса) может быть указан пользователем в настройках парсинга

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

• 1. переменные, массивы и объекты - пары ключ-значение в теле запроса для передачи в контекстные переменные при парсинге в слоте Incoming Request. Необязательные поля.

  2. Могут быть переданы только в POST запросе.

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

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

1. Тело запроса

2. body — объект тела запроса. Формат: JSON.Обращение к вложенным в тело (JSON) ключам соответственно body.<key>

1. Важно: Если размер тела Входящий запрос превышает 10 КБ, то оно заменяется на пустое {}. (См. Лимит на размер получаемого тела в Incoming Request)

2. Заголовки запроса

3. headers — объект, содержащий заголовки запроса. Обращение к заголовкам соответственно headers.<header name>
4. Параметры (query parameter) запроса

5. query — объект, содержащий query параметры из URL (после знака ? в URL)Обращение к параметрам соответственно query.<parameter name>

Важно: объекты body, headers , query не сохраняются в Контекст Чата, но доступны для парсинга в момент работы данного Слота . При этом body, headers и query возможно целиком спарсить в Контекстная переменная.

Контекстная переменная в поле Context key можно задавать имена, совпадающие с названиями частей запроса, например, парсить весь объект body в переменную body.

Особенности парсинга:

• Возможен парсинг объектов, массивов и переменных любой вложенности;

• Пример: {{ 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.

В 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=falseBODY:

{    "message": "Новая акция для постоянных клиентов",    "name": "Игорь"}

В данном примере входящий запрос адресован в Чат с CHAT_ID = 1b7637033b3fc4c15a95bfad048ceb89244f6dea.Этот запрос будет поставлен в очередь и будет выполнен после Закрытие диалога, т.к. он несрочный (is_urgent = false).Парсинг данного запроса в переменные:Значения из ключей message и name будут спарсены в Пользовательские контекстные переменные, если Слот будет сконфигурирован, как указано на скриншоте ниже

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

Работа слота начинается с момента получения Платформа Входящий запрос от внешнего сервиса на Вебхук слота Incoming Request.После получения запроса выполняются следующие операции в указанном порядке:

1. Проверка лимитов на запросы к API: для каждой Компания установлен Лимит на входящие запросы — 20 Входящий запрос в секунду в сумме на все вебхуки всех Слотов Incoming Request во всех Агентах Компания.

2. 1. В случае, если лимит превышен: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 429

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

3. Проверка метода: Происходит проверка метода POST/GET в Входящий запрос:

4. 1. В случае, если был отправлен запрос с иным методом (не POST/GET): Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 405

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

5. Проверка заголовка content-type: application/json: если метод запроса POST, происходит проверка наличия заголовкаcontent-type: application/json:

6. 1. В случае, если в Входящий запрос нет заголовка content-type: application/json: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос: со статусом: HTTP status: 400 BODY: “status”: “Unsupported content-type.”

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

7. Проверка размера тела Входящий запрос:

8. 1. В случае, если размер тела Входящий запрос превышает 10 КБ, то тело заменяется на {}.

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

9. Валидация корректности JSON: если метод запроса POST, происходит валидация тела Входящий запрос на корректный JSON:

10. 1. В случае, если не удалось распарсить тело Входящий запрос, т.е. невалидный JSON: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 400 BODY: {"status": "Document parse error."}

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

11. Поиск Слота Incoming Request: система ищет среди Обученная модель агента Слот Incoming Request, на Вебхук слота Incoming Request которого поступил запрос:

12. 1. В случае, если среди Обученная модель агента не найден Слот Incoming Request, на Вебхук слота Incoming Request которого поступил запрос: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 404 BODY: {"status": "Incoming request not found."}

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

13. Поиск chat_id:

14. 1. Если метод запроса GET, система ищет параметр chat_id в параметрах URL Входящий запрос

    2. Если метод запроса POST, система ищет параметр chat_id в теле Входящий запрос затем, если не найден, то в параметрах URL Входящий запрос.

    3. В случае, если параметр chat_id не найден: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 400 BODY: {"status": "No chat id passed."}

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

15. Поиск is_urgent:

16. 1. Если метод запроса GET, система ищет параметр is_urgent в параметрах URL Входящий запрос

    2. Если метод запроса POST, система ищет параметр is_urgent в теле Входящий запрос затем, если не найден, то в параметрах URL Входящий запрос.

    3. В случае, если is_urgent нет или он есть, но не удалось прочитать корректную булеву, система считает его как false.

17. Поиск Чата по chat_id.

18. 1. В случае, если Чат по chat_id, полученному в теле или параметрах запроса (п.6), не найден: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 400 BODY: {"status": "Chat not found."}

    2. В случае, если Чат с идентификатором из атрибута chat_id найден, но Канал Проекта данного Чата удален: Прекращается выполнение обработки запроса. Отправка ответа на Входящий запрос со статусом: HTTP status: 400 BODY: {"status": "There is no active channel for received event."}

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

19. Запуск сценария.

20. 1. Если is_urgent == true, (п.7) то запускается Ветка сценария Incoming Request. Отправка ответа на Входящий запрос со статусом: HTTP status: 200 OK BODY: “status”: “Accepted for execution”

    2. Если is_urgent == false, и в Чате нет Активный диалог, то запускается Ветка сценария Incoming Request. Отправка ответа на Входящий запрос со статусом: HTTP status: 200 OK BODY: “status”: “Accepted for execution”

    3. Если is_urgent == false и в Чате есть Активный диалог, то запрос попадает в Очередь входящих запросов и сработает в Неактивный чат, когда подойдет его очередь.