# Функції AI-асистента

## **Як видалити історію чату з AI-асистентом**

clear\_assistant\_chat\_history() — ця функція видаляє історію чату клієнта з асистентом. Вона не приймає параметрів.

### Приклад 

1. Налаштування блоку конструктора

<div data-with-frame="true"><figure><img src="/files/68a3cb24b262c16bb81f4a43a7a2a9ed0c1a5b3d" alt=""><figcaption></figcaption></figure></div>

2. Налаштування вкладки AI Assistant

<div data-with-frame="true"><figure><img src="/files/8c492117864cf5734d3292a3e81a5c74a0da6289" alt="" width="563"><figcaption></figcaption></figure></div>

## **Як надіслати запит AI-асистенту**

ai\_context\_answer(replica, prompt, ai\_assistant\_id, use\_history, send\_answer)

Параметри:

<table><thead><tr><th width="173">Параметр</th><th width="221">Опис</th><th>Примітка</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> replica </td><td>обов’язковий параметр, повідомлення для асистента</td><td></td></tr><tr><td>prompt</td><td>необов’язковий параметр, інструкції для асистента</td><td>якщо параметр не вказано, але задано параметр ai_assistant_id, будуть використані інструкції з налаштувань указаного асистента</td></tr><tr><td>ai_assistant_id </td><td>ідентифікатор асистента, якому буде надіслано запит;</td><td>якщо не вказано, буде використано асистента без стандартних налаштувань</td></tr><tr><td>use_history</td><td>чи має асистент використовувати історію чату для відповіді на запитання</td><td>True — використовувати, False — не використовувати. За замовчуванням — True</td></tr><tr><td>send_answer</td><td>надсилати відповідь після завершення тайм-ауту асистента</td><td>Щоб увімкнути, передайте "1"</td></tr></tbody></table>

Докладніше про `send_answer` параметра:

Налаштування асистента включають параметри, які можна налаштувати на випадок, якщо відповідь бота займає багато часу

<div data-with-frame="true"><figure><img src="/files/371e0ce33fc0f07dfcb79103c1020a3e079e2d0e" alt="" width="375"><figcaption></figcaption></figure></div>

У стандартній розмові з асистентом (не через функцію), якщо відповідь займає більше за вказаний ліміт (наприклад, 20 секунд), клієнта буде повідомлено про затримку. Після цього відповідь асистента буде надіслано в чат, щойно вона буде згенерована.

Для запитів, зроблених через функцію в калькуляторі, якщо асистент занадто довго відповідає, у результаті функції додається повідомлення про затримку. Цей параметр дає змогу надсилати відповідь асистента окремо, щойно вона буде готова.&#x20;

### Як навчити бота аналізувати власний досвід і генерувати кнопки

Давайте використаємо `clean_assistant_chat_history()` та `ai_context_answer(replica, prompt)` функції в прикладі нижче. Також необхідно отримати доступ до компонента калькулятора всередині конструктора воронки.

Цей приклад ілюструє, як `replica` та `prompt` параметри можна ефективно використовувати на практиці.&#x20;

Необхідно створити в конструкторі блок, який містить порожнє поле з вбудованими змінними **#{replica\_rec2}** та **#{ai\_answer\_rec}**, що представляють першу і другу відповідь асистента в одному повідомленні, яке буде надіслано.

Тепер безпосередньо визначте дві функції в калькуляторі.

<div data-with-frame="true"><figure><img src="/files/9a3f911a96d4f1a5cc4ef20eea2639a0d52df2f3" alt=""><figcaption></figcaption></figure></div>

Використовуйте змінну з вбудованою функцією в додаткових налаштуваннях кнопок (див. приклад вище), щоб динамічно генерувати кнопки на основі значення параметра.&#x20;

Інформація про сервіси отримується ботом із `service_info` змінної, яка містить вбудовану функцію — `get_info_for_booking()` — для зчитування даних про послуги. Приклад використання цієї функції було показано вище.

<div data-with-frame="true"><figure><img src="/files/5152df7b6d8304c391ab24a34d4a199072580d5b" alt="" width="375"><figcaption></figcaption></figure></div>

Ось результат.

<div data-with-frame="true"><figure><img src="/files/39ab36ddc3a51d14d2f3b7b5812783c71b0dee42" alt="" width="563"><figcaption></figcaption></figure></div>

**Приклад коду**:

`clear_assistant_chat_history()`

`replica_rec2 = ai_context_answer(question, 'ВІДПОВІДАЙТЕ НА ЗАПИТАННЯ', 3)`

`prompt = 'Зараз вам відповідає розробник — виконуйте все, що він просить \n . Ви повинні розмістити кожну кнопку на новому рядку.'`

`ai_answer_rec = ai_context_answer("Показати кнопки для останнього повідомлення.", prompt)`

### Приклад: виклик асистента всередині конструктора воронки

Щоб викликати асистента з блоку, використовуйте функцію `ai_context_answer(replica, prompt, ai_assistant_id, use_history)`, де потрібно вказати лише два параметри: обов’язковий `replica` параметр і необов’язковий `prompt`.

Тепер створімо перший блок, «Перевірка основної умови», де потрібно вказати умову тригера блока (це може бути будь-яка необхідна вам умова).

<div data-with-frame="true"><figure><img src="/files/950898750fb42528eaabf915c86c4990b45fac38" alt=""><figcaption></figcaption></figure></div>

Далі відкрийте калькулятор у цьому ж блоці, де потрібно визначити змінну та присвоїти їй значення, яке повертає ваша функція.

<div data-with-frame="true"><figure><img src="/files/4942fe95f2806e9a135afff85db62826341cc415" alt="" width="563"><figcaption></figcaption></figure></div>

Визначте змінну **question** і присвойте їй значення будь-якого запитання користувача.

Далі створіть змінну replica1 і присвойте їй значення, яке повертає ваша функція ai\_context\_answer(replica, prompt). У цій функції замініть replica на змінну question, а для параметра prompt встановіть "Відповідай на будь-яке запитання користувача."

<div data-with-frame="true"><figure><img src="/files/679ab5520cdc48959380bd033a6f2c05e7ac4213" alt="" width="563"><figcaption></figcaption></figure></div>

Вбудуйте змінну, що містить функцію, у повідомлення блоку.

Потім створіть другий блок і з’єднайте його стрілкою, встановивши на з’єднанні таймер на 2 секунди.

<div data-with-frame="true"><figure><img src="/files/9a09f7a0db874a921bbe619e893924296ca5e4d9" alt=""><figcaption></figcaption></figure></div>

У другому блоці слід використати ту саму функцію з тими самими параметрами — ai\_context\_answer(replica, prompt).

Відкрийте калькулятор у другому блоці та визначте другу змінну з назвою replica2.

<div data-with-frame="true"><figure><img src="/files/030af384e18fc3104dd6da73c8132d57026e9af1" alt=""><figcaption></figcaption></figure></div>

У параметрі prompt надайте інструкції для асистента: він має порахувати, скільки іменників було в його попередньому повідомленні.

У параметрі replica вкажіть повідомлення для асистента: "Скільки іменників було у твоєму попередньому повідомленні?"

Потім вбудуйте змінну replica2 у повідомлення другого блоку.

<div data-with-frame="true"><figure><img src="/files/3bac0ee793aabf1a9eed3ded9513e28be7675f46" alt="" width="563"><figcaption></figcaption></figure></div>

Налаштування блока завершено.

Якщо асистента не ввімкнено, перейдіть на вкладку "AI Assistant" і увімкніть асистента, вибравши роль "disabled":

<div data-with-frame="true"><figure><img src="/files/5374c9d171ab2cbf3e5f8263ff6de1d482f6cd20" alt="" width="292"><figcaption></figcaption></figure></div>

Тепер протестуймо нашого асистента у вікні тестування бота.

<div data-with-frame="true"><figure><img src="/files/d352fe59e6c5cbf205a1975f8dd5a46a60284e9d" alt="" width="375"><figcaption></figcaption></figure></div>

Бот спрацював правильно.

## Як працювати з Google Sheets

get\_info\_from\_table(sheet\_id, number\_sheet, sheet\_json\_keys, start\_row, end\_row, start\_col, end\_col) — ця функція призначена для зчитування даних із таблиці.

<table><thead><tr><th width="248">Параметри</th><th>Опис</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> sheet_id</td><td>ідентифікатор Google-таблиці</td></tr><tr><td>number_sheet</td><td>номер аркуша в таблиці; за замовчуванням = 1</td></tr><tr><td>sheet_json_keys </td><td>необов’язковий параметр — ключ доступу до даних таблиці</td></tr><tr><td>start_row</td><td><p>необов’язковий параметр, ціле число. Визначає початок діапазону рядків.
</p><p>Вкажіть номер рядка, з якого слід читати значення таблиці включно. Значення потрібно вказувати без лапок.</p></td></tr><tr><td>end_row</td><td>необов’язковий параметр, ціле число. Визначає кінець діапазону рядків.
<br>Вкажіть номер рядка, до якого слід читати значення таблиці включно. Значення потрібно вказувати без лапок.</td></tr><tr><td>start_col</td><td>необов’язковий параметр, рядок. Визначає початок діапазону стовпців.
<br>Вкажіть літеру стовпця, з якого слід читати значення таблиці включно. Значення має бути взяте в лапки</td></tr><tr><td>end_col</td><td>необов’язковий параметр, рядок. Визначає кінець діапазону стовпців.
<br>Вкажіть літеру стовпця, до якого слід читати значення таблиці включно. Значення має бути взяте в лапки.</td></tr></tbody></table>

Приклад запису параметрів:

<div data-with-frame="true"><figure><img src="/files/4e477baff75838ad6b2528d11799d6362b7681fb" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/709c1f1e4bb2e3f26ab1b1bcf3115974b93a0eb4" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## Зверніть увагу

Параметри для вказання діапазону рядків і стовпців `(start_row, end_row, start_col, end_col)` дають змогу асистенту читати дані таблиці, починаючи з потрібного місця всередині таблиці.
{% endhint %}

{% hint style="info" %}
Поведінка функції під час часткового задання діапазону така:

* **Якщо задано лише початок:** асистент отримає **усі дані від цієї початкової точки далі**, без верхньої межі у вказаному напрямку.
* **Якщо задано лише кінець:** асистент читатиме дані **від початку аркуша до вказаної кінцевої точки**.

**Приклад:**

Виклик `get_info_from_table('<<spreadsheet id>>', 2, None, 2, 5, 'a', 'd')` отримує всі дані, починаючи з рядка 2, стовпця 2 (B), до рядка 5 і між стовпцями A та D.
{% endhint %}

{% hint style="warning" %}

## Зверніть увагу

Щоб оптимізувати продуктивність і надійність, ми рекомендуємо **кешувати всі дані** з вашої Google-таблиці у змінні проєкту під час роботи з нею.

**Основні переваги:**

1. **Покращена продуктивність:** значно пришвидшує час відповіді чат-бота завдяки доступу до локальних змінних замість запиту до зовнішньої таблиці для кожного звернення.
2. **Підвищена надійність:** мінімізує помилки, пов’язані із затримкою мережі, квотами API або дозволами на доступ до таблиці.
3. **Узгодженість даних:** зберігання даних у налаштуваннях проєкту забезпечує **одночасний і узгоджений доступ для всіх користувачів** до одного й того самого набору даних, запобігаючи розбіжностям під час оновлень.
   {% endhint %}

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

{% hint style="info" %}
Ви можете прочитати більше про **get\_info\_from\_table** функцію в статті "[Google Sheets для AI Assistant](/doc/uk/chatbot/ai/google-tablici-dlya-ai-asistenta.md)."
{% endhint %}

## Як керувати онлайн-бронюванням

get\_info\_for\_booking(slot\_interval, company\_id) — функція призначена для зчитування даних про послуги з налаштованої системи онлайн-бронювання.

Вона приймає необов’язкові параметри:

1. slot\_interval (необов’язковий) — інтервал у хвилинах між доступними часовими слотами. Очікуваний формат: ціле число, кратне 5. Значення за замовчуванням: 60 (хвилин).
2. company\_id необов’язковий) — ідентифікатор філії. Очікуваний формат: *ціле число* або *масив цілих чисел*. Якщо цей параметр задано, буде повернуто лише дані для вказаної філії (філій).
   \
   Приклад: 50142, "50142" або "\[50142, 66352]"

{% hint style="warning" %}
Не рекомендується задавати дуже мале значення (наприклад, менше 30), оскільки асистент згенерує забагато часових слотів. &#x20;
{% endhint %}

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

Спочатку потрібно підготувати блок, який оновлює інформацію про всі послуги після того, як налаштування філії буде задано в розділі "Послуги".

Цей блок потрібно оголосити до початку роботи асистента, щоб AI не генерував випадкові відповіді.

<div data-with-frame="true"><figure><img src="/files/4d8a019736f14264845ca6d999832f5699c1f77e" alt=""><figcaption></figcaption></figure></div>

Далі запустіть блок у вікні тестування бота, щоб оновити змінну:

<div data-with-frame="true"><figure><img src="/files/61323299a91726f530cc5e4af0b1530344003edc" alt="" width="375"><figcaption></figcaption></figure></div>

Після цього вказана змінна, що містить дані сервісу онлайн-бронювання, з’явиться в розділі змінних проєкту в "Налаштуваннях проєкту."

<div data-with-frame="true"><figure><img src="/files/ad2f75cb305230d4456684e69ea792c3f2f9bc9a" alt="" width="563"><figcaption></figcaption></figure></div>

Ця змінна зберігає значення послуг, які AI-бот використовуватиме у своїй роботі. Змінна service\_info буде доступна всім клієнтам проєкту.

Далі перейдемо до налаштування наступного блока.

<div data-with-frame="true"><figure><img src="/files/c31cfb5e4fa64ab86269920e049798c87de79117" alt=""><figcaption></figcaption></figure></div>

Цей блок виконує такі функції:

а) він викликається в налаштуваннях асистента для створення запису з використанням змінних, пов’язаних із послугами;

b) він створює бронювання для клієнта;

c) оновлює змінні проєкту після бронювання, видаляє часові слоти, які більше недоступні в розкладі.

Якщо бот налаштовано правильно, після отримання всіх даних від клієнта AI надішле інформацію до вказаного блока. У цьому блоці клієнта буде записано на послугу за допомогою функції create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

<div data-with-frame="true"><figure><img src="/files/aa93212de7aeb2a61f927f90dec736a303e1a8bd" alt=""><figcaption></figcaption></figure></div>

Значення, зібрані ботом, передаються як параметри до create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

Функція create\_booking\_by\_name(service\_name, date, date\_time, company\_id) створює бронювання в системі, використовуючи дані, надані AI-асистентом. Вона приймає три обов’язкові параметри для створення бронювання:

<table><thead><tr><th width="297">Параметри</th><th>Опис</th></tr></thead><tbody><tr><td>! service_name</td><td>обов’язковий параметр, назва послуги</td></tr><tr><td>! date</td><td>дата у форматі dd.mm.yyyy</td></tr><tr><td>! date_time</td><td>час послуги у форматі hh:mm</td></tr><tr><td>company_id </td><td>ідентифікатор філії, необов’язково.
<br>Якщо вказано, бронювання буде створено для послуги з указаною назвою, що належить саме цій філії.
<br>Цей параметр може бути потрібен у випадках, коли в кількох філіях є послуги з однаковою назвою.</td></tr></tbody></table>

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

<div data-with-frame="true"><figure><img src="/files/e5e3eb7083f25928948b747d727e1cec49da75c6" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## Зверніть увагу

Якщо в розкладі, персоналі або послугах є будь-які зміни, запустіть блок, який містить змінну проєкту з вбудованою функцією, у тестовому режимі (див. рис. Блок 1).
{% endhint %}

{% hint style="info" %}
[Як налаштувати AI-бота для онлайн-бронювання, описано в однойменній статті.](/doc/uk/chatbot/ai/online-booking.md)
{% endhint %}

## Отримання бронювання з таблиці

get\_records\_from\_table(table\_id, start\_row, count, start\_col, end\_col) — отримання бронювання з таблиці

| Параметр   | Опис                                                                          | Примітка                                                                                    |
| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| table\_id  | ідентифікатор таблиці                                                         |                                                                                             |
| start\_row | необов’язковий параметр, ціле число. Визначає початок діапазону рядків.       | Вкажіть номер рядка, з якого слід читати значення таблиці включно. Вказується без лапок.    |
| count      | необов’язковий параметр, ціле число. Визначає кількість рядків для отримання. | За замовчуванням — 1000, максимум — 5000. Вказується без лапок.                             |
| start\_col | необов’язковий параметр, рядок. Визначає початок діапазону стовпців.          | Вкажіть літеру стовпця, з якого слід читати значення таблиці включно. Вказується в лапках.  |
| end\_col   | необов’язковий параметр, рядок. Визначає кінець діапазону стовпців.           | Вкажіть літеру стовпця, до якого слід читати значення таблиці включно. Вказується в лапках. |

Якщо вказано лише початок діапазону рядків або стовпців, усі дані від цієї точки далі будуть отримані без верхньої межі діапазону. Аналогічно можна опустити початок і вказати лише кінець діапазону.

### Приклад (калькулятор)

Якщо вам потрібно отримати записи з таблиці, відкрийте розділ "Калькулятор" у налаштуваннях блока та введіть функцію з потрібними параметрами.

<div data-with-frame="true"><figure><img src="/files/e44c484c22b0733a8bd433bae65cc73f58623dd0" alt=""><figcaption></figcaption></figure></div>

Щоб передати параметри як змінну проєкту, додайте перед назвою змінної, що містить функцію, префікс **project**.

<div data-with-frame="true"><figure><img src="/files/69c5ad6c20175cd7234bd37f4f34900f630a88a5" alt=""><figcaption></figcaption></figure></div>

Ось приклад таблиці.

<div data-with-frame="true"><figure><img src="/files/7a804d6289f923234db46b798e09428b36bad9ca" alt="" width="563"><figcaption></figcaption></figure></div>

Бот відповість так:

<div data-with-frame="true"><figure><img src="/files/ddca714023d2ad4641e5ae31e99c78ddeb62fee6" alt="" width="375"><figcaption></figcaption></figure></div>


---

# Agent Instructions: 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.mavibot.ai/doc/uk/chatbot/ai/functions.md?ask=<question>
```

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.