# Работа с клиентами и CRM

## Работа с клиентами

<mark style="color:красный;">**ЛЕГЕНДА:**</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/af48f2c6c4e2c9efb6ddafbaa8b5afae814cd0b3" 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/ba15d76b3ab50579009ceb0256eed74f2c360d77" alt="" width="563"><figcaption></figcaption></figure></div>

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

Если передано любое другое число, оно будет отображаться в разделе **«Клиенты»** как количество непрочитанных сообщений от клиента.

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

**clear\_unread()**\
помечает диалог как прочитанный

**unsubscribe()**\
Функция для отписки от сообщений бота. Пример приведён [в этой статье.](/doc/ru/biznes-rassylki/otpiska-ot-bota.md)
&#x20; У отписанного клиента появится символ — красное сообщение с крестиком.

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

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

{% hint style="info" %}
**Важно!**

Текст **Калькулятор выполняется первым**, и только потом отправляется сообщение.

Поэтому, если вам нужно отправить итоговое сообщение, например **"Вы были отписаны от бота"** или **"Вы были заблокированы"**, необходимо использовать двухшаговый процесс:

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

**Если попытаться сделать и то и другое в одном блоке, сообщение не будет отправлено.**
{% endhint %}

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

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

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

**block\_client()**\
блокирует клиенту возможность отправлять сообщения боту. Ранее запланированные сообщения от бота также будут отменены. Однако по-прежнему можно будет писать клиенту напрямую из диалога в разделе **«Клиенты»** раздел

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

У заблокированного клиента будет отметка — красный значок замка.

<div data-with-frame="true"><figure><img src="/files/d06f0aaf3dbdb8f3e46097e04c357a63a8d2c97a" 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:красный;">**!**</mark>**&#x20;email** - email ответственного\ <mark style="color:красный;">**!**</mark>**&#x20;name** - название задачи\ <mark style="color:красный;">**!**</mark>**&#x20;date\_srok** - срок выполнения, дата\ <mark style="color:красный;">**!**</mark>**&#x20;description** - описание задачи\
**time\_srok** - срок выполнения, время

**update\_task(task\_id,email, name, date\_srok, description, time\_srok)** - обновляет задачу

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

**done\_task(task\_id)**- помечает задачу как выполненную

Параметры:\ <mark style="color:красный;">**!**</mark>**&#x20;task\_id**- ID задачи

**delete\_task(task\_id)** – удаляет задачу

Параметры:\ <mark style="color:красный;">**!**</mark>**&#x20;task\_id**- ID задачи

</details>

<details>

<summary>Примеры</summary>

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

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

Обновим срок выполнения и описание.

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

Пометим задачу как выполненную.

<div data-with-frame="true"><figure><img src="/files/9246bd9935429e95351d6951c2b65cb330eb99ff" alt="" width="563"><figcaption><p>Пометка задачи как выполненной</p></figcaption></figure></div>

Удаление задачи

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

</details>

<details>

<summary>Пример кода для копирования</summary>

`task_id=create_task('admin@mavibot.ai', 'Test', '22.01.2023', 'test task', '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:красный;">**!**</mark>**&#x20;name** - (необязательно), название сделки. Если не указано, функция применяется к текущей активной сделке клиента.

<mark style="color:красный;">**!**</mark>**&#x20; budget** - (необязательно) сумма сделки. Если не указана, применяется к текущей активной сделке.\
Если **budget** не является числом, функция вернёт: **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)**

**budget** -❗обязательно, число; сумма сделки

**order\_id** - (необязательно) ID сделки. Если не указан, применяется к текущей активной сделке клиента.

Чтобы корректно использовать order\_id:

1. Вы можете указать его вручную — получить ID сделки и передать его как параметр функции, если хотите обратиться к конкретной сделке.

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

<div data-with-frame="true"><figure><img src="/files/98204515e4508838be96e03e963aea9214d13d41" 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:красный;">**!**</mark>**&#x20;order\_id** - ID сделки&#x20;

<mark style="color:красный;">**!**</mark>**&#x20;variable** - имя переменной, значение которой вы хотите получить

<mark style="color:по умолчанию;background-color:blue;">**Получение данных сделки**</mark>

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

Параметры:

<mark style="color:красный;">**!**</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:красный;">**!**</mark>**&#x20;order\_id** - ID сделки

<mark style="color:красный;">**!**</mark>**&#x20;variable** - имя переменной для добавления или обновления в сделке

{% hint style="warning" %}
Если вы хотите изменить параметры сделки "name" или "description", используйте имена переменных "name" или "description" соответственно.
{% endhint %}

<mark style="color:красный;">**!**</mark>**&#x20;value** - значение переменной

<mark style="color:по умолчанию;background-color:blue;">**Добавление нескольких переменных сделки**</mark>

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

Параметры:

<mark style="color:красный;">**!**</mark>**&#x20;order\_id** - ID сделки.&#x20;

<mark style="color:красный;">**!**</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:красный;">**!**</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:красный;">!</mark> var\_name - имя переменной\ <mark style="color:красный;">!</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:красный;">**!**</mark> id - ID состояния сделки.&#x20;

Пример использования функции:

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

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

ID этапа можно найти в настройках.

Далее нужно ввести функцию в калькулятор следующим образом:

<div data-with-frame="true"><figure><img src="/files/46955d122cb88a3ee23efaa32aa10099dc271831" 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/2b6a3b5753bfa582d859391cb94c5f9b7c0171f8" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/7f252b1a2c70d0bae4be8ace3b927b9edc7b0663" 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/ee7075398b37119b1c32bff6cadf7b02c19fbfb3" alt="" width="563"><figcaption><p>Получение ID текущей активной сделки</p></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/34b293392ea8973df56a4197aff237fa6d4468c3" alt="" width="563"><figcaption><p>Получение списка активных сделок</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/40bfee8fc7ee859a8fd157dd45eb4d1061f366b3" 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/ru/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.