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

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

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