# Функції (API) у калькуляторі

{% hint style="warning" %}
API-функції доступні лише в планах "Business" і "MaviBot AI".
{% endhint %}

## API MaviBot

<mark style="color:red;">**ЛЕГЕНДА:**</mark>\ <mark style="color:red;">**!**</mark> -Обов'язкові параметри

### Як надіслати callback

#### **callback()**

{% hint style="danger" %}
Ви можете надіслати callback лише ІНШОМУ клієнту.

ВИ НЕ МОЖЕТЕ надіслати callback САМОМУ СОБІ!
{% endhint %}

<details>

<summary>Опис</summary>

**callback(client\_id, callback\_message)**

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;client\_id** - ідентифікатор клієнта

<mark style="color:red;">**!**</mark>**&#x20;callback\_message** - текст повідомлення callback

</details>

<details>

<summary>Приклад</summary>

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

Давайте надішлемо callback клієнту з client\_id=73704021

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

Далі ми задаємо відповідь на цей callback у блоці з умовою.

</details>

<details>

<summary>Приклад коду для копіювання</summary>

```
callback('73704021', 'callback TEST123')

callback(client_id, 'callback TEST123')
```

</details>

### Як надіслати callback у Telegram

#### **tg\_callback()**

<details>

<summary>Опис</summary>

**tg\_callback(platform\_id , callback\_message,group\_id, business\_connection\_id)**

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** -  ідентифікатор клієнта Telegram

<mark style="color:red;">**!**</mark>**&#x20;callback\_message** - текст повідомлення callback

&#x20;**group\_id** -  ідентифікатор бота Telegram

**tg\_business -** для роботи з бізнес-клієнтами передається значення "1".

</details>

<details>

<summary>Приклад</summary>

Це приклад з обов'язковими параметрами:

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

Це приклад з необов'язковими параметрами

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

</details>

<details>

<summary>Приклад коду для копіювання</summary>

```
tg_callback('73704021', 'callback TEST123')

tg_callback(platform_id, 'callback TEST123', None, 1)
```

</details>

### Як додати редирект бота з тегом у відповідь на кнопку callback?

<details>

<summary>Опис</summary>

**tg\_callback\_url\_open(callback\_query\_id, url)**

Параметри: \ <mark style="color:red;">**!**</mark>**&#x20;callback\_query\_id** - цей id дозволяє вам ідентифікувати людину, яка натиснула кнопку, і показати їй сповіщення Alert,\ <mark style="color:red;">**!**</mark>**&#x20;url** - URL — адреса бота та параметр (виглядає так: t.me/your\_bot?start=XXXX, замість your\_bot — назва бота)

</details>

### **Як надіслати повідомлення клієнту**

**message() | platform\_message() | whatsapp\_message()**

{% hint style="info" %}
Щоб зберегти текст із переносами рядків у змінну, задайте значення так:

`text = "Текст першого рядка" + "\n" + "Текст другого рядка" + "\n" +"Текст третього рядка"`
{% endhint %}

<details>

<summary>Опис</summary>

**message(client\_id, text, message\_id, timeout)**

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;client\_id** - ідентифікатор клієнта\ <mark style="color:red;">**!**</mark>**&#x20;text** - текст повідомлення\
**message\_id** - ID блоку. Якщо ви залишите поле тексту порожнім (") і заповните цей параметр, клієнту буде надіслано текст із вказаного блоку.

*Примітка: якщо ви передасте параметр message\_id у функцію message, блок усе одно буде повністю виконано, а клієнт, вказаний у параметрі client\_id, буде переміщений у блок, який ви передали в message\_id.*

\
**timeout** - затримка повідомлення або запланований час надсилання. Ви можете використовувати параметр timeout, щоб затримати надсилання повідомлення:\
a) Затримка в секундах (до 3600 секунд). Якщо значення перевищує 3600, повідомлення буде надіслано за одну годину. Якщо значення від'ємне, повідомлення буде надіслано негайно. Приклад: timeout = 50                                                                                                                 &#x20;

b) Конкретна дата й час у форматі dd.mm.yyyy hh:mm, приклад: timeout = '03.04.2022 15:00' . Якщо вказано дату в минулому, повідомлення буде надіслано негайно.

**platform\_message(platform\_id, text, client\_type,  message\_id, timeout,group\_id)**

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;platform\_id** -  ідентифікатор клієнта в месенджері\ <mark style="color:red;">**!**</mark>**&#x20;text** - текст повідомлення\
**client\_type -** тип месенджера, необов'язковий параметр. Якщо його не вказано, клієнта буде знайдено в тому самому месенджері, з якого бот надсилає повідомлення. Якщо його вказано, клієнта буде знайдено серед бази даних зазначеного месенджера. Ви можете знайти типи месенджерів [тут.](/doc/uk/chatbot/functions/zminni.md#how-to-work-with-variables)\
**message\_id** - ID блоку. Якщо його вказано, клієнт отримає повідомлення з указаного блоку, а не значення з параметра text.\
**timeout** - час надсилання або затримка. Це аналогічно параметру з однаковою назвою у функції message().\
**group\_id** - ідентифікатор бота

**whatsapp\_message(phone, text, message\_id)**

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;phone**- номер телефону клієнта, на якому зареєстровано Whatsapp\ <mark style="color:red;">**!**</mark>**&#x20;text** - текст повідомлення\
**message\_id** -це ID блоку. Якщо поле text залишити порожнім (''), і цей параметр задано, клієнт отримає вміст повідомлення з указаного блоку.

{% hint style="info" %}
Whatsapp-бот потрібно підключити до проєкту.
{% endhint %}

</details>

<details>

<summary>Приклад</summary>

Простий приклад надсилання повідомлення за client\_id:

<div data-with-frame="true"><figure><img src="/files/b2cb650044f9b9f0b6f58d7255b41ef7a92a12fc" alt="" width="563"><figcaption><p>Надсилання повідомлення за client_id</p></figcaption></figure></div>

Різні варіанти надсилання повідомлення за client\_id:

<div data-with-frame="true"><figure><img src="/files/c106c149a917c88ee83888d4aecd3eb3deaef98e" alt="" width="563"><figcaption><p>Різні варіанти надсилання повідомлення </p></figcaption></figure></div>

Приклад надсилання повідомлення через platform\_message():

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

</details>

<details>

<summary>Приклад коду для копіювання</summary>

```
/*Надсилання повідомлення за client_id*/
message(73704021, 'Текст повідомлення для клієнта')
/*Надсилання повідомлення за client_id із затримкою 30 секунд*/
message(73704021, 'Привіт! Дякуємо за звернення..','',30)
/*Надсилання повідомлення з блоку 3190 клієнту з client_id 03.04.2022 о 15:00*/
message(73704021, '',3190, '03.04.2022 3pm')

/*Надсилання повідомлення у Whatsapp*/
whatsapp_message('79999999999', 'Текст повідомлення для клієнта')
```

</details>

### Отримання client\_id за значенням platform\_id

get\_client\_id\_by\_platform\_i&#x64;**()**

<details>

<summary>Опис</summary>

**get\_client\_id\_by\_platform\_id(client\_type, platform\_id , group)**&#x20;

Після виконання функція поверне client\_id, якщо буде знайдено клієнта, що відповідає вказаним умовам; інакше вона поверне None.

<mark style="color:red;">**!**</mark> **client\_type** - месенджер. Для значення client\_type дивіться [цю статтю](/doc/uk/chatbot/functions/zminni.md).&#x20;

<mark style="color:red;">**!**</mark> **platform\_id** - ID клієнта в зазначеному месенджері.

**group**  - є обов'язковим параметром, якщо підключено більше одного бота месенджера.

{% hint style="warning" %}
Якщо в проєкті підключено кілька месенджерів одного типу, пошук буде виконуватися по всіх підключених месенджерах цього типу.

У цьому випадку ми рекомендуємо передавати параметр group.
{% endhint %}

</details>

### Функція для GET-запитів:  requests\_get(url, answer\_type, headers, params, auth, proxy)&#x20;

<details>

<summary>Опис</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - це посилання, куди надсилається запит

**answer\_type**  – це необов'язковий параметр, який визначає, що має бути повернуто з відповіді сервера: ('status' – повертає код статусу відповіді; 'json' – повертає JSON-тіло відповіді; 'text' – повертає сирий текст відповіді; будь-яке інше значення (включно зі стандартним) повертає відповідь у форматі: '{"status": status\_code, "data": data}')

**headers** - це необов'язковий параметр для передавання заголовків запиту,&#x20;

**params** - це *get* параметри запиту (також можуть бути включені безпосередньо в URL),

**auth** - це необов'язковий параметр, корисний для автентифікації API. Якщо ви не хочете використовувати жоден необов'язковий параметр, але вам потрібен наступний, передайте тут 0.

**proxy** -  це необов'язковий параметр; приймає одне значення: "de", яке спрямовує запит через європейську IP-адресу.

</details>

### Функції для POST-запитів

<details>

<summary>Опис</summary>

requests\_post(url, answer\_type, headers, data, json\_data, auth, proxy)

<mark style="color:red;">**!**</mark>**&#x20;url** - це посилання, куди надсилається запит,

**answer\_type** - це необов'язковий параметр, який визначає, що має бути повернуто з відповіді сервера: ('status' – повертає код статусу відповіді; 'json' – повертає JSON-тіло відповіді; 'text' – повертає сирий текст відповіді; будь-яке інше значення (включно зі стандартним) повертає відповідь у форматі: '{"status": status\_code, "data": data}')

**headers** - це необов'язковий параметр для передавання заголовків запиту

**data** - це необов'язковий параметр; являє собою тіло запиту, коли API не працює з json.

&#x20;**json\_data** - це необов'язковий параметр; також являє собою тіло запиту. Слід використовувати лише один із цих параметрів за раз.

{% hint style="warning" %}
Зверніть увагу: деякі конфігурації заголовків можуть блокувати надсилання запиту з певним типом тіла.
{% endhint %}

**auth** - це необов'язковий параметр, корисний для автентифікації API. Якщо ви не хочете використовувати жоден необов'язковий параметр, але вам потрібен наступний, передайте тут 0

**proxy** - це необов'язковий параметр; приймає одне значення: "de", яке спрямовує запит через європейську IP-адресу.

</details>

### Функції для PUT-запитів

<details>

<summary>Опис</summary>

requests\_put(url, answer\_type, headers, data, auth, proxy)

<mark style="color:red;">**!**</mark>**&#x20;url** - це посилання, куди надсилається запит

**answer\_type** - це необов'язковий параметр, який визначає, що має бути повернуто з відповіді сервера: ('status' – повертає код статусу відповіді; 'json' – повертає JSON-тіло відповіді; 'text' – повертає сирий текст відповіді; будь-яке інше значення (включно зі стандартним) повертає відповідь у форматі: '{"status": status\_code, "data": data}')

**headers** - це необов'язковий параметр для передавання заголовків запиту

**data** - це необов'язковий параметр; являє собою тіло запиту, коли API не працює з json.

**auth** - це необов'язковий параметр, корисний для автентифікації API. Якщо ви не хочете використовувати жоден необов'язковий параметр, але вам потрібен наступний, передайте тут 0

proxy - це необов'язковий параметр; приймає одне значення: "de", яке спрямовує запит через європейську IP-адресу.

**data\_is\_json** це необов'язковий параметр.\
Якщо його встановлено, дані, передані в `data` будуть надіслані у форматі JSON.\
Щоб увімкнути його, передайте `'1'`.

</details>

### Функції для PATCH-запитів

requests\_patch(url, answer\_type, headers, data, auth, proxy)

<details>

<summary>Опис</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - це посилання, куди надсилається запит

**answer\_type** - це необов'язковий параметр, який визначає, що має бути повернуто з відповіді сервера: ('status' – повертає код статусу відповіді; 'json' – повертає JSON-тіло відповіді; 'text' – повертає сирий текст відповіді; будь-яке інше значення (включно зі стандартним) повертає відповідь у форматі: '{"status": status\_code, "data": data}')

**headers** - це необов'язковий параметр для передавання заголовків запиту

**data** - це необов'язковий параметр; являє собою тіло запиту, коли API не працює з json.

**auth** - це необов'язковий параметр, корисний для автентифікації API. Якщо ви не хочете використовувати жоден необов'язковий параметр, але вам потрібен наступний, передайте тут 0

proxy - це необов'язковий параметр; приймає одне значення: "de", яке спрямовує запит через європейську IP-адресу.

</details>

### Функції для DELETE-запитів

requests\_delete(url, answer\_type, headers, data, json\_data, auth, proxy)

<details>

<summary>Опис</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - це посилання, куди надсилається запит

**answer\_type** - це необов'язковий параметр, який визначає, що має бути повернуто з відповіді сервера: ('status' – повертає код статусу відповіді; 'json' – повертає JSON-тіло відповіді; 'text' – повертає сирий текст відповіді; будь-яке інше значення (включно зі стандартним) повертає відповідь у форматі: '{"status": status\_code, "data": data}')

**headers** - це необов'язковий параметр для передавання заголовків запиту

data -  це необов'язковий параметр; являє собою тіло запиту, коли API не працює з json.

json\_data - це необов'язковий параметр і також може використовуватися як тіло запиту. Однак одночасно слід використовувати лише один варіант

auth - це необов'язковий параметр, корисний для автентифікації API. Якщо ви не хочете використовувати жоден необов'язковий параметр, але вам потрібен наступний, передайте тут 0

proxy - це необов'язковий параметр; приймає одне значення: "de", яке спрямовує запит через європейську IP-адресу.

</details>

### Функція для отримання назви блоку за його ID

<details>

<summary>Опис</summary>

get\_block\_name\_by\_id(block\_id)

<mark style="color:red;">**!**</mark>**&#x20;block\_id** — ідентифікатор блоку (id)&#x20;

</details>


---

# 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/functions/api.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.