# Робота з клієнтами та CRM

## Робота з клієнтами

<mark style="color:red;">**ЛЕГЕНДА:**</mark>

was\_in\_state() | days\_from\_last\_message() | free\_client() | assign\_to\_user() | distribute\_client()| get\_operator() | get\_operator\_name() | delete\_pended\_messages() | set\_note() | add\_unread() | clear\_unread() | unsubscribe()|block\_client() | unblock\_client() | set\_client\_name() | get\_bind\_clients() | get\_current\_pipline\_id()

<details>

<summary>Опис</summary>

**was\_in\_state(message\_id)**\
перевіряє, чи був клієнт у вибраному стані (блоці). Номер блоку можна отримати в редакторі.

<figure><img src="/files/bc30dd3445a34f177838b7efe23a95ad6f33ca3f" alt=""><figcaption><p>У верхньому рядку редактора блоків відображається номер блоку.</p></figcaption></figure>

**days\_from\_last\_message()**\
визначає кількість днів від останнього повідомлення клієнта. Створено для перевірки, чи потрапляє воно у 24-годинне вікно.

Приклад: \
`d = days_from_last_message()`

{% hint style="info" %}
Якщо з моменту останнього повідомлення клієнта минуло понад 30 днів, функція поверне значення 9999.
{% endhint %}

\
**free*****\_*****client()**\
знімає відповідального оператора.
&#x20;Приклад: free\_client()

**assign\_to\_user(email, only\_active)**\
призначає діалог оператору, де:

1. email - рядковий параметр (необов’язковий). Якщо вказано лише email, діалог буде призначено вказаному оператору незалежно від його поточного статусу.&#x20;
2. only\_active - True або False (необов’язковий параметр). Якщо встановлено True, діалог буде призначено вказаному оператору лише якщо він зараз на зміні.

Приклади:

`assign_to_user()` - призначає діалог випадковому оператору, який зараз на зміні&#x20;

`assign_to_user('email оператора')` - призначає діалог оператору незалежно від його статусу

`assign_to_user('email оператора', True)` - призначає діалог вказаному оператору лише якщо він зараз на зміні

**distribute\_client()**\
призначає діалог оператору відповідно до налаштувань авторозподілу. \
Приклад:  `distribute_client()`

**get\_operator**()\
отримує email відповідального оператора

Приклад: `get_operator()`&#x20;

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

**get\_operator\_name**()\
отримує ім’я відповідального оператора

Приклад:  `get_operator_name()`&#x20;

Може використовуватися для відображення інформації клієнту. Якщо відповідального оператора немає, поверне None. Якщо в оператора не вказано ім’я, поверне його email.

**delete\_pended\_messages()**\
видаляє всі заплановані повідомлення для поточного клієнта. За замовчуванням також видаляє повідомлення, створені стрілками **"Не скасовувати"** Щоб зберегти повідомлення зі стрілок **"Не скасовувати"** передайте параметр False: delete\_pended\_messages(False).

**set\_note(comment)**\
додає коментар до діалогу.

Приклад: **`set_note`**`('Переробити')`

**add\_unread(count)**\
позначає діалог із клієнтом як непрочитаний

Параметр count можна не вказувати або встановити в 1; у цьому випадку в діалозі з клієнтом буде показано індикатор +1 непрочитане повідомлення.

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

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

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

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

**clear\_unread()**\
позначає діалог як прочитаний

**unsubscribe()**\
Функція для відписки від повідомлень бота. Приклад наведено [у цій статті.](/doc/uk/biznes-rozsilki/vidpiska-vid-bota.md)
&#x20; Для відписаного клієнта з’явиться символ — червоне повідомлення з хрестиком.

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

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

{% hint style="info" %}
**Важливо!**

Поле **Калькулятор виконується першим**, і лише потім надсилається повідомлення.

Тому, якщо вам потрібно надіслати фінальне повідомлення на кшталт **"Вас відписано від бота"** або **"Вас заблоковано"**, потрібно використати двоетапний процес:

1. **Спочатку надішліть блок** що містить фінальне повідомлення.
2. **Потім надішліть порожній блок** що містить функцію unsubscribe/block.

**Якщо спробувати зробити обидві дії в одному блоці, повідомлення не буде надіслано.**
{% endhint %}

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

Якщо ви розмістите функцію `unsubscribe()` у калькуляторі того ж блоку, що й ваше повідомлення, повідомлення **не буде надіслано**, і система відобразить помилку.

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

**block\_client()**\
блокує клієнту можливість надсилати повідомлення боту. Раніше заплановані повідомлення від бота також буде скасовано. Однак все ще буде можливо написати клієнту безпосередньо з діалогу в розділі **"Клієнти"** розділ

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

Заблокований клієнт матиме позначку — червону іконку замка.

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

**unblock\_client()**\
розблоковує клієнта. Клієнт знову зможе взаємодіяти з ботом і проходити ланцюжки повідомлень.

**set\_client\_name(name)**\
змінює ім’я клієнта. Передайте ім’я клієнта як рядок у подвійних лапках. Також можна використовувати змінну, що містить ім’я клієнта, наприклад: set\_client\_name("John Smith")

**get\_bind\_clients()**\
функція без параметрів, яка повертає масив ID клієнтів, пов’язаних із поточним клієнтом.

**get\_current\_pipline\_id()**\
функція без параметрів, яка повертає ID воронки, у якій клієнт перебуває зараз.

Якщо угода клієнта перебуває на етапі "необроблено", вона повертає None.

</details>

## Робота із завданнями&#x20;

{% hint style="success" %}
Функції, що працюють із завданнями, повертають статус операції як **True або ID завдання у разі успіху. У разі невдачі вони повертають False або None.**
{% endhint %}

{% hint style="info" %}
MaviBot використовує формат дати **"dd.mm.yyyy"** і формат часу **"HH:MM"**.
{% endhint %}

create\_task() | update\_task() | done\_task() | delete\_task()

<details>

<summary>Опис</summary>

**create\_task(email, name, date\_srok, description, time\_srok)** – створює завдання

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;email** - email відповідальної особи\ <mark style="color:red;">**!**</mark>**&#x20;name** - назва завдання\ <mark style="color:red;">**!**</mark>**&#x20;date\_srok** - кінцева дата, дата\ <mark style="color:red;">**!**</mark>**&#x20;description** - опис завдання\
**time\_srok** - кінцевий час, час

**update\_task(task\_id,email, name, date\_srok, description, time\_srok)** - оновлює завдання

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- ID завдання\ <mark style="color:red;">**!**</mark>**&#x20;email** - email відповідальної особи\ <mark style="color:red;">**!**</mark>**&#x20;name** - назва завдання\ <mark style="color:red;">**!**</mark>**&#x20;date\_srok** - кінцева дата, дата\ <mark style="color:red;">**!**</mark>**&#x20;description** - опис завдання\
**time\_srok** - кінцевий час, час

**done\_task(task\_id)**- позначає завдання як виконане

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- ID завдання

**delete\_task(task\_id)** – видаляє завдання

Параметри:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- ID завдання

</details>

<details>

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

Давайте створимо завдання для оператора:

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

Оновіть кінцеву дату та опис.

<div data-with-frame="true"><figure><img src="/files/dc3504ba06c3f5577007184a14b3dd46d240d954" alt="" width="563"><figcaption><p>Оновлення завдання</p></figcaption></figure></div>

Позначте завдання як виконане.

<div data-with-frame="true"><figure><img src="/files/50880a6a7fdcc062857f6e7f46b783200f52bce9" alt="" width="563"><figcaption><p>Позначення завдання як виконаного</p></figcaption></figure></div>

Видалення завдання

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

</details>

<details>

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

`task_id=create_task('admin@mavibot.ai', 'Тест', '22.01.2023', 'тестове завдання', '08:00') status=delete_task(task_id)`

</details>

## Робота з угодами

get\_order\_id() | create\_order() | set\_order\_name() | set\_order\_budget() | get\_active\_orders\_ids() | get\_success\_orders\_ids() | get\_fail\_orders\_ids() | get\_order\_var() | get\_order\_vars() | set\_order\_var() | set\_order\_vars() | move\_order\_to\_next\_state() | set\_order\_status\_success() | set\_order\_status\_fail(order\_id)| get\_state\_id() | change\_state() | get\_order\_id\_by\_var\_value() | latest\_order\_datetime() | count\_client\_orders(), get\_count\_orders() | delete\_order(order\_id)

<details>

<summary>Опис</summary>

<mark style="color:за замовчуванням;background-color:blue;">**Отримання ID поточної угоди**</mark>

**get\_order\_id()** - повертає стан угоди.

<mark style="color:за замовчуванням;background-color:blue;">**Створення нової угоди**</mark>

**create\_order(name, budget, description, client\_name, phone, email, state\_id)**\
Поточна активна угода у воронці разом зі своїми змінними буде доступна лише у функціях, пов’язаних з угодами, і в CRM.\
\
**Параметри функції:** \ <mark style="color:red;">**!**</mark>**&#x20;name** - (необов’язково), назва угоди. Якщо не вказано, функція застосовується до поточної активної угоди клієнта.

<mark style="color:red;">**!**</mark>**&#x20; Призначте назву змінної (наприклад,** - (необов’язково) вартість угоди. Якщо не вказано, застосовується до поточної активної угоди.\
Якщо **Призначте назву змінної (наприклад,** не є числом, функція поверне: **budget має бути числом**

**description** - (необов’язково), опис угоди.

Додаткові параметри для створення клієнта:

**client\_name** - (необов’язково) рядок, ім’я нового клієнта

**phone** - (необов’язково) рядок, номер телефону нового клієнта.

**email** - (необов’язково) рядок, email-адреса нового клієнта.

Щоб створити клієнта, потрібно вказати принаймні телефон або email. Якщо вказано телефон і в проєкті немає клієнта з таким телефоном, буде створено нового.

Якщо вказано email без телефону і клієнта з таким email не існує, буде створено нового.

Додатковий параметр:

**state\_id** - число, дозволяє встановити початковий стан угоди під час створення

<mark style="color:за замовчуванням;background-color:blue;">**Встановити або оновити назву угоди**</mark>

**set\_order\_name(name, order\_id)**

**name** - ❗обов’язково, рядок; назва угоди

**order\_id** - (необов’язково) ID угоди. Якщо не вказано, зміна застосовується до поточної активної угоди клієнта.

<mark style="color:за замовчуванням;background-color:blue;">**Встановити або оновити бюджет угоди**</mark>

**set\_order\_budget(budget, order\_id)**

**Призначте назву змінної (наприклад,** -❗обов’язково, число; вартість угоди

**order\_id** - (необов’язково) ID угоди. Якщо не вказано, застосовується до поточної активної угоди клієнта.

Щоб правильно використовувати order\_id:

1. Ви можете вказати його вручну — отримайте ID угоди та передайте його як параметр функції, якщо хочете звернутися до конкретної угоди.

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

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

1. Отримуйте його за допомогою функції get\_order\_id(), оскільки вбудована змінна order\_id повертає значення у форматі {client\_id}-{order\_id}, що може спричинити некоректну поведінку.

<mark style="color:за замовчуванням;background-color:blue;">**Отримання списків угод**</mark> \
((за винятком архівних, успішних або невдалих угод))

**get\_active\_orders\_ids()**&#x20;

<mark style="color:за замовчуванням;background-color:blue;">**Отримати список ID успішних угод**</mark>

**get\_success\_orders\_ids()**&#x20;

<mark style="color:за замовчуванням;background-color:blue;">**Отримати список ID невдалих угод**</mark>

**get\_fail\_orders\_ids()**

<mark style="color:за замовчуванням;background-color:blue;">**Отримання значення змінної угоди**</mark>

**get\_order\_var(order\_id, variable)**&#x20;

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - ID угоди&#x20;

<mark style="color:red;">**!**</mark>**&#x20;variable** - назва змінної, значення якої ви хочете отримати

<mark style="color:за замовчуванням;background-color:blue;">**Отримання даних угоди**</mark>

**get\_order\_vars(order\_id, names)**&#x20;

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - ID угоди

**names** - масив назв змінних для отримання. Якщо не вказано, функція повертає всі змінні для зазначеної угоди

Функція повертає словник, що містить змінні, перелічені в масиві **names** для угоди, визначеної за **order\_id**. Якщо **names** не вказано, вона повертає словник з усіма змінними зазначеної угоди.

<mark style="color:за замовчуванням;background-color:blue;">**Додавання змінної угоди**</mark>

**set\_order\_var(order\_id, variable, value)**

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - ID угоди

<mark style="color:red;">**!**</mark>**&#x20;variable** - назва змінної, яку потрібно додати або оновити в угоді

{% hint style="warning" %}
Якщо ви хочете змінити параметри угоди "name" або "description", використовуйте назви змінних "name" або "description" відповідно.
{% endhint %}

<mark style="color:red;">**!**</mark>**&#x20;value** - значення змінної

<mark style="color:за замовчуванням;background-color:blue;">**Додавання кількох змінних угоди**</mark>

**set\_order\_vars(order\_id, variables\_dict)**&#x20;

Параметри:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - ID угоди.&#x20;

<mark style="color:red;">**!**</mark>**&#x20;variables\_dict** - словник змінних

<mark style="color:за замовчуванням;background-color:blue;">**Перехід до наступного стану воронки**</mark>

**move\_order\_to\_next\_state(order\_id)**&#x20;

Параметри:\
**order\_id** - ID угоди. Якщо не вказано, буде переміщено поточну активну угоду.\
Порядок станів угоди визначається відповідно до послідовності, встановленої в MavibotCRM.

<mark style="color:за замовчуванням;background-color:blue;">**Отримання етапу воронки в MavibotCRM**</mark>

**get\_state\_id(client\_id, order\_id)** \
Ви також можете скопіювати ID стану воронки безпосередньо з **"Налаштування стану"**.

Параметри:

**order\_id -** ID угоди клієнта

Ви можете викликати функцію з параметром **order\_id** або без нього. Якщо order\_id не вказано, функція поверне ID стану воронки для поточної активної угоди.

Для коректного використання order\_id:

1. Ви можете вказати його вручну, отримавши ID угоди та передавши його як параметр функції, коли хочете звернутися до конкретної угоди.
2. Отримуйте його за допомогою функції get\_order\_id(), оскільки вбудована змінна order\_id повертає значення у форматі {client\_id}-{order\_id}, що може спричинити некоректну поведінку.

<mark style="color:за замовчуванням;background-color:blue;">**Переміщення ліда по воронці MavibotCRM за ID стану**</mark>

**change\_state(state\_id, order\_id)**&#x20;

Параметри:\ <mark style="color:red;">**!**</mark> **state\_id -** ID стану воронки\
**order\_id (** необов’язково) -  ID угоди для переміщення по воронці. Якщо не вказано, буде переміщено поточну активну угоду.

<mark style="color:за замовчуванням;background-color:blue;">**Отримання ID угоди за назвою змінної та значенням**</mark>

get\_order\_id\_by\_var\_value(var\_name, var\_value, client\_id)

Параметри:\ <mark style="color:red;">!</mark> var\_name - назва змінної\ <mark style="color:red;">!</mark> var\_value - значення змінної;\
client\_id - (необов’язково) ID угоди клієнта; за замовчуванням використовується ID клієнта в боті

<mark style="color:за замовчуванням;background-color:blue;">**Отримання дати й часу останньої угоди**</mark>

latest\_order\_datetime(client\_id, dt\_fmt)

Параметри:\
client\_id - (необов’язково) ID угоди клієнта; за замовчуванням використовується ID клієнта в боті;\
df\_fmt - (необов’язково) формат для повернених дати й часу; за замовчуванням "%d.%m.%y %H:%M"

<mark style="color:за замовчуванням;background-color:blue;">**Отримання кількості угод клієнта**</mark>

count\_client\_orders(client\_id, state\_id, get\_all, active)

Параметри:\
client\_id -  (необов’язково) ID клієнта угоди; за замовчуванням використовується ID клієнта в боті;\
state\_id - (необов’язково) ID стану угоди у воронці;\
get\_all - (необов’язково) прапорець фільтра для параметра active; за замовчуванням 1 (фільтрацію за active вимкнено);\
active - використовується лише коли get\_all дорівнює 0; фільтрує активні угоди; за замовчуванням 1 (повертає лише активні угоди);

<mark style="color:за замовчуванням;background-color:blue;">**Отримати кількість угод у певному стані угоди**</mark>

get\_count\_orders(id) - повертає кількість угод, які зараз перебувають у певному стані воронки за ID стану.

Функція приймає один параметр:

<mark style="color:red;">**!**</mark> id - ID стану угоди.&#x20;

Приклад використання функції:

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

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

ID етапу можна знайти в налаштуваннях.

Далі потрібно ввести функцію в калькулятор таким чином:

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

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

<mark style="color:за замовчуванням;background-color:blue;">**Видалення угоди**</mark>

delete\_order(order\_id) — видаляє угоду в **MaviBotCRM**.

order\_id - (необов’язково) ID угоди для видалення. Якщо не вказано, буде видалено останню угоду.&#x20;

</details>

<details>

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

Усі функції прості у використанні.
\
Наприклад, давайте створимо нову угоду та надішлемо її номер клієнту:

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

<div data-with-frame="true"><figure><img src="/files/9e73bf4047122562fe85326ae197dc3c6bb2dc18" alt="" width="563"><figcaption><p>Реєстрація запиту клієнта</p></figcaption></figure></div>

Ви можете отримати ID поточної активної угоди клієнта за допомогою функції get\_order\_id(), або отримати повний список угод клієнта за допомогою get\_active\_orders\_ids().

<div data-with-frame="true"><figure><img src="/files/cdb41a1e8ab471350c968e6bb3233de90fc2a65a" alt="" width="563"><figcaption><p>Отримання ID поточної активної угоди</p></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/282648fe2be5abe907311e5965596169f6d58574" alt="" width="563"><figcaption><p>Отримання списку активних угод</p></figcaption></figure></div>

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

</details>

<details>

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

<pre><code><strong>/* Створити нову угоду */
</strong>oid = create_order()

/*Отримати ID активної угоди клієнта*/
oid = get_order_id()

/*Отримати список активних угод*/
res = get_active_orders_ids()

/*Додати або оновити одну змінну в угоді*/
res = set_order_var('40630', 'оновлено', '#{current_date}')

vars = {"VAR1": "V111", "VAR2": "V222"}
res2 = set_order_vars('40630', vars)

ovar = get_order_vars('40630')
</code></pre>

</details>

### <mark style="color:за замовчуванням;background-color:blue;">**Встановлення мітки успішної угоди**</mark>

set\_order\_status\_success()

{% tabs %}
{% tab title="Опис" %}
**set\_order\_status\_success(order\_id)**&#x20;

Параметри:

**order\_id** - ID угоди. Якщо параметр не вказано, мітку буде встановлено для поточної активної угоди.
{% endtab %}
{% endtabs %}

### <mark style="color:за замовчуванням;background-color:blue;">**Встановлення мітки невдалої угоди**</mark>&#x20;

set\_order\_status\_fail()

{% tabs %}
{% tab title="Опис" %}
**set\_order\_status\_fail(order\_id)**&#x20;

Параметри:

**order\_id** - ID угоди. Якщо параметр не вказано, мітку буде встановлено для поточної активної угоди.
{% endtab %}
{% endtabs %}

### <mark style="color:за замовчуванням;background-color:blue;">**Встановлення мітки архівної угоди**</mark> &#x20;

set\_order\_status\_archive()

{% tabs %}
{% tab title="Опис" %}
**set\_order\_status\_archive(order\_id)**&#x20;

Параметри:

**order\_id** - ID угоди. Якщо параметр не вказано, мітку буде встановлено для поточної активної угоди.
{% endtab %}

{% tab title="Приклади" %}
/\*Архівувати поточну активну угоду\*/

`res_arh = set_order_status_archive()`
{% endtab %}
{% endtabs %}


---

# 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/kalkulyator/crm.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.