Вкладка внешних запросов — External Requests
Last updated
Last updated
Вкладка EXTERNAL REQUESTS — вкладка, на которой создаются Внешний запрос для дальнейшего их использования в Агентах Компания.
В список Внешний запрос Компания можно перейти двумя способами:
перейти на вкладку Resourses (Вкладка ресурсов Компании — Resourses) и нажать кнопку External Requests;
На вкладке Внешний запрос представлен список всех Внешний запрос Компания:
Name — названия Внешний запросов;
Кнопка сортировки Внешний запросов по алфавиту;
По нажатию кнопки сортировка Внешний запросов меняется: от начала алфавита к концу и наоборот.
Method and URL — URL назначения, куда должен быть отправлен запрос и метод HTTP запроса;
In use — использование Внешний запросов в Агентах;
Напротив каждого Внешний запроса, используемого в Агентах, проставлена галочка и кнопка Clarify;
По нажатию кнопки Clarify выводятся иконки Агентов, в которых используется Внешний запрос.
Для совершения поиска по имени Внешний запроса необходимо ввести искомое значение в поле поиска.
Поиск по использованию Внешний запроса в Агентах производится с помощью фильтров In use и Not in use.
По нажатию на кнопку In use вместо фильтра Not in use выводится фильтр Agent — фильтр по Агентам.
Чтобы найти Внешний запросы, которые используются в определенных Агентах, необходимо кликнуть по необходимым Агентам в списке.
Чтобы создать Внешний запросы, необходимо:
Перейти в список Внешний запросов.
По нажатию кнопки на панели справа откроется форма создания нового Внешний запроса.
Необходимо заполнить поля на вкладках формы создания Внешний запроса.
Name* — название Внешний запрос. Максимальная длина значения поля — 1000 символов.
Description — описание Внешний запрос. Максимальная длина значения поля — 1000 символов.
Метод запроса* — HTTP метод для данного запроса. По умолчанию установлен метод GET.
GET
POST
PUT
PATCH
DELETE
HEAD
Endpoint* — адрес вебхука, на который будет отправлен данный Внешний запрос. Максимальная длина значения поля — 1000 символов.
Формат значения:
Header* — название заголовка. Максимальная длина значения поля — 1000 символов.
Value* — значение заголовка. Максимальная длина значения поля — 10000 символов.
Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
Кнопка крестика удаляет заголовок (строку).
Add new field — кнопка добавления нового заголовка.
Parameter* — название параметра. Максимальная длина значения поля — 1000 символов.
Кодировка символов не латинского алфавита: Допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса.
Важно: Параметры запроса (имена и значения) будут закодированы в любом случае при подстановке в Итоговый URL внешнего запроса, во избежание двойной кодировки на вкладке Query parameters стоит указывать параметры в незакодированном виде.
Value* — значение параметра. Максимальная длина значения поля — 10000 символов.
Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
Кодировка символов не латинского алфавита: Допускаются пробелы, спецсимволы и не латинский символы, будет произведено кодирование значение параметра при выполнении запроса.
Такой параметр будет включен в Итоговый URL внешнего запроса в виде query=%D0%B0%D0%B1%D0%B2%D0%B3%D0%B4
Важно: Параметры запроса (имена и значения) будут закодированы в любом случае при подстановке в Итоговый URL внешнего запроса, во избежание двойной кодировки на вкладке Query parameters стоит указывать параметры в незакодированном виде.
Кнопка крестика удаляет параметр (строку).
Add new field — кнопка добавления нового параметра.
Data type — формат отправляемых данных (BODY в Request):
Формат по умолчанию: JSON
Форматы:
JSON
XML
Важно: при выборе формата не забывать указывать соответствующий заголовок content-type: application/json или content-type: application/xml
Поле для добавления шаблона тела запроса (BODY), которое будет отправлено. Максимальная длина значения поля — 1000 символов.
Формат: для корректной работы с REST API должен соблюдаться формат JSON или XML в соответствии со спецификацией API назначения.
При Data type: JSON
произвольный текст.
При Data type: XML
синтаксис XML
регистр тегов имеет значение — <var></Var> будет считаться незакрытым тегом и запрос не будет выполнен
Важно: при копировании и вставке текста из сторонних систем в поле Data (например, тело запроса прислали в Slack), могут быть вставлены недопустимые символы кавычек, которые “сломают” тело запроса (JSON, XML) и сервер не сможет принять такой запрос. Визуально "неправильные” кавычки мало отличаются от “правильных”, но это все же другие символы. Примеры:
Рекомендуется использовать двойные кавычки, так как это стандарт JSON
Подстановка Контекстная переменная, Выражение и Выражение с управляющей конструкцией:
В шаблон тела запроса можно указывать Контекстная переменная в формате {{ var }}, Выражение и Выражение с управляющей конструкцией, значения и результаты выполнения которых будут подставлены при выполнении запроса. Подробнее: Использование синтаксиса в External Request.
Если Контекстная переменная не удалось найти в Контекст Чата, будет подставлено пустое значение.
Если при вычисление результата Выражение или Выражение с управляющей конструкцией происходит ошибка (например, при делении на 0), то Внешний запрос не будет отправлен, и в Контекст Чата будут записаны следующие Контекстная переменная:
error = "Template rendering (request options) error occurred."
request_success = False
response_status_code = 499
raw_response = ""
Примеры:
Формат значений Контекстная переменная:
при Data type: JSON:
значение текстовой переменной подставляется в шаблон есть без кавычек. Если в JSON необходимо отправить текстовое значение, его необходимо обрамить в кавычки - “{{ var }}”.
Например, если в Сценарий агента в переменную {{ phone }} записана строка ‘89222203909’, то
- при выполнении запроса с Data { “phone_num”: {{ phone }} } будет отправлено тело { “phone_num”: 89222203909 }
- при выполнении запроса с Data { “phone_num”: “{{ phone }}” } будет отправлено тело { “phone_num”: “89222203909” }
при Data type: XML:
Кодировка символов не латинского алфавита:
при Data type: JSON: кодирование произведено не будет
при использовании Data type: XML символы не латинского алфавита будут закодированы при отправке запроса, не зависимо от формата текста, вписанного в поле Data.
Data type — формат принимаемых данных (BODY из Response)
Формат по умолчанию: JSON
Форматы:
JSON
XML
Variable — название Пользовательские контекстные переменные, в которую будет записано значение. Максимальная длина значения поля — 128 символов. Имя Пользовательские контекстные переменные должно соответствовать требованиям к названию пользовательских контекстных переменных.
Value — ключ или Xpath путь к тегу xml из тела или заголовков ответа, значение которого будет записано в Variable. Максимальная длина значения поля — 10000 символов. По достижении максимального значения далее символы не вводятся в поле;
Возможен парсинг из тела и заголовков ответа:
body. — парсинг из тела запроса;
headers. — парсинг из заголовков запроса.
Формат значения: допустимо использование Выражение или Выражение с управляющей конструкцией.
Важно: обращение к ключу объекта, если его имя совпадает с именем Зарезервированные методы объектов происходит через квадратные скобки и кавычки.
Пример: {{ data["keys"] }}
Кнопка крестика: удаляет пару (строку)
Add new field — кнопка добавления новой пары Variable - Value.
Важно: реализовано ограничение на размер получаемого в ответ на Внешний запрос тела: если размер тела превышает Лимит на размер получаемого тела в ответ на Внешний запрос , то оно заменяется на пустое {}. )
Примеры парсинга тела и заголовков ответа в Контекстная переменная:
Пример тела JSON и парсинга его в настройках слота
Пример тела XML и парсинга его в настройках слота
Пример тела TEXT и парсинга его в настройках слота
Refresh cURL — кнопка, по нажатию которой обновляется запрос в поле cURL на вкладке Request в соответствии с настройками Внешний запрос.
Test cURL — кнопка, по нажатию которой сформированный в поле cURL запрос отправляется во внешнюю систему.
Отображение статуса запроса — полученный после отправки запроса ответ отображается слева от кнопки перехода на вкладку Request. Цвет светофора зависит от типа полученного статуса:
Раздел Request — раздел содержит данные для тестирования Внешний запрос.
cURL — сгенерированный из настроек Внешний запрос cURL.
Update request from cURL — кнопка, по нажатию которой обновляются поля Внешний запрос из cURL.
Чтобы подтвердить действие, необходимо нажать кнопку YES. При этом происходит валидация cURL:
при корректном cURL произойдет обновление настроек Внешний запрос, а именно: поля на вкладках Headers, Query Parameters, Data Внешний запрос очищаются, и в них подставляется новая информация из cURL, в т.ч. существующие данные могут быть заменены на пустые значения, если их нет в cURL. Например, если во Внешний запрос есть заголовки, а в поле cURL заголовков нет, то при нажатии Update Request from cURL текущие заголовки из Внешний запрос будут удалены, и на их месте ничего не появится.
На данный момент добавление сертификатов безопасности к Внешний запросам реализуется через поддержку: напишите на адрес support@chatme.ai, указав идентификаторы Внешний запроса или Агента, к Внешний запросам которого необходимо подставить кастомные сертификаты, и предоставить данные сертификаты.
Во Внешний запрос допустимо использование Выражение и Выражение с управляющей конструкцией в полях Endpoint, Value на вкладке Headers и Query parameters, Data, поле Name на вкладке Response. Подробнее: Синтаксис.
ВАЖНО: при парсинге ответа все используемые в шаблоне переменные из поля Value ищутся в ответe (Response), а не в Контекст Чата. Обращение к телу ответа происходит через переменную body. Обращение к заголовкам запроса происходит через переменную headers. Например, если ответом на ER является JSON объект: {“one”: {“two”: [0, 1, 2]}}, то в переменную resp_body будет сохранен весь JSON-объект (словарь) {“one”: {“two”: [1, 2, 3]}}, в переменную resp_one – будет сохранен объект (словарь) {“two”: [1, 2, 3]}, в переменную resp_two будет сохранено целое число 1. Переменная resp_invalid не будет сохранена, т.к. к телу ответа нужно обращаться через переменную body.
Для удаления единичного Внешний запрос необходимо:
Перейти в список Внешний запрос.
Нажать на название Внешний запрос или галочку в селекторе напротив.
Для создания копии — клонирования единичного Внешний запроса необходимо:
Перейти в список Внешний запросов.
Нажать на название Внешний запроса или галочку в селекторе напротив.
Подтвердить действие в модальном окне, нажав кнопку YES, I’M SURE.
В Платформа реализован множественный выбор Внешний запросов и массовые действия, применимые к группе Внешний запросов.
Множественный выбор Внешний запросов можно осуществить следующими способами:
Проставить галочки в соответствующих необходимым Внешний запросам селекторах вручную.
Проставить галочки в селекторе массового выбора — в этом случае будут выделены все Внешний запросы на странице.
Выбрать одну из групп Внешний запросов. По клику на стрелочке открывается выпадающий список;
В выпадающем списке необходимо выбрать группу Внешний запросов на текущей странице:
All — все Внешний запросы;
In use — только используемые в Агентах Внешний запросы;
Not in use — только неиспользуемые Внешний запросы.
Снятие выделения с выбранных Внешний запросов можно осуществить следующими способами:
Удалить галочек из селекторов вручную.
Через селектор массового выбора.
Выбрать вариант Clear selection в выпадающем списке:
Чтобы единовременно удалить несколько Внешний запросов, необходимо:
Выбрать несколько Внешний запросов, как описано в пункте Множественный выбор;
Нажать кнопку Delete requests;
Подтвердить действие в модальном окне, нажав кнопку DELETE REQUESTS;
Если в числе выбранных Внешний запросов присутствуют Внешний запросы, которые используются в Агентах, при удалении появится предупреждение о том, что данные Внешний запросы не были удалены.
Остальные Внешний запросы будут удалены.
Чтобы единовременно клонировать несколько Внешний запросов, необходимо:
Выбрать несколько Внешний запросов, как описано в пункте Множественный выбор;
По нажатию кнопки YES, I’M SURE будут созданы копии Внешний запроса с названием <название клонируемого запроса> CLONE.
При экспорте Агента происходит также экспорт всех Внешний запросов, содержащихся в его Обученная модель агента.Агент с включенными в него Внешний запросами экспортируется в виде файла формата .cfg.При импорте Агента происходит импорт используемых в нем Внешний запросов, при этом:
Если в Компания есть Внешний запрос с идентичным названием и содержимым, дублирования Внешний запроса не происходит. В импортированном Агенте будет использован уже существующий Внешний запрос. В остальных случаях будет создан новый Внешний запрос.
Шаблон имени импортированного Внешний запроса: название_запроса [imported timestamp], где timestamp — время импортирования данного Агента: количество секунд с 1 января 1970 года.
Если в Компания есть Внешний запрос с отличающимся названием, но идентичным содержанием, то Внешний запрос из конфигурационного файла Агента будет импортирован.
Если в Компания нет такого Внешний запроса, то он будет импортирован и появится в списке Внешний запросов.
В списке будут выведены только Внешний запросы, содержащие в названии искомую строку;
По нажатию на кнопку In use выводятся Внешний запросы, используемые в Агентах;
По нажатию на кнопку Agent открывается панель поиска по Агентам.
По нажатию на кнопку Not in use выводятся Внешний запросы, не используемые в Агентах.
Нажать кнопку Create new.
Вкладка Main содержит базовые данные Внешний запроса.Поля вкладки:
Строка
Контекстная переменная в формате {{ var }}
Выражение или Выражение с управляющей конструкцией. Подробнее: Использование синтаксиса в External Request.
На вкладке Headers можно добавить заголовки к Внешний запросу.Поля и кнопки вкладки:
На вкладке Query parameters можно прописать параметры, которые будут подставлены к URL запроса.Поля и кнопки вкладки:
Пример:
На вкладке Data можно указать данные в JSON или XML, которые будут отправлены в теле запроса (BODY)Поля вкладки:
при Data type: JSON:
при Data type: XML:
переменная должны быть записана в XML тег с помощью фигурных скобок {{ }} и с учетом регистра. Например:
Результат запроса, Data type: XML, и в client_message записана кириллица
На вкладке Response настраивается парсинг ответов на Внешний запрос в Пользовательские контекстные переменные.Парсинг выполняется в процессе обработки ответа на Внешний запрос.При парсинге ответа на запрос переменные, указанные в поле Value, не являются Контекстная переменная, а являются обращениями к объектам body и headers — частям ответа на запрос — и их свойствам.Поля и кнопки вкладки:
TEXT
Табличная часть — массив пар Variable - Value для парсинга данных из тела и заголовков ответа на Внешний запрос в Пользовательские контекстные переменные для последующего использования их в Сценарий агента.
Для типа TEXT возможен парсинг только всего тела ответа на Внешний запрос.
На вкладке Test можно протестировать работу Внешний запрос.При создании нового Внешний запрос до заполнения параметров Внешний запрос поле cURL не заполнено.При открытии существующего Внешний запрос cURL генерируется автоматически и вкладка заполнена.Поля и элементы вкладки:
Успешный статус: 200 OK — зеленый цвет;
Статусы с предупреждениями: от 201 до 399 — желтый цвет;
Ошибки: от 400 и выше — красный цвет.
По нажатию кнопки появляется модальное окно подтверждения действия:
при отсутствии Endpoint или некорректной структуре cURL будет выведена ошибка Invalid cURL и всплывающее уведомление Could’t parse cURL, request settings have not been updated.
Раздел Response — раздел содержит ответ внешней системы на запрос.
До нажатия кнопки Test cURL раздел недоступен для открытия (так как тестовый запрос не был отправлен и никакого ответа еще нет)
Подраздел Body — подраздел содержит тело ответа на запрос;
Подраздел Headers — подраздел содержит заголовки ответа на запрос;
Отображение статуса запроса;
Время от отправки запроса до получения ответа в миллисекундах;
Размер тела ответа в байтах.
Нажать на кнопку Delete request или Delete на панели справа;
Подтвердить действие в модальном окне, нажав кнопку DELETE REQUEST.
Если удаляемый Внешний запрос используется в Агентах, при удалении появится предупреждение о том, что необходимо сначала удалить его из Сценарий агента Агента;
Нажать на кнопку Duplicate request или Delete на панели справа;
По нажатию кнопки YES, I’M SURE будет создана копия Внешний запроса с названием <имя клонируемого запроса >CLONE.
Нажать кнопку Duplicate requests;
Подтвердить действие в модальном окне, нажав кнопку YES, I’M SURE в модальном окне.
Если в компании есть Внешний запрос с идентичным названием, но отличающимся содержимым, будет создан дубликат этого Внешний запрос с автоматически сгенерированным именем: