# Конструктор API

Деякі функції API-запитів можна запускати в Калькуляторі.

Запити надсилаються через **POST** або **GET** метод до URL у такому форматі:

**<https://chatter.mavibot.ai/api/{api\\_key}/{action}>**

Де:

**api\_key** — ключ доступу до API, згенерований у налаштуваннях проєкту.

<figure><img src="/files/02e8296a12172f8fa79d462db4da3cf4d3c7586d" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Щоб використовувати токен у URL-запиті, спочатку потрібно згенерувати API-ключ.

Інструкції з цього наведено в розділі "Генерація API-ключа". <mark style="color:red;">**посилання**</mark>
{% endhint %}

{% hint style="danger" %}
Під час копіювання URL із цієї сторінки може з’явитися пробіл, який потрібно видалити.

Приклад неправильного посилання:
&#x20;<https://chatter.mavibot.pro> /api/callback

Якщо пробіл після .pro залишиться, запит не спрацює.
{% endhint %}

{% hint style="warning" %}
Не використовуйте заборонені символи під час надсилання GET-запиту.

Переконайтеся, що ви розумієте правильний формат GET-запитів.
{% endhint %}

## **Як згенерувати API-ключ**

{% hint style="success" %}
Стара функція генерації API-ключа все ще працює як і раніше, але недоступна для нових проєктів.

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

Якщо вам потрібно згенерувати нові ключі, використовуйте оновлені налаштування.
{% endhint %}

Щоб згенерувати API-ключ, перейдіть до налаштувань проєкту:

<figure><img src="/files/292322914b0d48370447c3eb6a1ec2bc0008307f" alt="" width="301"><figcaption></figcaption></figure>

Далі перейдіть до розділу "Інтеграції":

<figure><img src="/files/2a41d35f9aac1506eeba030426d0a1cc42019dcd" alt="" width="563"><figcaption></figcaption></figure>

У розділі "Інтеграції" ви знайдете кнопку "Додати API-ключ":

<figure><img src="/files/7bae63a66c6651543f21391e9337b2778f84ca7e" alt=""><figcaption></figcaption></figure>

Після натискання кнопки відкриється модальне вікно з налаштуваннями доступу та опціями генерації API-ключа:

<figure><img src="/files/9c70adc15067af49954b83f06d0061c31be89ab6" alt=""><figcaption></figcaption></figure>

Далі потрібно вибрати права доступу для API-ключа:

<figure><img src="/files/3e618d547626a7c1c1318dcb074c0621827245ff" alt=""><figcaption></figcaption></figure>

Функція API працюватиме відповідно до вибраних вами прав доступу.

{% hint style="warning" %}
Зверніть увагу!

Функція API залежить від установлених вами прав доступу: якщо ви згенеруєте API-ключ із доступом лише для читання до інформації про клієнта, а потім використаєте його для надсилання повідомлення клієнту або зміни його змінних, API-запит завершиться помилкою.
\
Необхідний дозвіл для кожного API-запиту вказано на картці API-запиту:

<img src="/files/4a3411ffb77b10c07188a2716ee33905867a2859" alt="" data-size="original">
{% endhint %}

Далі введіть назву для API-ключа:

<figure><img src="/files/f891d6c5a439cdf11adaf47395f89e7d57bf9309" alt=""><figcaption></figcaption></figure>

Згенеруйте API-ключ, натиснувши кнопку "Згенерувати":

<figure><img src="/files/1b5c033b68f8048a87b13987d304f6b9f5843f23" alt=""><figcaption></figcaption></figure>

Після чого натисніть "Готово", і ключ api буде додано до розділу:

<figure><img src="/files/f2933097c41d33cbeb39d927a57c279751eba41b" alt=""><figcaption></figcaption></figure>

Ви можете додати стільки API-ключів, скільки потрібно, призначаючи кожному різні права доступу.

<figure><img src="/files/a416fa1723fee73eb68e4d0f65ab2a7e129a2a48" alt=""><figcaption></figcaption></figure>

Далі потрібно встановити основний ключ проєкту. Це дає змогу використовувати ключ у URL-запиті з підстановкою #{api\_key}.

Для цього натисніть кнопку "{+}" праворуч від потрібного API-ключа:

<figure><img src="/files/c4b9fbd38719f3ccbee0990aedb5fb226dec39f6" alt=""><figcaption></figcaption></figure>

Після цього поруч із ключем з’явиться мітка, що вказує на те, що це основний ключ проєкту.

<figure><img src="/files/c9fa2fd7cee614dd881f0b27cc55a163cb7798db" alt=""><figcaption></figcaption></figure>

Ви можете отримати доступ до основного ключа проєкту через api\_key: просто згенеруйте потрібний ключ, налаштуйте його права та призначте його основним ключем проєкту. Потім у Калькуляторі використовуйте URL-запиту з підстановкою #{api\_key}, яка міститиме значення основного ключа проєкту.

<figure><img src="/files/7389827980db3270e25b7f2595305a40a709412c" alt=""><figcaption><p>URL-запиту</p></figcaption></figure>

<figure><img src="/files/e2af085903f1a6002910c3791d64073732618b3a" alt=""><figcaption></figcaption></figure>

Будь-які інші згенеровані ключі з налаштуваннями доступу вважатимуться другорядними ключами. У URL-запиті ви можете використовувати їхнє значення замість #{api\_key}. Для цього скопіюйте значення другорядного ключа:

<figure><img src="/files/a3b0474ed5a9227a1ffc0d10b8e39473e341a68e" alt=""><figcaption></figcaption></figure>

і вставте його в URL-запит замість #{api\_key}:

<figure><img src="/files/a25b0982c067860aa30ec9bbd0a17c89246c7c50" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
API-ключ, згенерований старим методом, за замовчуванням встановлюється як основний ключ проєкту та має повні права.
{% endhint %}

{% hint style="danger" %}
Увага!&#x20;

Якщо ви видалите ключ, встановлений як основний ключ проєкту, вам потрібно буде вручну призначити новий ключ основним.
{% endhint %}

{% hint style="success" %}
Зверніть увагу!&#x20;

Якщо у вас є API-ключі, згенеровані старим методом, вони й надалі працюватимуть нормально. Згенерувати нові API-ключі старого типу неможливо.
{% endhint %}

## Як отримувати повідомлення на Webhook URL, вказаному в налаштуваннях проєкту

![Налаштування проєкту](/files/931830b7e523ce07ab22eb47105c5aca05a8d315)

Кожне вхідне або вихідне повідомлення буде надіслано як такий JSON POST-запит:

```
{
    "id": "ID повідомлення в системі",
    "client": {
        "id": "ID клієнта в системі",
        "recepient": "ID клієнта в месенджері",
        "client_type": "тип месенджера",
        "name": "ім’я клієнта",
        "avatar": "аватар клієнта",
        "created_at": "дата створення клієнта",
        "tag": "ключ підписки",
        "group": "бот, до якого прив’язаний клієнт"
    },
    "message": "текст повідомлення",
    "attachments": "масив, що містить посилання на файли або словники посилань на файли",
    "message_id": "ID блоку, з якого було надіслано повідомлення",
    "project_id": "ID проєкту",
    "is_input": "1, якщо повідомлення від клієнта, 0, якщо від бота",
    "delivered": "1, якщо повідомлення успішно надіслано, 0, якщо сталася помилка",
    "error_message": "текст помилки доставки повідомлення"
}
```

Якщо запит повертає помилку, повторно він не буде надісланий. Навіть якщо сервер повертає помилки, сповіщення й надалі надсилатимуться.

### Як створити JSON-запит

Перейдіть до налаштувань блоку, де дані будуть записані в таблицю.&#x20;

<figure><img src="/files/260f7cf6017225b9d9f5d33c4183669234587fa4" alt=""><figcaption></figcaption></figure>

1. Додайте розділ API Request.
2. Виберіть POST-JSON як тип запиту.
3. Потім заповніть поля запиту:

<figure><img src="/files/c9afe3c344a59e3a6acde59acc169b144c839c8f" alt=""><figcaption></figcaption></figure>

**URL-запиту** — шлях до функції, яку потрібно викликати. У документації це завжди показано в першому рядку поруч із типом запиту:

<figure><img src="/files/b4332f3ddadf004f00785b1d5d6f4c2b6d5a9d89" alt=""><figcaption></figcaption></figure>

**Збережені значення** — список параметрів відповіді з назвами змінних, у яких потрібно зберегти результати, у такому форматі:

> **request\_parameter -> your\_variable**
>
> Якщо відповідь містить параметри зі складною структурою, розбирайте їх так:
>
> * > "cell\_number":{"row":4,"col":2}\
>   > \
>   > \
>   > cell\_number|row ->String; \
>   > cell\_number|col -> Column<br>

**Заголовки запиту** — заповніть за потреби. Зазвичай це включає формат даних і/або токен доступу.

**JSON-параметри** — тіло запиту, де ви вказуєте параметри даних у форматі JSON. Приклад:

**{"client\_id": "#{recipient\_id\_in\_builder}", "message":"Привіт!"}**

Щоб зрозуміти структуру відповіді, запишіть #{custom\_answer} у поле Message, щоб вивести значення змінної.<br>

<figure><img src="/files/9ed318f3105dc74f0cf185541afeeda3b3687bf4" alt=""><figcaption><p>Отримання результату API-запиту як повідомлення</p></figcaption></figure>

Далі в документації наведено дозволені параметри в розділі "Body":&#x20;

<figure><img src="/files/82827e876b3628e9246e98509d203a177ddc0153" alt="" width="551"><figcaption></figcaption></figure>

## Як використовувати універсальний webhook

Перелічені методи тепер можна виконувати як POST- або GET-запити.

* [callback](#zapusk-bota)
* [whatsapp\_callback](#zapusk-bota)
* [message](#otpravka-soobshenii)
* [whatsapp\_message](#otpravka-soobshenii)

Раніше наші методи мали фіксовані параметри (наприклад, **client\_id** та **fb\_id**), які використовувалися для запуску дій підписника, що створювало певні обмеження під час інтеграції зі сторонніми сервісами.

Тепер ви можете вказати, який параметр запиту SaleBot має використовувати для пошуку ID користувача. Використовуйте параметр із префіксом **value\_**, наприклад, **value\_user\_id** або **value\_group\_id**.

Крім того, метод надсилання callback тепер можна запускати також за email клієнта (**client\_email**) або номером телефону (**client\_phone**).

{% hint style="success" %}
Поле **callback**, **fb\_callback**, і **whatsapp\_callback** методи не прив’язані до конкретних назв параметрів. Ви можете вказати, який параметр містить номер телефону, email або ID клієнта.
{% endhint %}

Це корисно під час налаштування приймання webhook із вебсайту.

**Щоб вказати, яка змінна містить client\_id** , використовуйте параметр value\_client\_id і вкажіть назву параметра, що містить це значення.

**Щоб вказати, яка змінна містить номер телефону** , використовуйте value\_phone.

**Щоб вказати, яка змінна містить email,** використовуйте value\_email.

**Щоб вказати, яка змінна містить user\_id** , використовуйте value\_user\_id.

**Щоб вказати, яка змінна містить group\_id** , використовуйте value\_group\_id.

**Щоб вказати змінну, яка містить саме повідомлення у webhook** , використовуйте value\_message (передається так само, як і інші параметри).

Приклад:

В адресі вкажіть value\_client\_id = my\_client.

`https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback?value_client_id=my_client`\
`{"my_client":49177759, "message":"Hello world"}`

Запит буде еквівалентний наведеному нижче:

`https://chatter.mavibot.pro/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback`\
`{"client_id":49177759, "message":"Hello world"}`

Як бачите, назва параметра, що містить значення, має префікс **value\_**.

{% hint style="warning" %}
Зверніть увагу!&#x20;

Деякі події генерують системні сповіщення всередині проєкту.

Наприклад, є системні сповіщення з полем message, яке не є порожнім, але не містить тексту клієнта.

Водночас проєкт може також генерувати хуки повідомлень із певним вмістом, наприклад "message: new\_chat\_member".

Тому важливо перевіряти вміст: це буде або системне сповіщення, або хук для певної події.
{% endhint %}

## Як запустити бота

### Запустити бота

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/callback</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/callback><br>

Цей метод можна використовувати для запуску воронки для клієнта або підтвердження дії на зовнішньому ресурсі. Клієнт не побачить це повідомлення.<br>

**Зверніть увагу: усі додатково передані вами параметри буде збережено в змінній**

Метод callback тепер також можна запускати за email клієнта (client\_email) або номером телефону (client\_phone).

Права доступу під час генерації ключа: **"Право змінювати/видаляти інформацію про клієнта"**.

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

client\_phone - номер телефону, який використовується для пошуку клієнта

client\_email - email, який використовується для пошуку клієнта

client\_id - ID клієнта в конструкторі

message - текст повідомлення

resume\_bot - True (необов’язковий параметр). Якщо бот призупинено, це використовується, щоб зняти паузу.&#x20;

Приклад: resume\_bot = True

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

```
import requests
import json

params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.salebot.pro/api/{token}/callback'
requests.post(url, json=params)
```

</details>

### Запуск бота за допомогою номера WhatsApp

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/whatsapp_callback</summary>

URL-запиту: <https://chatter.mavibot.ai/api/\\>\<api\_key>/whatsapp\_callback

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

**Зверніть увагу: усі додатково передані вами параметри буде збережено в змінній**

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

name - ім’я клієнта\
message - текст повідомлення\
phone - номер телефону клієнта\
bot\_id - ID бота\
resume\_bot - True (необов’язковий параметр). Якщо бот призупинено, використовуйте це, щоб продовжити роботу. Приклад: resume\_bot = True

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

</details>

### Запуск бота за допомогою Telegram ID

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.pro/api/#{api_key}/tg_callback</summary>

URL-запиту: <https://chatter.mavibot.pro/api/#{api\\_key}/tg\\_callback>

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

**Зверніть увагу: усі додатково передані вами параметри буде збережено в змінних.**

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

message - текст повідомлення\
user\_id - Telegram ID користувача\
group\_id - назва бота (закінчується на bot)\
resume\_bot - True (необов’язковий параметр). Якщо бот призупинено, використовуйте це, щоб продовжити роботу. Приклад: resume\_bot = True

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

</details>

### Надсилання callback-повідомлень списку клієнтів за platform\_id

<details>

<summary><mark style="color:green;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/send\\_callback\\_by\\_platform\\_id>

Коли в проєкті знайдено клієнтів із platform\_id зі списку, буде надіслано callback із текстом із поля callback\_text.\
\ <mark style="color:red;">**Ліміт: 1 запит = максимум 300 надсилань**</mark>&#x20;

Приклад параметрів запиту:\
{"platform\_ids":\[407184121, "79609879898", "2rwewefw"], "callback\_text": "test\_callback"}

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

platform\_ids - список ID клієнтів у месенджері\
callback\_text - текст callback\
group\_id - ID бота

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

</details>

### Надсилання callback-повідомлення клієнту за email

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/email_callback</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/email\\_callback>

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

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Зверніть увагу: усі додатково передані вами параметри буде збережено в змінній**

Шлях

api key\* - токен доступу

Тіло

name - ім’я клієнта\
message - текст повідомлення\
email - адреса email\
email\_id\_bot - email-адреса бота\
resume\_bot - True (необов’язковий параметр).&#x20;

Якщо бот призупинено, використовуйте це, щоб продовжити роботу. Приклад: resume\_bot = True

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

</details>

## Як працювати з повідомленнями

### Параметри надсилання повідомлень

**attachment\_type** — може бути: **image, video, link, file або audio**.
\
Під час надсилання вкладення параметр message є необов’язковим.

**buttons** — визначає кнопки, які будуть прикріплені до повідомлення. Формат кнопок відповідає розширеним налаштуванням кнопок.

Кнопки можна передавати двома способами: з підказкою для месенджерів, які не підтримують кнопки, або без неї.

Приклад параметра buttons:

```
"buttons": {
  "hint": "Цей текст буде відображено в WhatsApp",
  "buttons": [
    {
      "type": "reply",
      "text": "Розкажіть мені про послуги",
      "line": 0,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Ціни на послуги",
      "line": 0,
      "index_in_line": 1
    },
    {
      "type": "reply",
      "text": "Контакти",
      "line": 1,
      "index_in_line": 0
    },
    {
      "type": "reply",
      "text": "Надіслати заявку",
      "line": 1,
      "index_in_line": 1
    }
  ]
}
```

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

<details>

<summary><mark style="color:green;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/message</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/message>

Цей метод можна використовувати для надсилання повідомлень-сповіщень. Параметр message є обов’язковим, якщо ви не надсилаєте файл. Якщо ви надсилаєте файл, текст є необов’язковим.

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

message\_id - номер блоку для надсилання\
message - текст повідомлення\
client\_id - ID клієнта в конструкторі\
attachment\_type - тип відображення файлу. Обов’язковий, якщо вказано attachment\_url.\
attachment\_url - URL файлу\
buttons - кнопки

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

```
import requests
import json

# Надсилання текстового повідомлення
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# Надсилання вкладення
params = {
    "message": "some message",
    "client_id": "1234565",
    "attachment_type": "video/image/file",
    "attachment_url": "https://qwreqw"
}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# У 'attachment_type' вкажіть 'video', 'image' або 'file'
# залежно від типу вкладення: відео, зображення або документ.
```

</details>

### Надсилання повідомлення в WhatsApp

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.salebot.pro/api/&#x3C;api_key>/whatsapp_message</summary>

URL-запиту: <https://chatter.mavibot.pro/api/\\>\<api\_key>/whatsapp\_message

Дає змогу надсилати повідомлення від імені підключеного бота на вказаний номер. whatsapp\_bot\_id потрібно взяти з розділу "Месенджери та чати". Кожному підключеному обліковому запису WhatsApp конструктор призначає унікальний ідентифікатор.

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

Шлях

api key\* - токен доступу

Тіло

message\_id - номер блоку для надсилання\
whatsapp\_bot\_id - ID бота WhatsApp, з якого має бути надіслано повідомлення\
attachment\_url - URL файлу\
attachment\_type - тип відображення файлу. Обов’язковий, якщо вказано attachment\_url.\
message - текст повідомлення\
phone - номер телефону одержувача

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

```
import requests
import json

params = {"message": "some_text", "phone": "79875146788"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/whatsapp_message'
requests.post(url, json=params)
```

</details>

### Масове надсилання повідомлень

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/broadcast</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/broadcast>

Цей метод дає змогу запустити розсилку.

Ви можете використовувати <mark style="color:red;">**одну з наведених нижче взаємовиключних опцій**</mark>:

1. параметр list — розсилку буде надіслано до вказаного списку клієнтів.
2. параметр clients — розсилку буде надіслано масиву ID клієнтів.
3. параметри platform\_ids і group\_id — розсилку буде надіслано масиву platform\_ids (ID месенджера) для вказаного бота (group\_id).
4. Якщо жодного з наведених вище параметрів не надано, розсилку не буде надіслано.

Обов’язкові параметри: message (та/або attachment\_type і attachment\_url) або message\_id.

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

**list** - номер списку, на який потрібно надіслати розсилку

clients - ID клієнтів у конструкторі

message - текст повідомлення

platform\_ids - ID одержувачів у месенджері. Має використовуватися разом із обов’язковим параметром group\_id

group\_id - потрібен лише під час використання platform\_ids. Ігнорується з іншими опціями. Вказує бота для надсилання на задані platform\_ids

attachment\_url - URL файлу

attachment\_type - тип відображення файлу. Обов’язковий, якщо вказано attachment\_url.

buttons - кнопки

message\_id - номер блоку для надсилання

shift — кількість секунд між повідомленнями. За замовчуванням 0.2.

time\_shift - число. Якщо вказано, повідомлення буде надіслано через задану кількість секунд від поточного часу.

send\_time - дата й час у форматі "%Y-%m-%d %H:%M:%S" (наприклад, "2024-10-16 13:15:59"). Це встановлює дату й час надсилання повідомлення. Якщо вказано і time\_shift, і send\_time, пріоритет матиме time\_shift.

```
import requests
import json

params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

### Отримання історії повідомлень

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_history?client_id=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_history?client\\_id=>

Параметр client\_id можна отримати тут. <mark style="color:red;">**посилання**</mark>

Права доступу під час генерації ключа: **"Право читати інформацію про клієнта"**.

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

limit - кількість елементів у відповіді. За замовчуванням: 2000, максимум: 2000

start\_date - дата початку періоду вибірки (обов’язково, якщо вказано stop\_date), формат: dd.mm.yyyy&#x20;

stop\_date - дата завершення періоду вибірки (обов’язково, якщо вказано start\_date), формат: dd.mm.yyyy

```
{
  "status": "success",
  "result": [
    {
      "id": 104500,
      "answered": true,
      "client_replica": false,
      "message_id": 390,
      "message_from_outside": 0,
      "created_at": 1587895014,
      "text": "Няв няв",
      "attachments": {
        
      },
      "delivered": true,
      "error_message": "true",
      "manager_id": 12486,
      "manager_email": "example@mail.com"
    },
  ]
}
```

</details>

### Очистити історію повідомлень

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/clear_history?client_id=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/clear\\_history?client\\_id=>

Видаляє історію чату&#x20;

Права доступу під час генерації ключа: **"Право змінювати/видаляти інформацію про клієнта"**.

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

```
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/clear_history?client_id=85856'
requests.get(url)
```

</details>

## Як призначати клієнтів

### Призначення клієнта співробітнику

<details>

<summary><mark style="color:green;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/assign_to_user</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/assign\\_to\\_user>

Цей метод дає змогу призначити клієнта співробітнику. Параметр email є необов’язковим. Якщо email не вказано, система призначить клієнта за своїм алгоритмом.

Права доступу під час генерації ключа: **"Право змінювати/видаляти інформацію про клієнта"**.

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта\
email - email співробітника (необов’язково)

```
import requests
import json

params = {"client_id":"#{client_id}","email":"xxxxx@mail.ru"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

### Імпорт клієнтів у систему

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/load_clients</summary>

URL-запиту: <https://chatter.mavibot.pro/api/#{api\\_key}/load\\_clients>

Цей метод дає змогу імпортувати клієнтів у систему. Під час завантаження клієнтів WhatsApp ви можете вказати номер у будь-якому форматі, із закінченням @s.whatsapp.net або без нього.

ID групи (group\_id) можна отримати ТУТ через /api/\<api\_key>/connected\_channels. (Якщо client\_type = 13 (телефонія), тоді group\_id є порожнім рядком: ""). <mark style="color:red;">**посилання**</mark>

Тип месенджера, з якого прийшов клієнт (client\_type), можна знайти ТУТ. <mark style="color:red;">**посилання**</mark>

Приклад: \[{"platform\_id":"79875555555","group\_id":34810,"client\_type":6}]

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

platform\_id - номер телефону\
group\_id - ID групи\
client\_type - тип месенджера, з якого прийшов клієнт

```
import requests
import json
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/load_clients'
params = [{ "platform_id": 274827917, "group_id": 169166236, "client_type":0},
{"platform_id":"79538550785@s.whatsapp.net", "group_id": "1hwF7lwEjv4SKYIGFhQnBw==", "client_type": 6}]
requests.post(url, json=params)
# якщо успішно, функція поверне ID та статус додавання для кожного елемента
# приклад відповіді
# {"status":"success","items":[{"platform_id":"700000000@s.whatsapp.net","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}
```

</details>

### Додати клієнтів до списку

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/add_to_list</summary>

URL-запиту: <https://chatter.mavibot.ai/api/\\>\<api\_key>/add\_to\_list

Додає клієнтів до списку

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

list\_id - номер списку\
clients - масив ID клієнтів

Приклад:\
Параметри JSON\
{"list\_id":1170282, "clients":\[411262772, 646410963]}

</details>

### Видалити клієнтів зі списку

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/remove_from_list</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/remove\\_from\\_list>

Видаляє клієнтів зі списку

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

list\_id - номер списку\
clients - масив номерів клієнтів у конструкторі Mavibot (значення client\_id)

</details>

### Отримати список клієнтів

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_clients</summary>

**URL-запиту:** <https://chatter.mavibot.a/aipi/\\>\<api\_key>/get\_clients

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

offset – Зсув від першого елемента

limit – Кількість елементів у відповіді / За замовчуванням: 500, максимум: 500

list – Номер списку

reverse – Вказує зворотне сортування (від найстарішого запису до найновішого). Цей параметр працює лише якщо список не вказано.

Повертає статус і масив елементів.

```
{
"status":"success",
"clients":[{
    "id":44483,
    "platform_id":"146467928",
    "client_type":0,
    "name":null,
    "avatar":null,
    "message_id":null,
    "project_id":1,
    "created_at":1588248599,
    "updated_at":1588248599,
    "custom_answer":null,
    "tag":null,
    "group":"143414131",
    "operator_start_dialog":null
    }
]
}
```

</details>

### Отримати список підписників бота в будь-якому месенджері

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/subscribers</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/subscribers>

Отримує інформацію про клієнта з обраного месенджера.

*<mark style="color:red;">Увага!</mark>* Цей метод не повертає змінні.

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

page
\
tag – Тег, вказаний на сторінці підписки
\
group – ID групи VK, до якої прив’язаний підписник
\
date\_from – Підписка після цієї дати (timestamp)
\
date\_to – Підписка до цієї дати (timestamp)
\
client\_type – ID месенджера, для якого потрібно отримати список підписників. Якщо не вказано, буде повернуто всіх клієнтів

```
[  
  {
    "id": 44886,
    "tag": null,
    "created_at": 1609867984,
    "name": "John Smith",
    "vk_id": "146467928",
    "group": "155824294",
    "variables": null
  },
  {
    "id": 44889,
    "tag": null,
    "created_at": 1609867984,
    "name": "Anna Smith",
    "vk_id": "1609867984",
    "group": "155824294",
    "variables": {
      "utm_source": "some_value"
    }
  }
]
```

</details>

## Як працювати зі змінними

### Призначення змінних

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/save_variables</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/save\\_variables>

&#x20;<mark style="color:green;">**!**</mark>**&#x20;**<mark style="color:$success;">**На цей запит не поширюється жодне обмеження.**</mark>&#x20;

Дає змогу зберігати змінні як у ліді, так і в клієнті.
&#x20;За замовчуванням запит призначення змінних додає їх до змінних угоди.
&#x20;Щоб оновити змінні в профілі клієнта, використовуйте префікс client. Наприклад, для телефону: client.phone.

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Оновити**: Параметр clients дає змогу призначати змінні масово.
\
Приклад: {"client\_id":49177759, "variables":{"client.phone":"88888888888"}}

**Шлях**

api key\* - токен доступу

**Тіло**

clients – масив ID клієнтів для призначення змінних

client\_id – ID клієнта

variables – хеш змінних (пари ключ-значення)

```
import requests
import json

params = {"client_id": "25554", "variables": {"var_name": "var_value"}}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/save_variables'
requests.post(url, json=params)
```

</details>

### Отримати змінні

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_variables?client_id=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_variables?client\\_id=>

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

Приклад: <https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/get\\_variables?client\\_id=49177759>

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

```
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/get_variables?client_id=85856'
requests.get(url)
```

</details>

## Як отримати ID клієнта (client\_id)

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

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_platform_id</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_platform\\_id>

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

platform\_ids - масив ID у месенджері\
group\_id - ID бота

```
[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"ОЛЬГА БЕЛІК",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@belik"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"John Smith",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@jsmith61"}
}]
```

</details>

### Отримати ID клієнта з онлайн-чату

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/online_chat_client_id?recipient=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/online\\_chat\\_client\\_id?recipient=>

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

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

<img src="/files/377f2fb83b97aa71bf8f3dae15b2eaac73b8d48c" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

tag - тег (тег клієнта)\
name - ім’я клієнта\
recipient - ID діалогу на вебсайті

#### Де взяти **recipient?**&#x20;

Ви можете отримати його на вебсайті з онлайн-чатом Mavibot.ai, скористайтеся JS, щоб отримати властивість **MavibotAi.recipient\_id**.

<img src="/files/6aa21aa5c9614112849918a8c27c03750c706ffa" alt="" data-size="original">

```
{ "client_id": 36553 }
```

</details>

### Отримати client\_id за номером WhatsApp

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/whatsapp_client_id?phone=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/whatsapp\\_client\\_id?phone=>

Цей метод повертає ID клієнта для виконання API-запитів, якщо вам відомий номер WhatsApp клієнта.
\
Якщо з таким номером клієнт не існує, метод поверне помилку 404.

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

phone - номер телефону\
group\_id - ID бота

</details>

### Отримати client\_id за номером телефону

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/find_client_id_by_phone?phone= </summary>

URL-запиту: <https://chatter.mavibot.ai/api/\\>\<api\_key>/find\_client\_id\_by\_phone?phone=&#x20;

Цей метод повертає ID клієнта для виконання API-запитів.

Пошук виконується як серед клієнтів WhatsApp, так і через змінні.

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

phone - номер телефону

</details>

### Отримати client\_id за email

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_email?email= </summary>

URL-запит: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_email?email=&#x20>;

Цей метод повертає ID клієнта для виконання API-запитів.
\
Пошук виконується за допомогою змінних.

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

email - email для пошуку

</details>

### Отримати client\_id за значенням змінної

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_client_id_by_var?var=&#x26;val=</summary>

URL-запиту: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_var?var=\\&val=>

Цей метод повертає ID клієнта для виконання API-запитів.

Права доступу під час генерації ключа: "Дозвіл на читання інформації про клієнтів"

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

**var -** назва змінної для пошуку\
**val -** значення змінної\
**group\_id -** ID групи\
**search\_in -** передайте значення 'order' для пошуку в змінних угоди; виконує пошук до трьох змінних для клієнтів проєкту та повертає список клієнтів, у яких є всі вказані змінні.

</details>

### Отримати ID нещодавно створеного клієнта за значенням змінної

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var?var=&#x26;val=</summary>

URL-запит: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_latest\\_client\\_id\\_by\\_var> ?var=\&val=

Цей метод повертає ID нещодавно створеного клієнта для виконання API-запитів. Він шукає як у змінних клієнта, так і в змінних угоди.

Права доступу під час генерації ключа: "Дозвіл на читання інформації про клієнтів"

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

**var -** назва змінної для пошуку\
**val -** значення змінної

</details>

### Отримати список значень client\_id за значенням змінної

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&#x26;val=</summary>

URL-запит: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_var?var=\\&val=>

Цей метод повертає список ID клієнтів, які мають вказану змінну з вказаним значенням.

Права доступу під час генерації ключа: "Дозвіл на читання інформації про клієнтів"

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

**var -** назва змінної для пошуку\
**val -** значення змінної

```
{
    // Відповідь
}
```

</details>

### Отримати список значень client\_id на основі кількох значень змінних

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val</summary>

URL-запит: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_several\\_vars?var=val>

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

variable1 - Значення1

variable2 - Значення2

variable3 - Значення3

```
{
 "status":"success","client_ids":[93891114]
}
```

</details>

### Пошук за змінними

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_clients</summary>

URL-запит: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_clients>

Цей метод виконує пошук за змінними та повертає список ID клієнтів, які відповідають умовам запиту.

За замовчуванням пошук виконується по змінних клієнта (рекомендовано): {"q": {"result": "ok", "var": "home", "var": "60"}} – клієнт повинен мати всі вказані змінні

Пошук по змінних угоди, має бути присутня щонайменше одна з вказаних змінних: {"q": {"result": "ok", "var": "home", "var": "60"}, "search\_in": "order", "include\_all": False}

Назва змінної клієнта дорівнює одному зі значень списку: {"q": {"name": {"\_in": \["Joe", "Jane", "Donald"]}}}

Назва змінної клієнта НЕ дорівнює жодному зі значень списку: {"q": {"name": {"\_not\_in": \["Joe", "Jane", "Donald"]}}}

Назва змінної клієнта не дорівнює "Joe": {"q": {"name": {"\_not": "Joe"}}}

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

Права доступу під час генерації ключа: "Дозвіл на читання інформації про клієнтів"

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

Параметри

**Шлях**

api key\* - токен доступу

**Тіло**

q – обов’язковий параметр, містить умови запиту для пошуку змінних

search\_in – вказує, змінні якої сутності шукати; якщо не вказано, пошук виконується по змінних клієнта. Може приймати значення order.

include\_all – чи мають бути виконані всі умови в q;

False – якщо збігається хоча б одна умова, сутність вибирається

```
Успіх
{"status":"success","client_ids":[41203, 5622354, 785212]} 
{"status":"success","client_ids":[]} 
{"status": "fail", "message": "Параметр "q" обов'язковий"} {"status": "fail", "message": "Помилка у форматі параметра"}
Помилка
{"status":"fail","message":"Щось пішло не так"}
```

</details>

## Як працювати з угодами

### Отримати поточний ID угоди

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_current\\_order\\_id>

Права доступу під час генерації ключа: "Дозвіл на читання CRM-інформації".

<img src="/files/49a681b85c1b85f7427805cfca9b4d8ea2c92fab" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

```
Успішна відповідь: {"status":"success","order_id":40632}, де
order_id - поточний ID угоди
Відповідь з помилкою: {"status":"client_not_found"}
```

</details>

### Отримати список угод

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_orders</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_orders>

Права доступу під час генерації ключа: "Дозвіл на читання CRM-інформації"

<img src="/files/49a681b85c1b85f7427805cfca9b4d8ea2c92fab" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

**order\_status** - етап угоди: \
0 - активні угоди\
1 - успішні угоди\
2 - неуспішні угоди

```
Успішна відповідь: {"status":"success","order_id":[40338,40340,40341]} 
Відповідь з помилкою: {"status":"client_not_found"}
```

</details>

### Перемістити угоду на наступний етап у воронці Mavibot

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/move\\_order\\_to\\_next\\_state>

Права доступу під час генерації ключа: "Дозвіл на зміну/видалення CRM-інформації"

<img src="/files/166e92b39d003963aabe2eb8b268305252804570" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

**order\_id** - ID угоди

```
Успішна відповідь: 
{"status":"success","state_id":37}, де 
state_id - ID етапу в MavibotCRM 
Відповідь з помилкою: 
{"status":"client_not_found"}
```

</details>

### Отримати дані угоди

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_vars</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_vars>

Права доступу під час генерації ключа: "Дозвіл на читання CRM-інформації"

<img src="/files/49a681b85c1b85f7427805cfca9b4d8ea2c92fab" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

**order\_id** - ID угоди

variables - масив змінних\
(формат:\["var\_name1", "var\_name2"])

```
Успішна відповідь: 
{"status":"success","result":{"var_name1":"111","var_name2":"13.04.2023"}} 

Приклад помилки: 
{"status":"client_not_found"}
```

</details>

### Додати змінні угоди

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_vars</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_vars>

Права доступу під час генерації ключа: "Дозвіл на зміну/видалення CRM-інформації"

<img src="/files/166e92b39d003963aabe2eb8b268305252804570" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

**order\_id** - ID угоди

variables - словник змінних (ключ — це назва змінної, а значення — те, що потрібно зберегти в цій змінній)\
(формат:{"var\_name": "var\_velue"})

```
Успішна відповідь: {"status":"success"} 
Відповідь з помилкою: {"status":"order 12345 not found"}
```

</details>

### Створити угоду

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/create_order</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/create\\_order>

Права доступу під час генерації ключа: "Дозвіл на зміну/видалення CRM-інформації"

<img src="/files/166e92b39d003963aabe2eb8b268305252804570" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

name - назва угоди

description - опис угоди

budget - сума угоди

У запиті потрібно вказати один із таких параметрів: client\_id, email або phone.
\
Якщо вказано кілька параметрів, буде використано лише один. Пріоритет такий: client\_id > phone > email.
\
Якщо вказано phone або email і клієнта з таким номером телефону або email не існує, буде створено нового клієнта.

```
Успішна відповідь: {"status":"success","order_id":40654}, 
де order_id — ID нової активної угоди.
Відповідь з помилкою: {"status":"client_not_found"}
```

</details>

### Перемістити угоду на етап у MavibotCRM

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_state</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_state>

Права доступу під час генерації ключа: "Дозвіл на зміну/видалення CRM-інформації"

<img src="/files/166e92b39d003963aabe2eb8b268305252804570" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

state\_id - номер етапу, на який потрібно перемістити угоду клієнта

</details>

### Отримати ID етапу воронки в Mavibot CRM

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_state</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_state>

Права доступу під час генерації ключа: "Дозвіл на читання CRM-інформації"

<img src="/files/49a681b85c1b85f7427805cfca9b4d8ea2c92fab" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

**Тіло**

client\_id - ID клієнта

state\_id - ID угоди (якщо не вказано, метод поверне ID етапу поточної угоди)

```
Приклад успішної відповіді:
{'status': 'success', 'state_id': 123456}

Приклад невдалої відповіді:
{'status': 'order not found'}
```

</details>

## Які ще можливості доступні?

### Перевірити, чи має номер телефону WhatsApp

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/check_whatsapp</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/#{api\\_key}/check\\_whatsapp>

**Щоб використовувати цей метод, WhatsApp має бути підключений до Mavibot.**

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

Може викликатися через GET або POST.
\
Номер телефону можна вказувати в будь-якому форматі.

**Шлях**

api key\* - токен доступу

**Тіло**

phone - номер телефону для перевірки

</details>

### Отримати список месенджерів, підключених до проєкту

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/connected_channels</summary>

URL-запит: <https://chatter.mavibot.ai/api/\\>\<api\_key>/connected\_channels

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

Функція повертає параметр group\_id для кожного месенджера, який потрібно використовувати під час імпорту клієнтів.

Для WhatsApp вона також повертає **status** поле, яке може мати такі значення:<br>

**NOT\_STARTED = 0**\
**STARTED = 1**\
**ASLEEP = 2**\
**STOPPED = 3**

**Шлях**

api key\* - токен доступу

```
{'project_id': 1, 
'viber': [{
        'id': 14, 
        'uri': 'mavibotstage', 
        'name': 'mavibotstage', 
        'enabled': true,
        'group_id': 11}], 
'facebook': [], 
'telegram': [{
        'id': 23, 
        'short_name': 'bulls_vs_bears_bot', 
        'name': 'bulls_vs_bears_bot', 
        'enabled': true,
        'group_id': 'bulls_vs_bears_bot'}], 
'whatsapp': [], 
'avito': [], 
'ok': [], 
'vkontakte': [{
        'id': 33, 
        'group': '143414131',
        'group_id': '143414131'}]
}
```

</details>

### Отримати список блоків із потоку бота

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_messages</summary>

**URL-запиту:** <https://chatter.mavibot.ai/api/\\>\<api\_key>/get\_messages

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

<img src="/files/01d63837fc97a1d951c3331386daa667eff3f140" alt="" data-size="original">

**Шлях**

api key\* - токен доступу

</details>

### Отримати вкладені дані клієнта

<details>

<summary>delimiter</summary>

Щоб отримати client\_id та/або номер телефону клієнта з вкладених словників (не на першому рівні), використовуйте параметр delimiter.

Додайте таке до URL вашого запиту:

?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}&#x20;

де:

?delimiter=1 – значення роздільника, яке відокремлює ключі {key1}1{key2}1{key3}

delimiter\_value\_client\_id={key1}1{key2} – для отримання ID клієнта

delimiter\_value\_phone={key1}1{key2} – для отримання номера телефону клієнта

{key1}, {key2}, … – ключі, що містять значення (можуть містити будь-які символи, крім роздільника). Може бути необмежена кількість ключів:\
?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}. \
**Ключі передаються без фігурних дужок.**

Використовуйте роздільник між ключами. Наприклад, якщо delimiter=2, тоді {key1}2{key2}2{key3}; якщо delimiter=5, тоді {key1}5{key2}5{key3}. Переконайтеся, що ключ не містить символ роздільника.

Приклад:

<https://chatter.mavibot.a/aipi/\\>\<api\_key>/callback<mark style="color:yellow;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}**</mark>&#x20;

Ви також можете отримати лише ID або лише номер телефону:&#x20;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:green;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2} -**</mark> лише ID клієнта;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:green;">**?delimiter=1delimiter\_value\_phone={key1}1{key2}**</mark> - лише номер телефону;

Методи API:

1. Запустити бота: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/callback
2. Запустити бота за номером WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_callback
3. Запустити бота за Telegram ID: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/tg\_callback
4. Надіслати callback-повідомлення email-клієнту: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/email\_callback
5. Надіслати повідомлення клієнту: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/message
6. Надіслати повідомлення WhatsApp: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_message
7. Масова розсилка: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/broadcast
8. Призначити змінні: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/save\_variables
   \\

</details>

{% hint style="success" %}
Якщо вам потрібні додаткові методи, будь ласка, зверніться до служби підтримки.
{% endhint %}


---

# 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/robota-z-api/konstruktor-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.