Пользовательские функции

Агент может вызывать пользовательские функции с помощью HTTP-запросов. Например, агент может уточнить у пользователя номер заказа, вызвать http-метод https://endpoint/api/get_order=1 и предоставить пользователю информацию о его заказе.

Агент поддерживает GET и POST запросы. Для POST запросов тело запроса должно быть application/json. Поддерживается передача заголовков, в том числе и Authorization.

На странице Агенты -> Ответ нажмите Добавить функцию, откроется окно для создания функции.

Основная структура JSON-описания

На вкладке Описание необходимо добавить JSON, который должен следовать строгому формату.

name (строка)

Описание: Уникальное имя функции, отражающее её цель.

Пример:

"name": "validate_user_email"

description (строка)

Описание: Краткое описание назначения функции.

Пример:

"description": "Проверяет, зарегистрирован ли адрес электронной почты в системе."

parameters (объект)

Описание: Определяет входные параметры, которые принимает функция.

Состав:

• type (объект): Указывает, что параметры являются объектом.
• properties (объект): Описывает все ожидаемые свойства (поля).
• required (массив): Указывает обязательные для передачи поля.

Пример:

"parameters": {
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Адрес электронной почты пользователя."
    }
  },
  "required": ["email"]
}

Типы данных

string

Описание: Простой текст.

Поля:

• description (строка): Объясняет, что представляет собой строка.
• pattern (строка): Регулярное выражение для проверки формата.

Пример:

"phone": {
  "type": "string",
  "description": "Номер телефона, начинающийся с +7 и 10 последующими цифрами."
}

number

Описание: Числовое значение, может быть как целым, так и дробным.

Поля:

• description (строка): Объясняет, что означает число.

Пример:

"age": {
  "type": "number",
  "description": "Возраст пользователя в годах."
}

object

Описание: Сложная структура, содержащая взаимосвязанные поля.

Поля:

• properties (объект): Описывает составные части объекта.
• required (массив): Определяет обязательные поля внутри объекта.

Пример:

"user": {
  "type": "object",
  "properties": {
    "id": { "type": "number" },
    "name": { "type": "string" }
  },
  "required": ["id", "name"]
}

array

Описание: Коллекция данных, может содержать как простые, так и сложные типы.

Поля:

• items (объект): Описывает тип данных, содержащийся в массиве.
• description (строка): Объясняет, что представляет собой массив.

Пример:

"tags": {
  "type": "array",
  "items": {
    "type": "string"
  },
  "description": "Список тегов, связанных с элементом."
}

Пример полной функции

{
  "name": "check_user_subscriptions",
  "description": "Проверяет, есть ли у указанных пользователей активные подписки.",
  "parameters": {
    "type": "object",
    "properties": {
      "users": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "Уникальный идентификатор пользователя"
            },
            "name": {
              "type": "string",
              "description": "Имя пользователя"
            }
          },
          "required": ["id", "name"],
          "description": "Объект информации о пользователе"
        },
        "description": "Массив объектов пользователей, содержащих id и имя"
      },
      "include_inactive": {
        "type": "boolean",
        "description": "Флаг, указывающий включать или нет неактивные подписки в результаты"
      }
    },
    "required": ["users"]
  }
}

Действие

На вкладке Действия настраивается вызов вебхука. Если вы верно указали описание функции, то автоматически появятся кнопки с доступными аргументами. В примере по умолчанию это location и unit. Данные кнопки позволяет вставить переменные, с которыми агент вызывает функцию, в шаблоны Вебхук URL и тела запроса.