Пошаговая инструкция. Создаём первую функцию

Содержание:

• Шаг 1. Включаем режим функций
• Шаг 2. Создаём новую функцию
• Шаг 3. Вкладка «Описание»
• Шаг 4. Вкладка «Действие»
• Шаг 5. Сохраняем функцию
• Шаг 6. Проверяем работу

В этой статье мы проведём вас за руку по всем этапам создания функции. В качестве примера настроим функцию проверки статуса заказа.

Шаг 1. Включаем режим функций

1. Перейдите в раздел «Функции» в левом меню.
2. В самом верху страницы найдите переключатель «Использование функций в запросах».
3. Убедитесь, что он включён — переключатель горит синим.

⚠️ Важно

Без этого переключателя бот не сможет вызывать функции, даже если вы их создадите.

Шаг 2. Создаём новую функцию

Нажмите зелёную кнопку «+ Добавить функцию» в правой части экрана.

Откроется окно редактирования функции с двумя вкладками:

• Описание — объясняем боту, что это за функция;
• Действие — настраиваем техническую часть: URL, заголовки и прочее.

Шаг 3. Вкладка «Описание»

Название

Введите техническое имя функции на английском языке. Используйте snake_case — слова через нижнее подчёркивание.

✅ Так нужно

• get_order_status
• find_client_by_phone
• get_delivery_price

❌ Так не стоит

• function1
• api
• test

В нашем примере вводим get_order_status.

Описание

Это самое важное поле: именно по описанию модель понимает, когда нужно вызвать функцию. Пишите простым языком и укажите, что функция делает, когда её нужно использовать и какие данные возвращает.

Пример: Возвращает статус заказа по запросу клиента сообщить статус заказа

❌ Чего не писать

Технические детали API, названия эндпоинтов и внутренние термины вашей системы. Модель читает это поле как обычный текст — ей нужен смысл, а не документация.

JSON Schema

Это «анкета», которую бот заполнит данными из сообщения пользователя. Здесь описываются параметры функции. Для проверки статуса заказа нужен всего один — order_id.

{
  "type": "object",
  "required": ["order_id"],
  "properties": {
    "order_id": {
      "type": "integer",
      "description": "Номер заказа"
    }
  },
  "additionalProperties": false
}

Разберём по частям:

• type: "object" — корневой тип всегда должен быть object;
• required: ["order_id"] — этот параметр обязателен;
• properties — описание каждого параметра:
  • type: "integer" — номер заказа это число;
  • description: "Номер заказа" — подсказка для модели;
• additionalProperties: false — запрещаем лишние параметры.

Тестовые аргументы

Обязательное поле. Здесь указывается пример данных для проверки функции.

{
  "order_id": 12345
}

При нажатии кнопки «Тестировать» система автоматически подставит эти данные.

Шаг 4. Вкладка «Действие»

Теперь настроим техническую часть — куда и как отправлять запрос.

HTTP метод

• GET — для получения данных, наиболее распространён;
• POST — для отправки данных;
• PUT / PATCH — для обновления;
• DELETE — для удаления.

Для нашего примера выбираем GET.

URL запроса

Введите адрес вашего API. Переменные подставляются прямо в URL — заключайте их в одинарные фигурные скобки:

https://helpfy-ai.free.beeceptor.com/order/{order_id}

Когда бот получит номер заказа, он подставит его в адрес:

https://helpfy-ai.free.beeceptor.com/order/12345

⚠️ Ограничения адреса

• разрешены только HTTPS-адреса;
• запрещены localhost и приватные IP;
• максимальная длина — 2048 символов.

Заголовки

Если вашему API нужны HTTP-заголовки — например, Content-Type или токен авторизации — добавьте их кнопкой «+ Добавить заголовок».

Body template — шаблон тела запроса

Если вы используете метод POST или PUT, здесь описывается JSON, который отправится на сервер. Переменные, как и в адресе, заключаются в одинарные фигурные скобки и обязательно в кавычки:

{
  "order_id": "{order_id}"
}

ℹ️ Полезно знать

• Для GET-запросов это поле обычно оставляют пустым.
• Кавычки нужны даже для числовых параметров — без них шаблон не сохранится.

Response path

Ваш API может вернуть большой JSON с множеством данных. Чтобы бот не запутался, укажите путь к нужной части ответа через точку.

Допустим, API отвечает так:

{
  "data": {
    "result": {
      "status": "Доставляется",
      "delivery_date": "15 июня 2026"
    }
  }
}

Если указать data.result, модели будет передано только:

{
  "status": "Доставляется",
  "delivery_date": "15 июня 2026"
}

ℹ️ Совет

Если оставить поле пустым, бот получит весь ответ API целиком.

Таймаут, мс

Максимальное время ожидания ответа от вашего API в миллисекундах. Рекомендуемое значение — 5000–15000 мс (5–15 секунд). Минимум 1000, максимум 30000. Для нашего примера оставляем 15000.

Максимальный размер ответа, байт

Если ответ API окажется больше указанного, функция завершится ошибкой. Рекомендуемое значение — 65536 (64 КБ). Минимум 1024, максимум 1048576 (1 МБ).

ℹ️ Совет

Не отдавайте боту огромные ответы. Используйте Response path, чтобы вернуть только нужные данные.

Функция активна

Убедитесь, что переключатель включён. Если функция неактивна, она сохранится, но бот не сможет её использовать.

Шаг 5. Сохраняем функцию

Нажмите зелёную кнопку «Сохранить изменения» внизу окна. Если все поля заполнены корректно, функция появится в списке.

Шаг 6. Проверяем работу

Перейдите в раздел «Тестирование» в левом меню и напишите боту:

Какой статус у моего заказа под номером 12345?

Бот должен:

1. распознать номер заказа (12345);
2. автоматически вызвать функцию get_order_status;
3. отправить запрос на ваш API;
4. вернуть ответ пользователю.

Пример ответа бота: «Статус вашего заказа под номером 12345 — "Доставляется". Ожидаемая дата доставки — 15 июня 2026 года.»

В следующей статье — «Справочник параметров» — разберём все настройки функции для продвинутых пользователей.