chatme.ai
Search
K

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

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

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

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

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

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

image.png
  1. 1.
    Name — название слота, которое будет отображено в Дереве сценария. Максимальная длина значения поля — 40 символов.
    1. 1.
      При сохранении Слота проверяется значение в поле:
      1. 1.
        если поле пустое, выводится ошибка Please enter a slot name
        image.png
      2. 2.
        если в поле более 40 символов, выводится ошибка Name must contain no more than 40 characters
        image.png
  2. 2.
    Webhook — адрес вебхука данного слота Incoming Request:
    1. 1.
      При создании слота поле скрыто и начинает отображаться только после сохранения слота;
    2. 2.
      Содержимое поля нельзя редактировать, но можно скопировать;
    3. 3.
      Адрес вебхука содержится в системной контекстной переменной IR_url
    4. 4.
      Вебхук начинает работать после обучения Агента.
  3. 3.
    Массив пар Context keyRequest key для парсинга данных из тела Входящего запроса в Пользовательские контекстные переменные для последующего использования их Сценарии Агента:
    1. 1.
      Context key — название переменной, в которую будет записано значение; Важно: при указании CONTEXT KEY обратите внимание на требования к именам Пользовательских контекстных переменных.
      1. 1.
        При сохранении Слота проверяется значение в поле:
        1. 1.
          если имя переменной не соответствует требования к именам Пользовательских контекстных переменных, выводится ошибка Invalid name
          image.png
    2. 2.
      Request key — ключ из тела Входящего запроса, значение которого будет записано в Context key.
      1. 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

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

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

  1. 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. 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. И т.д пока не будут выполнены все запросы в очереди.