> For the complete documentation index, see [llms.txt](https://docs.jedidesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jedidesk.com/nalashtuvannya-jedidesk-ai/vlasni-funkciyi-ai.md). # Власні функції 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-тілом: ```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`: ```javascript 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' }); } }); ``` ```php $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):** ```json { "status": "delivered", "delivery_date": "05.04.2026", "tracking_number": "UA1234567890" } ``` **Відповідь з помилкою:** ```json { "error": "Замовлення з таким номером не знайдено" } ``` AI розуміє структуру вашої відповіді та самостійно формулює повідомлення для клієнта на основі отриманих даних. Тому не потрібно формувати готовий текст — достатньо повернути дані. #### Рекомендації до відповіді * Повертайте зрозумілі назви полів (краще `delivery_date`, ніж `dd`) * Якщо помилка — повертайте текст помилки в полі `error`, AI передасть суть клієнту * Відповідь має повернутися протягом розумного часу (до 10 секунд) * Максимальний розмір відповіді — не обмежений жорстко, але великі відповіді можуть вплинути на якість інтерпретації AI *** ### Верифікація запиту Для безпеки рекомендуємо перевіряти `token` у вхідному запиті — він відповідає API-токену вашої компанії з розділу **Інтеграція → API**. ```php $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. Обробник на вашому сервері ```php // 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. **Скільки власних функцій можна створити?** *Кількість обмежена тарифним планом. Якщо ви бачите повідомлення про обмеження — зверніться до підтримки або перейдіть на вищий план*. 2. **Чи можна мати кілька функцій на одному вебхуку?** *Так. Всі виклики `ai.func_call` йдуть на один зареєстрований вебхук. Розрізняйте їх за полем `data.function`.* 3. **Що станеться, якщо мій сервер не відповість?** *AI повідомить клієнту, що не вдалося отримати інформацію, та запропонує спробувати пізніше або звернутися до менеджера.* 4. **Як AI вирішує, коли викликати функцію?** *AI аналізує опис функції та контекст розмови. Якщо запит клієнта відповідає опису — AI збирає необхідні параметри та робить виклик. Поле «Інструкція для AI» додатково уточнює правила виклику.* 5. **Чи можна тестувати функцію без реального сервера?** *Так. Ви можете використати сервіси на кшталт* [*webhook.site*](https://webhook.site/) *або* [*requestbin.com*](https://requestbin.com/) *для отримання та перегляду запитів під час тестування.*