Рассылки и уведомления | Слот Incoming Request
Incoming Request (Входящий запрос) позволяет Агенту первым писать Собеседнику в уже существующий Чат при закрытых диалогах. Наличие слота Incoming Request дает возможность внешней системе активировать Агента в определенном Чате путем отправки http-запроса (POST или GET) на его вебхук (указанный в слоте), например, чтобы послать уведомление Собеседнику о статусе его заказа. После получения Входящего запроса Агент начинает ветку Сценария, следующую за слотом Incoming Request.
- 1.Слот Incoming Request можно создать только после слота Start при наличии обычной ветки обработки входящих через Канал Агента сообщений.
- 2.Разрешен только один слот Incoming Request в Сценарии.
- 1.Name — название слота, которое будет отображено в Дереве сценария. Максимальная длина значения поля — 40 символов.
- 2.Webhook — адрес вебхука данного слота Incoming Request:
- 1.При создании слота поле скрыто и начинает отображаться только после сохранения слота;
- 2.Содержимое поля нельзя редактировать, но можно скопировать;
- 3.Адрес вебхука содержится в системной контекстной переменной IR_url
- 4.Вебхук начинает работать после обучения Агента.
- 3.Массив пар Context key — Request key для парсинга данных из тела Входящего запроса в Пользовательские контекстные переменные для последующего использования их Сценарии Агента:
- 1.Context key — название переменной, в которую будет записано значение; Важно: при указании CONTEXT KEY обратите внимание на требования к именам Пользовательских контекстных переменных.
- 2.Request key — ключ из тела Входящего запроса, значение которого будет записано в Context 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"
}
]
}
Парсинг:
- Адрес вебхука слота Incoming Request генерируется только после сохранения Слота;
- Значение поля WEBHOOK представляет с собой URL-адрес (ссылку), который необходимо скопировать и передать внешней системе для отправки Входящего запроса;
- Вебхук по ссылке становится активен только после Обучения Агента;
- Адрес активного вебхука доступен в Контексте Чата в переменой IR_url и выгружается в отчете: Выгрузка контекстных переменных;
- Вебхук можно перегенерировать при помощи кнопки GENERATE NEW WEBHOOK, он начнет обрабатывать запросы после переобучения Агента;
- Адрес вебхука не выгружается в файл-конфиг при экспорте Агента: при импорте конфига генерируется новый вебхук для созданного импортом Агента.
В Слоте допустимо использование Выражений и Управляющих конструкций в поле Value. Результат вычисления шаблона будет сохранен в Контекст Чата по аналогии со слотом Memory. Подробнее: Переход на новый синтаксис
ВАЖНО: для парсинга полей
is_urgent
/ chat_id
допускается использование только Выражений. Использ ование Управляющих конструкций не допускается. ВАЖНО: при парсинге тела запроса все используемые в шаблоне переменные ищутся в теле запроса, а не в Контексте Чата. Обращение к телу запроса происходит через переменную
body
по аналогии с обращением к телу ответа во Внешних запросах.

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 и приоритет выбора:
- 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” на первом уровне тела запроса.
- 5.Атрибут запроса is_urgent:
- 1.Атрибут is_urgent содержит признак срочности запроса. Необязательный атрибут, если не указан, принимает значение
false
; - 2.Допустимы значения:
- 1.true — признак срочного входящего запроса — выполняется незамедлительно и прерывает Активный диалог;
- 2.false — признак несрочного входящего запроса — выполняется после закрытия Диалога.
- 3.Порядок поиска is_urgent и приоритет выбора:
- 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.
Важно:- 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.
Ветка сценария слота Incoming Request для Чата с данным CHAT_ID выполняется незамедлительно после получения и обработки данного входящего запроса, выполняемый до этого сценарий прерывается. Таким образом может быть прервано общение (сценарий) в текущем активном Диалоге, вне зависимости от того, кем он был инициирован: Собеседником, предыдущим Входящим запросом или специальным слотом, например, Timer.
Входящий запрос становится в очередь на выполнение с другими несрочными входящими запросами. Такие запросы выполняются по очереди после завершения активного Диалога.
В один Чат внешней системой может быть отправлено несколько Входящих запросов подряд, несрочные запросы не прерывают активный Диалог, они становятся в очередь на выполнение в порядке их поступления на вебхук в Платформу. Очередь может состоять из одного или нескольких ожидающих выполнения несрочных входящих запросов.
Выполнение нескольких несрочных запросов в один чат может занять продолжительное время:
Для Чата, у которого есть активный Диалог 1 и невыполненные входящие запросы в очереди, Платформа ожидает закрытия Диалога 1, затем выполняет перый в очереди несрочный входящий запрос. Выполненный входящий запрос открывает в Чате новый диалог — Диалог 2 — начинается Ветка сценария слота Incoming Request, соответственно, следующий входящий запрос из очереди ждет закрытия уже Диалога 2. И т.д пока не будут выполнены все запросы в очереди.
Last modified 1mo ago