# Working with cutomers and CRM

## Working with clients

<mark style="color:red;">**LEGEND:**</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>Description</summary>

**was\_in\_state(message\_id)**\
checks whether a client was in the selected state (block). You can get the block number from the editor.

<figure><img src="/files/e54yGnZp9uEaVQ0xNovR" alt=""><figcaption><p>The top line of the block editor displays the block number.</p></figcaption></figure>

**days\_from\_last\_message()**\
determines the number of days since the client's last message. Created to check whether it falls within the 24-hour window.

Example: \
`d = days_from_last_message()`

{% hint style="info" %}
If more than 30 days have passed since client's last message, the function will return the value 9999.
{% endhint %}

\
**free*****\_*****client()**\
unassigns the responsible operator.
&#x20;Example: free\_client()

**assign\_to\_user(email, only\_active)**\
assigns a dialogue to an operator, where:

1. email - a string parameter (optional). If only email is provided, a dialogue will be assigned to the specified operator regardless of his current status.&#x20;
2. only\_active - True or False (optional parameter). If set to True, a dialogue will be assigned to the specified operator only if they are currently on shift.

Examples:

`assign_to_user()` - assigns a dialogue to a random operator who is currently on shift&#x20;

`assign_to_user('operator's email')` - assigns a dialogue to the operator regardless of their status

`assign_to_user('operator's email', True)` - assigns a dialogue to the specified operator only if they are currently on shift

**distribute\_client()**\
assigns a dialogue to the operator according to the auto-distribution settings. \
Example:  `distribute_client()`

**get\_operator**()\
retrieves the email of a responsible operator

Example: `get_operator()`&#x20;

It can be used to assign tasks to a responsible operator or to check if he exists. If there is no responsible operator, it will return None.

**get\_operator\_name**()\
retrieves the name of the responsible operator

Example:  `get_operator_name()`&#x20;

It can be used to display information to ta client. If there is no responsible operator, it will return None. If the operator does not have a name assigned, it will return their email.

**delete\_pended\_messages()**\
deletes all scheduled messages for the current client. By default, it also deletes messages created by the **"Do not cancel"** arrows. To keep messages from the **"Do not cancel"** arrows, pass the parameter False: delete\_pended\_messages(False).

**set\_note(comment)**\
adds a comment to a dialogue.

Example: **`set_note`**`('Redo')`

**add\_unread(count)**\
marks a dialogue with a client as unread

The count parameter can be omitted or set to 1; in this case, the dialogue with the client will show a +1 unread message indicator.

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

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

If any other number is passed, it will be displayed in the **"Clients"** section as the number of unread messages from a client.

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

**clear\_unread()**\
marks a dialogue as read

**unsubscribe()**\
Function to unsubscribe from bot messages. An example is provided [in this article.](/business-mailings/unsubscribing-from-the-bot.md)
&#x20; For the unsubscribed client, a symbol will appear — a red message with a cross.

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

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

{% hint style="info" %}
**Important!**

The **Calculator is executed first**, and only then is the message sent.

Therefore, if you need to send a final message like **"You have been unsubscribed from the bot"** or **"You have been blocked"**, you must use a two-step process:

1. **First, send a block** containing the final message.
2. **Then, send an empty block** containing the unsubscribe/block function.

**If you try to do both in a single block, the message will not be sent.**
{% endhint %}

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

If you place the `unsubscribe()` function in the same block's calculator as your message, the message will **not be sent**, and the system will display an error.

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

**block\_client()**\
blocks a client from sending messages to the bot. Previously scheduled messages from the bot will also be canceled. However, it will still be possible to message the client directly from the dialogue in the **"Clients"** section

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

A blocked client will have a mark — a red lock icon.

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

**unblock\_client()**\
unblocks the client. The client will be able to interact with the bot again and proceed through message chains.

**set\_client\_name(name)**\
changes the client’s name. Pass the client’s name as a string in double quotes. You can also use a variable containing the client’s name, for example: set\_client\_name("John Smith")

**get\_bind\_clients()**\
a parameterless function that returns an array of clients IDs linked to the current client.

**get\_current\_pipline\_id()**\
a parameterless function that returns the funnel ID the client is currently in.

If the client’s deal is in the "unprocessed" stage, it returns None.

</details>

## Working with tasks&#x20;

{% hint style="success" %}
Functions that work with tasks return the operation status as **True or the task ID upon success. In case of failure, they return False or None.**
{% endhint %}

{% hint style="info" %}
MaviBot uses the date format **"dd.mm.yyyy"** and the time format **"HH:MM"**.
{% endhint %}

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

<details>

<summary>Description</summary>

**create\_task(email, name, date\_srok, description, time\_srok)** – creates a task

Parameters:\ <mark style="color:red;">**!**</mark>**&#x20;email** - responsible person email\ <mark style="color:red;">**!**</mark>**&#x20;name** - task name\ <mark style="color:red;">**!**</mark>**&#x20;date\_srok** - due date, date\ <mark style="color:red;">**!**</mark>**&#x20;description** - task description\
**time\_srok** - due time, time

**update\_task(task\_id,email, name, date\_srok, description, time\_srok)** - updates a task

Parameters:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- task ID\ <mark style="color:red;">**!**</mark>**&#x20;email** - responsible person email\ <mark style="color:red;">**!**</mark>**&#x20;name** - task name\ <mark style="color:red;">**!**</mark>**&#x20;date\_srok** - due date, date\ <mark style="color:red;">**!**</mark>**&#x20;description** - task description\
**time\_srok** - due time, time

**done\_task(task\_id)**- marks a task as completed

Parameters:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- task ID

**delete\_task(task\_id)** – deletes a task

Parameters:\ <mark style="color:red;">**!**</mark>**&#x20;task\_id**- task ID

</details>

<details>

<summary>Examples</summary>

Let's create a task for the operator:

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

Update the due date and description.

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

Mark the task as completed.

<div data-with-frame="true"><figure><img src="/files/Bs1Y3LbyFZKPEsbZzTrz" alt="" width="563"><figcaption><p>Marking the task as completed</p></figcaption></figure></div>

Task deletion

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

</details>

<details>

<summary>Code example for copying</summary>

`task_id=create_task('admin@mavibot.ai', 'Test', '22.01.2023', 'test task', '08:00') status=delete_task(task_id)`

</details>

## Working with deals

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>Description</summary>

<mark style="background-color:blue;">**Retrieving the current deal ID**</mark>

**get\_order\_id()** - returns the deal state.

<mark style="background-color:blue;">**Creating a new deal**</mark>

**create\_order(name, budget, description, client\_name, phone, email, state\_id)**\
The currently active deal in the pipeline, along with its variables, will be available only in deal-related functions and in the CRM.\
\
**Function parameters:** \ <mark style="color:red;">**!**</mark>**&#x20;name** - (optional), the deal name. If not provided, the function applies to client’s current active deal.

<mark style="color:red;">**!**</mark>**&#x20; budget** - (optional) the deal value. If not provided, applies to the current active deal.\
If **budget** is not a number, the function will return: **budget must be a number**

**description** - (optional), the deal description.

Additional parameters for client creation:

**client\_name** - (optional) string, name of a new client

**phone** - (optional) string, phone number of a new client.

**email** - (optional) string, email address of a new client.

To create a client, at least phone or email must be provided. If phone is provided and no client with this phone exists in the project, a new one will be created.

If email is provided without phone and no client with this email exists, a new one will be created.

Additional parameter:

**state\_id** - number, allows setting the initial state of the deal upon creation

<mark style="background-color:blue;">**Set or update the deal name**</mark>

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

**name** - ❗required, string; the deal name

**order\_id** - (optional) deal ID. If not provided, the change applies to the client's current active deal.

<mark style="background-color:blue;">**Set or update the deal budget**</mark>

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

**budget** -❗required, number; the deal value

**order\_id** - (optional) deal ID. If not provided, applies to the client’s current active deal.

To use order\_id correctly:

1. You can manually specify it — get the deal ID and pass it as the function parameter if you want to target a specific deal.

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

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

1. Retrieve it using the get\_order\_id() function, because the built-in order\_id variable returns the value in the format {client\_id}-{order\_id}, which may cause incorrect behavior.

<mark style="background-color:blue;">**Retreaving lists of deals**</mark> \
((excluding archived, successful, or failed deals))

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

<mark style="background-color:blue;">**Get a list of successful deal IDs**</mark>

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

<mark style="background-color:blue;">**Get a list of failed deal IDs**</mark>

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

<mark style="background-color:blue;">**Retrieving the value of a deal variable**</mark>

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

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - deal ID&#x20;

<mark style="color:red;">**!**</mark>**&#x20;variable** - variable name whose value you want to retrieve

<mark style="background-color:blue;">**Retrieving deal data**</mark>

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

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - deal ID

**names** - an array of variable names to retrieve. If omitted, the function returns all variables for the specified deal

The function returns a dictionary containing the variables listed in the **names** array for the deal identified by **order\_id**. If **names** is not provided, it returns a dictionary with all variables of the specified deal.

<mark style="background-color:blue;">**Adding a deal variable**</mark>

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

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - deal ID

<mark style="color:red;">**!**</mark>**&#x20;variable** - the name of the variable to add or update in a deal

{% hint style="warning" %}
If you want to change the deal’s parameters "name" or "description," use the variable names "name" or "description" respectively.
{% endhint %}

<mark style="color:red;">**!**</mark>**&#x20;value** - variable value

<mark style="background-color:blue;">**Adding multiple deal variables**</mark>

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

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;order\_id** - deal ID.&#x20;

<mark style="color:red;">**!**</mark>**&#x20;variables\_dict** - a dictionary of variables

<mark style="background-color:blue;">**Moving to the next funnel state**</mark>

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

Parameters:\
**order\_id** - deal ID. If not specified, the current active deal will be moved.\
The order of deal states is defined according to the sequence set in MavibotCRM.

<mark style="background-color:blue;">**Retrieving the funnel stage in MavibotCRM**</mark>

**get\_state\_id(client\_id, order\_id)** \
You can also copy the pipeline state ID directly from the **"State settings"**.

Parameters:

**order\_id -** client deal ID

You can call the function with or without the **order\_id** parameter. If order\_id is omitted, the function will return the pipeline state ID for the current active deal.

For correct usage of order\_id:

1. You can specify it manually by obtaining the deal ID and passing it as the function parameter when you want to target a specific deal.
2. Retrieve it using the get\_order\_id() function, because the built-in order\_id variable returns a value in the format {client\_id}-{order\_id}, which can cause incorrect behavior.

<mark style="background-color:blue;">**Moving a lead through the MavibotCRM funnel by state ID**</mark>

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

Parameters:\ <mark style="color:red;">**!**</mark> **state\_id -** funnel state ID\
**order\_id (** optional) -  the deal ID to move through the pipeline. If omitted, the current active deal will be moved.

<mark style="background-color:blue;">**Getting deal ID by variable name and value**</mark>

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

Parameters:\ <mark style="color:red;">!</mark> var\_name - variable name\ <mark style="color:red;">!</mark> var\_value - variable value;\
client\_id - (optional) client deal ID; defaults to the client ID in the bot

<mark style="background-color:blue;">**Getting date and time of the latest deal**</mark>

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

Parameters:\
client\_id - (optional) the client deal ID; defaults to the client ID in the bot;\
df\_fmt - (optional) format for the returned date and time; default is "%d.%m.%y %H:%M"

<mark style="background-color:blue;">**Getting number of client deals**</mark>

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

Parameters:\
client\_id -  (optional) the deal client ID; defaults to the client ID in the bot;\
state\_id - (optional) the deal state ID in the pipeline;\
get\_all - (optional) filter flag for the active parameter; default is 1 (filtering by active is disabled);\
active - used only when get\_all is 0; filters active deals; default is 1 (returns only active deals);

<mark style="background-color:blue;">**Get count of deals in a specific deal state**</mark>

get\_count\_orders(id) - returns the number of deals currently in a specific pipeline state by state ID.

The function takes a single parameter:

<mark style="color:red;">**!**</mark> id - the deal state ID.&#x20;

Example of function usage:

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

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

The stage ID can be found in the settings.

Next, you need to enter the function in the calculator as follows:

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

When testing the bot, the bot’s response will consist of the number of deals in the state specified by the value passed to the function.

<mark style="background-color:blue;">**Deleting a deal**</mark>

delete\_order(order\_id) — deletes a deal in **MaviBotCRM**.

order\_id - (optional) the deal ID to delete. If omitted, the most recent deal will be deleted.&#x20;

</details>

<details>

<summary>Examples</summary>

All functions are simple to use.
\
For example, let’s create a new deal and send its number to the client:

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

<div data-with-frame="true"><figure><img src="/files/XWWzv9eqboGXZSps9G4S" alt="" width="563"><figcaption><p>Client request registration</p></figcaption></figure></div>

You can get the client’s current active deal ID using the function get\_order\_id(), or retrieve the full list of the client’s deals using get\_active\_orders\_ids().

<div data-with-frame="true"><figure><img src="/files/ecvAoCD8dQlt9nCtNlo8" alt="" width="563"><figcaption><p>Retrieving the current active deal ID</p></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/vb0lyUwR79CV9qfZrMqS" alt="" width="563"><figcaption><p>Retrieving the list of active deals</p></figcaption></figure></div>

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

</details>

<details>

<summary>Code example for copying</summary>

<pre><code><strong>/* Create a new deal */
</strong>oid = create_order()

/*Retrieve the client's active deal ID*/
oid = get_order_id()

/*Retrieve the list of active deals*/
res = get_active_orders_ids()

/*Add or update a single variable in the deal*/
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="background-color:blue;">**Setting a successful deal tag**</mark>

set\_order\_status\_success()

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

Parameters:

**order\_id** - the deal ID. If the parameter is not specified, the tag will be set for the current active deal.
{% endtab %}
{% endtabs %}

### <mark style="background-color:blue;">**Setting a failed deal tag**</mark>&#x20;

set\_order\_status\_fail()

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

Parameters:

**order\_id** - the deal ID. If the parameter is not specified, the tag will be set for the current active deal.
{% endtab %}
{% endtabs %}

### <mark style="background-color:blue;">**Setting an archived deal tag**</mark> &#x20;

set\_order\_status\_archive()

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

Parameters:

**order\_id** - the deal ID. If the parameter is not specified, the tag will be set for the current active deal.
{% endtab %}

{% tab title="Examples" %}
/\*Archive the current active deal\*/

`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/chatbot/functions/calculator/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.