Working with clients and CRM

was_in_state(message_id) checks whether a client was in the selected state (block). You can get the block number from the editor.

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()

free_client() unassigns the responsible operator. 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.

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

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()

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()

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.

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

clear_unread() marks a dialogue as read

unsubscribe() Function to unsubscribe from bot messages. An example is provided in this article. For the unsubscribed client, a symbol will appear — a red message with a cross.

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.

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

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

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.

create_task(email, name, date_srok, description, time_srok) – creates a task

Parameters: ! email - responsible person email ! name - task name ! date_srok - due date, date ! description - task description time_srok - due time, time

update_task(task_id,email, name, date_srok, description, time_srok) - updates a task

Parameters: ! task_id- task ID ! email - responsible person email ! name - task name ! date_srok - due date, date ! description - task description time_srok - due time, time

done_task(task_id)- marks a task as completed

Parameters: ! task_id- task ID

delete_task(task_id) – deletes a task

Parameters: ! task_id- task ID

Let's create a task for the operator:

Update the due date and description.

Mark the task as completed.

Task deletion

task_id=create_task('[email protected]', 'Test', '22.01.2023', 'test task', '08:00') status=delete_task(task_id)

Retrieving the current deal ID

get_order_id() - returns the deal state.

Creating a new deal

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: ! name - (optional), the deal name. If not provided, the function applies to client’s current active deal.

! 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

Set or update the deal name

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.

Set or update the deal budget

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.

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.

Retreaving lists of deals ((excluding archived, successful, or failed deals))

get_active_orders_ids()

Get a list of successful deal IDs

get_success_orders_ids()

Get a list of failed deal IDs

get_fail_orders_ids()

Retrieving the value of a deal variable

get_order_var(order_id, variable)

Parameters:

! order_id - deal ID

! variable - variable name whose value you want to retrieve

Retrieving deal data

get_order_vars(order_id, names)

Parameters:

! 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.

Adding a deal variable

set_order_var(order_id, variable, value)

Parameters:

! order_id - deal ID

! variable - the name of the variable to add or update in a deal

! value - variable value

Adding multiple deal variables

set_order_vars(order_id, variables_dict)

Parameters:

! order_id - deal ID.

! variables_dict - a dictionary of variables

Moving to the next funnel state

move_order_to_next_state(order_id)

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.

Retrieving the funnel stage in MavibotCRM

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.

Moving a lead through the MavibotCRM funnel by state ID

change_state(state_id, order_id)

Parameters: ! 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.

Getting deal ID by variable name and value

get_order_id_by_var_value(var_name, var_value, client_id)

Parameters: ! var_name - variable name ! var_value - variable value; client_id - (optional) client deal ID; defaults to the client ID in the bot

Getting date and time of the latest deal

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"

Getting number of client deals

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);

Get count of deals in a specific deal state

get_count_orders(id) - returns the number of deals currently in a specific pipeline state by state ID.

The function takes a single parameter:

! id - the deal state ID.

Example of function usage:

The stage ID can be found in the settings.

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

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.

Deleting a deal

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.

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

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().