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

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

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

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

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

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

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

    1. При сохранении Слота проверяется значение в поле:

  2. Webhook — адрес вебхука данного слота Incoming Request:

    1. При создании слота поле скрыто и начинает отображаться только после сохранения слота;

    2. Содержимое поля нельзя редактировать, но можно скопировать;

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

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

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

    1. Context key — название переменной, в которую будет записано значение; Важно: при указании CONTEXT KEY обратите внимание на требования к именам Пользовательских контекстных переменных.

      1. При сохранении Слота проверяется значение в поле:

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

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

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

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

body — объект тела запроса. Формат: JSON

headers — объект в который записываются HTTP заголовки запроса

query — объект query переменных из URL (после знака ? в URL)

Важно: объекты body, headers , query не сохраняются в Контекст Чата, но доступны для парсинга

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

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

  • Имена переменных и пути к значениям регистрозависимы

  • Текстом прописываются названия соответствующих ключей из тела запроса;

  • Через точку (.) происходит обращение к ключам на нижних уровнях многоуровневого JSON;

  • Обращение к соответствующему номеру элемента массива происходит с помощью чисел. Нумерация элементов массива начинается с нуля, поэтому обращение к первому элементу массива обозначается как 0.

Пример:

  • Заголовок: foo: bar

    • {{ headers }} == {"foo": "bar"}

  • URL ...?bar=42&baz=aaa

    • {{ query }} == {"bar": 42, "baz": "aaa"}

  • Тело:

{
    "chat_id": "e2022b50f626d13b8fc12ee0ea2d7582dca09424",
    "is_urgent": true,
    "par": "value",
    "content":
            {       
            "par1": "value1"
            },
    "array": [
            {            
            "par2": "value2"        
            },        
            {            
            "par3": "value3"        
            }    
    ]
}

Парсинг:

body. — парсинг из тела запроса;

headers. — парсинг из заголовков запроса;

query. — парсинг из Query parameters запроса.

Объекты body, headers и query возможно целиком спарсить в Контекстные переменные.

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

  • Значение поля WEBHOOK представляет с собой URL-адрес (ссылку), который необходимо скопировать и передать внешней системе для отправки Входящего запроса;

  • Вебхук по ссылке становится активен только после Обучения Агента;

  • Адрес активного вебхука доступен в Контексте Чата в переменой IR_url и выгружается в отчете: Выгрузка контекстных переменных;

  • Вебхук можно перегенерировать при помощи кнопки GENERATE NEW WEBHOOK, он начнет обрабатывать запросы после переобучения Агента;

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

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

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

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

ВАЖНО: при парсинге тела запроса все используемые в шаблоне переменные ищутся в теле запроса, а не в Контексте Чата. Обращение к телу запроса происходит через переменную body по аналогии с обращением к телу ответа во Внешних запросах.

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

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

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

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

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

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

    • Тело POST запроса: JSON

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

  4. Атрибут запроса chat_id:

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

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

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

      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” на первом уровне тела запроса.

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

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

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

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

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

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

      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. Важно:

        1. расположения chat_id и is_urgent могут совпадать (пример: https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea&is_urgent=true)

        2. расположения chat_id и is_urgent могут отличаться, например, is_urgent может быть передан в параметрах запроса, а путь к ключу “chat_id” (в теле запроса) может быть указан пользователем в настройках парсинга.

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

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

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

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

  1. С chat_id и is_urgent в теле запроса

    • URL: https://admin.chatme.ai/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4

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

    • В данном примере входящий запрос адресован в Чат с CHAT_ID = c86821cecf80feadf1e07193b0727335af2f5c1f.

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

  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 будут спарсены в Пользовательские контекстные переменные, если в слоте будет сконфигурирован соответствующий парсинг.

Формат ответа платформы на входящий запрос

  • Лимиты на запросы к API

Для каждой компании установлен лимит на обработку запросов к API — 20 Входящих запросов в секунду в сумме на все вебхуки всех слотов Incoming Request во всех Агентах компании. При превышении Платформа ответит (http response) кодом 429.

  • Ответ на Входящий запрос

Платформа отвечает на запросы следующими ответами:

  • HTTP status: 200 OK BODY: “status”: “Accepted for execution” - запрос получен, найден Чат с идентификатором из атрибута chat_id, запрос отправлен в обработку

  • HTTP status: 404 Not Found BODY: “status”: “Chat not found”- запрос получен, но не найден Чат с идентификатором из атрибута chat_id

  • HTTP status: 404 Not Found BODY: “status”: “There is no active channel for received event”- запрос получен, Чат с идентификатором из атрибута chat_id найден, но Канал Агента данного чата удален

  • HTTP status: 400 BODY: “status”: “Unsupported content-type.”- запрос получен, в нем нет заголовка content-type: application/json

  • HTTP status: 400 BODY: “status”: “No chat id passed.”- запрос получен, атрибута chat_id не найдено

Выполнение входящих запросов в сценарии

  • Один Входящий запрос может быть выполнен только в одном Чате — с указанным chat_id в атрибуте chat_id.

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

  • При выполнении входящего запроса происходит парсинг данных из тела запроса в Контекстные переменные согласно настройкам слота Incoming Request.

Выполнение срочных (is_urgent=true) входящих запросов

Ветка сценария слота Incoming Request для Чата с данным CHAT_ID выполняется незамедлительно после получения и обработки данного входящего запроса, выполняемый до этого сценарий прерывается. Таким образом может быть прервано общение (сценарий) в текущем активном Диалоге, вне зависимости от того, кем он был инициирован: Собеседником, предыдущим Входящим запросом или специальным слотом, например, Timer.

Выполнение несрочных (is_urgent=false) входящих запросов

Входящий запрос становится в очередь на выполнение с другими несрочными входящими запросами. Такие запросы выполняются по очереди после завершения активного Диалога.

Очередь входящих запросов чата

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

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

Для Чата, у которого есть активный Диалог 1 и невыполненные входящие запросы в очереди, Платформа ожидает закрытия Диалога 1, затем выполняет перый в очереди несрочный входящий запрос. Выполненный входящий запрос открывает в Чате новый диалог — Диалог 2 — начинается Ветка сценария слота Incoming Request, соответственно, следующий входящий запрос из очереди ждет закрытия уже Диалога 2. И т.д пока не будут выполнены все запросы в очереди.

PreviousНачало Сценария | Слот StartNextРассылки в WhatsApp| Слот Notification

Last updated