5️⃣Власні функції AI

Власні функції дозволяють підключити будь-яку зовнішню систему до вашого AI-асистента. Коли під час розмови з клієнтом AI вирішить, що потрібно виконати дію — він автоматично відправить запит на ваш сервер із потрібними параметрами та використає відповідь у розмові.

Приклади використання:

• Перевірка статусу замовлення за номером

• Перевірка наявності товару на складі

• Отримання інформації з CRM (дані клієнта, історія покупок)

• Запис клієнта на послугу

• Розрахунок вартості доставки

• Будь-яка інша логіка, яку може обробити ваш бекенд

---

Як створити власну функцію

Перейдіть у Налаштування AI → AI Функції → Власні функції та натисніть «Додати функцію».

Поля функції

Назва функції (обов'язкове)

Технічна назва функції латиницею. Дозволено лише малі літери, цифри та підкреслення. Повинна починатися з літери.

Приклади:

• get_order_status

• check_stock

• calculate_delivery

• book_appointment

Ця назва передається в полі function у webhook-запиті — саме за нею ваш сервер визначає, яку дію потрібно виконати.

Опис функції (обов'язкове)

Текстовий опис того, що робить функція. AI використовує цей опис для того, щоб зрозуміти, коли потрібно викликати функцію. Чим точніше опис — тим краще AI визначатиме момент виклику.

Приклади:

• перевіряє статус замовлення за номером замовлення

• перевіряє наявність товару на складі за артикулом

• розраховує вартість доставки за адресою та вагою

Пишіть опис мовою, на якій працює ваш AI-асистент.

Інструкція для AI (необов'язкове)

Додаткові правила поведінки AI, коли ця функція активна. Наприклад, можна вказати, що AI повинен завжди викликати цю функцію в певних ситуаціях, або як інтерпретувати відповідь.

Приклади:

• завжди викликай цю функцію, коли клієнт питає про статус замовлення, не покладайся на попередні відповіді

• якщо функція повернула помилку, попроси клієнта повторити номер замовлення

• після отримання результату, представ інформацію у зручному вигляді для клієнта

Параметри функції

Список даних, які AI збере від клієнта та передасть у запиті на ваш сервер. Для кожного параметра вказується:

Поле	Опис
Назва (ключ)	Технічна назва параметра латиницею (наприклад, order_id, phone, product_sku)
Тип	Тип даних: Текст, Число, Ціле число, Так/Ні
Обов'язковий	Чи повинен AI обов'язково зібрати цей параметр перед викликом
Підказка для AI	Опис параметра, щоб AI розумів, що саме потрібно запитати у клієнта
Допустимі значення	(необов'язково) Перелік конкретних значень через кому. Якщо заповнено — AI обиратиме лише з цих варіантів

Приклад параметрів для функції get_order_status:

Назва	Тип	Обов'язковий	Підказка	Допустимі значення
order_id	Текст	Так	номер замовлення клієнта	—

Приклад параметрів для функції book_appointment:

Назва	Тип	Обов'язковий	Підказка	Допустимі значення
service	Текст	Так	назва послуги	консультація, діагностика, ремонт
date	Текст	Так	бажана дата у форматі ДД.ММ.РРРР	—
phone	Текст	Так	контактний телефон клієнта	—
comment	Текст	Ні	додатковий коментар	—

---

Налаштування вебхука

Для того, щоб ваш сервер отримував виклики від AI, потрібно налаштувати вебхук.

Крок 1: Створіть endpoint на вашому сервері

Ваш сервер повинен мати URL, який приймає POST-запити та повертає JSON-відповідь.

Крок 2: Зареєструйте вебхук у JediDesk

Перейдіть у розділ Інтеграція → API та створіть вебхук:

• Вкажіть URL вашого сервера

• У списку подій оберіть ai.func_call

---

Формат запиту (webhook payload)

Коли AI вирішує викликати вашу функцію, JediDesk відправляє POST-запит на ваш вебхук з таким JSON-тілом:

{
  "event": "ai.func_call",
  "data": {
    "function": "get_order_status",
    "parameters": {
      "order_id": "12345"
    }
  },
  "timestamp": "2026-04-07T12:00:00+00:00",
  "token": "your-api-token",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Поле	Опис
event	Завжди ai.func_call
data.function	Назва функції, яку AI вирішив викликати
data.parameters	Об'єкт з параметрами, які AI зібрав від клієнта
timestamp	Час виклику у форматі ISO 8601
token	API-токен вашої компанії (для верифікації запиту)
request_id	Унікальний ідентифікатор запиту (UUID)

Як визначити яку функцію викликано

Якщо у вас кілька власних функцій, всі виклики приходять на один вебхук. Розрізняйте їх за полем data.function:

app.post('/webhook', (req, res) => {
  const { function: funcName, parameters } = req.body.data;

  switch (funcName) {
    case 'get_order_status':
      return res.json(getOrderStatus(parameters.order_id));
    case 'check_stock':
      return res.json(checkStock(parameters.product_sku));
    default:
      return res.json({ error: 'Unknown function' });
  }
});

$payload = json_decode(file_get_contents('php://input'), true);
$funcName = $payload['data']['function'];
$params = $payload['data']['parameters'];

switch ($funcName) {
    case 'get_order_status':
        $result = getOrderStatus($params['order_id']);
        break;
    case 'check_stock':
        $result = checkStock($params['product_sku']);
        break;
    default:
        $result = ['error' => 'Unknown function'];
}

header('Content-Type: application/json');
echo json_encode($result);

---

Формат відповіді

Ваш сервер повинен повернути JSON-відповідь. AI використає цю відповідь для формування повідомлення клієнту.

Успішна відповідь (HTTP 200):

{
  "status": "delivered",
  "delivery_date": "05.04.2026",
  "tracking_number": "UA1234567890"
}

Відповідь з помилкою:

{
  "error": "Замовлення з таким номером не знайдено"
}

AI розуміє структуру вашої відповіді та самостійно формулює повідомлення для клієнта на основі отриманих даних. Тому не потрібно формувати готовий текст — достатньо повернути дані.

Рекомендації до відповіді

• Повертайте зрозумілі назви полів (краще delivery_date, ніж dd)

• Якщо помилка — повертайте текст помилки в полі error, AI передасть суть клієнту

• Відповідь має повернутися протягом розумного часу (до 10 секунд)

• Максимальний розмір відповіді — не обмежений жорстко, але великі відповіді можуть вплинути на якість інтерпретації AI

---

Верифікація запиту

Для безпеки рекомендуємо перевіряти token у вхідному запиті — він відповідає API-токену вашої компанії з розділу Інтеграція → API.

$token = $payload['token'];
if ($token !== env('JEDIDESK_API_TOKEN')) {
    http_response_code(403);
    exit;
}

---

Повний приклад: функція «Перевірка статусу замовлення»

1. Створення функції в JediDesk

• Назва: get_order_status

• Опис: перевіряє статус замовлення за номером замовлення

• Інструкція для AI: завжди викликай цю функцію, коли клієнт питає про статус замовлення або доставку. Не вигадуй статус самостійно.

• Параметри:

  • order_id — Текст, обов'язковий, підказка: номер замовлення клієнта

2. Налаштування вебхука

• URL: https://yoursite.com/api/jedidesk-webhook

• Подія: ai.func_call

3. Обробник на вашому сервері

// Laravel приклад
Route::post('/api/jedidesk-webhook', function (Request $request) {
    $funcName = $request->input('data.function');
    $params = $request->input('data.parameters');

    if ($funcName === 'get_order_status') {
        $order = Order::where('number', $params['order_id'])->first();

        if (!$order) {
            return response()->json([
                'error' => 'Замовлення не знайдено'
            ]);
        }

        return response()->json([
            'order_number' => $order->number,
            'status' => $order->status,
            'created_at' => $order->created_at->format('d.m.Y'),
            'total' => $order->total . ' грн',
            'delivery_status' => $order->delivery_status,
            'tracking_number' => $order->tracking_number,
        ]);
    }

    return response()->json(['error' => 'Unknown function']);
});

4. Як це виглядає у діалозі

Клієнт: Який статус мого замовлення 12345?
AI: [викликає функцію get_order_status з order_id="12345"]
AI: Ваше замовлення #12345 має статус «Доставлено».
    Дата створення: 01.04.2026, сума: 1500 грн.
    Трекінг-номер: UA1234567890.

---

Управління функціями

• Увімкнути/вимкнути — перемикач зліва від назви функції. Вимкнена функція не буде доступна AI.

• Редагувати — кнопка з іконкою олівця.

• Видалити — кнопка з іконкою кошика.

• Аналітика — кнопка з іконкою графіка. Показує статистику викликів функції: кількість, успішні/помилкові, середній час відповіді.

---

Логування

Всі виклики кастомних функцій логуються. Переглянути їх можна в розділі Інтеграція → API → Логи вебхуків. Для кожного виклику зберігається:

• Відправлений запит (payload)

• Статус відповіді (HTTP код)

• Тіло відповіді

• Час виклику

Це допомагає у відлагодженні, якщо функція не працює як очікувалось.

---

Поширені питання

1. Скільки власних функцій можна створити?

Кількість обмежена тарифним планом. Якщо ви бачите повідомлення про обмеження — зверніться до підтримки або перейдіть на вищий план.

1. Чи можна мати кілька функцій на одному вебхуку?

Так. Всі виклики ai.func_call йдуть на один зареєстрований вебхук. Розрізняйте їх за полем data.function.

1. Що станеться, якщо мій сервер не відповість?

AI повідомить клієнту, що не вдалося отримати інформацію, та запропонує спробувати пізніше або звернутися до менеджера.

1. Як AI вирішує, коли викликати функцію?

AI аналізує опис функції та контекст розмови. Якщо запит клієнта відповідає опису — AI збирає необхідні параметри та робить виклик. Поле «Інструкція для AI» додатково уточнює правила виклику.

1. Чи можна тестувати функцію без реального сервера?

Так. Ви можете використати сервіси на кшталт webhook.site або requestbin.com для отримання та перегляду запитів під час тестування.