> 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/) *для отримання та перегляду запитів під час тестування.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.jedidesk.com/nalashtuvannya-jedidesk-ai/vlasni-funkciyi-ai.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.