# Working with lists

## **Create a new list** 

create\_list()

{% tabs %}
{% tab title="Description" %}
Enter the function in the **"Calculator"** field in the block settings: 

**create\_list(name)** - creates new list. The result is list ID.

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;name** - list name. The name is specified in single quotes.
{% endtab %}

{% tab title="Example" %}
`list_id = create_list("registered")`

<div data-with-frame="true"><figure><img src="/files/f9pGPRE9yq42aYxsu2im" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

## Creating a list from the block without duplicates

create\_list\_if\_not\_exist()

{% tabs %}
{% tab title="Description" %}
**create\_list\_if\_not\_exist('list\_name')** - creates a new list if one with the given name does not exist yet and returns its identifier, or returns the identifier of the existing list.

Required parameter:

**list\_name** - name for a new list to be created.
{% endtab %}

{% tab title="Example" %}

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

```
new_list = create_list_if_not_exist('List of participants')
```

{% endtab %}
{% endtabs %}

## Adding a client to the list

add\_to\_list()

{% tabs %}
{% tab title="Description" %}
**add\_to\_list(list\_id, client\_id)** - adds a client to a list. The function returns none.

Parameters:

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

**client\_id** - MaviBot client ID. If not provided, the current client’s ID is used.
{% endtab %}
{% endtabs %}

## Moving a client to the list

move\_to\_list()

{% tabs %}
{% tab title="Description" %}
**move\_to\_list(list\_id, client\_id)** - moves a client to the list (Important! The client is removed from all other lists and moved to the specified one). The result is a boolean value (True or False).

Parameters:

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

**client\_id** - MaviBot client ID. If not provided, the current client’s ID is used.
{% endtab %}
{% endtabs %}

## Removing a client from the list

remove\_from\_list()

{% tabs %}
{% tab title="Description" %}
**remove\_from\_list(list\_id, client\_id)** - removes a client with the specified client\_id from the list.

Parameters:

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

**client\_id** - MaviBot client ID. If not provided, the current client’s ID is used.
{% endtab %}
{% endtabs %}

## Deleting lists&#x20;

remove\_list\_from\_project(list\_id, clear\_list)

{% tabs %}
{% tab title="Description" %} <mark style="color:red;">**!**</mark>**&#x20;list\_id** - required parameter; the ID of the list to be deleted.

**clear\_list** — optional parameter; accepts two values: True or False (default is False).

If you do not provide this parameter and the list contains clients, you will receive the following response:
***"Can't delete list, list not empty"***

If the list is empty, it will be deleted without issues. However, if you set **clear\_list** to True, the list will be deleted regardless of whether it contains clients or not.
{% endtab %}
{% endtabs %}

## Deleting tags

remove\_label\_from\_project(list\_id, clear\_list)

{% tabs %}
{% tab title="Description" %} <mark style="color:red;">**!**</mark>**&#x20;list\_id** - required parameter; the ID of the tag to be deleted.

**clear\_list** - optional parameter; accepts two values: True or False (default is False).

If this parameter is not provided and the tag is assigned to clients, you will receive the following response:
&#x20;***"Can't delete list, list not empty"***

If the tag is not assigned to any clients, it will be deleted without issues. However, if **clear\_list** is set to True, the tag will be deleted regardless of whether it is assigned to clients or not.
{% endtab %}
{% endtabs %}

## Clear the client list&#x20;

clear\_list()

{% tabs %}
{% tab title="Description" %}
**clear\_list(list\_id)** - clears the client list

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;list\_id -** list ID. After use, all clients will be removed from the specified list.&#x20;
{% endtab %}
{% endtabs %}

## Get the number of clients in the list

list\_size()

{% tabs %}
{% tab title="Description" %}
**list\_size(list\_id)** – counts the total number of clients in the list

Parameters:&#x20;

<mark style="color:red;">**!**</mark>**&#x20;list\_id**- list ID
{% endtab %}
{% endtabs %}

## Count the number of unique client entries across multiple lists

lists\_joint\_count()

{% tabs %}
{% tab title="Description" %}
**lists\_joint\_count(massive\_list)** – counts the total number of unique client entries across multiple lists. The function takes an array of list IDs as input and returns a number.

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;massive\_list** - an array containing the list IDs in which the unique client entries will be counted. The format is: **\['list\_id1', 'list\_id2', ..., 'list\_idN']**
{% endtab %}

{% tab title="Code example for copying" %}

```
/*Creating a list*/
list_id = create_list('New list')

/*Check if the client is in the list*/
k=inlist(list_id, client_id)

/*Get the size of the list — total number of clients in the list*/
razm=list_size(1)

/*Get the total number of unique client entries across multiple lists*/
k=lists_joint_count('[144636,144634]')
```

{% endtab %}
{% endtabs %}

## Check if a client is in the list

inlist()

{% tabs %}
{% tab title="Description" %}
**inlist(list\_id,client\_id)** - checks if a client is in the list. The result is a boolean value (True or False).

Parameters:

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

**client\_id** - MaviBot client ID. If not provided, the current client’s ID is used.&#x20;
{% endtab %}
{% endtabs %}

## Check if a chat participant is in a specific list

some\_client\_in\_list()

{% tabs %}
{% tab title="Description" %}
**some\_client\_in\_list(list\_id, recepient)**

Parameters:

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

<mark style="color:red;">**!**</mark>**&#x20;recepient** - messenger user ID being checked (platform\_id). For chats, the value of the variable is chat\_member\_id.&#x20;

It returns values:

True - client is in the list;

False -  client is not in the specified list.
{% endtab %}

{% tab title="Example" %}

<div data-with-frame="true"><figure><img src="/files/teEQppVUbzFaNNSxEgeb" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Code example for copying" %}

```
/*Example of checking if a chat participant is in the list, where the first parameter is the list ID, and the second is the user's chat ID*/

r = some_client_in_list(123456, chat_member_id)
```

{% endtab %}
{% endtabs %}

### Retrieving elements from a list

count\_occurrences()

{% tabs %}
{% tab title="Description" %}
**count\_occurrences(array, element)** - returns the number of specified elements contained in the list.

Parameters:

**array** - required parameter; list of elements

**element** - required parameter; element to count
{% endtab %}
{% endtabs %}

## Getting a random client ID from the list

random\_list\_member(list\_id)

{% tabs %}
{% tab title="Description" %}
random\_list\_member(list\_id) - returns one random client ID in the specified list.

list\_id - required parameter, list ID.

The list ID, which contains your clients, can be found in the **"Lists"** section:

<figure><img src="/files/5m4ZGR0UBjq8mOaGryUF" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## Example of working with lists in the Calculator

<details>

<summary>example</summary>

Let's look at an example of using functions in the **"Calculator"** for working with lists.

<mark style="color:red;">**Important!**</mark> You need to save a new list ID in order to use it later. To do this, assign the function result to a variable, i.e. list\_id = ...

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

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

Now you can easily perform other operations with the list — check if a client is in the list, add, move, or remove a client.

For example, let's check if a client is in the list with ID 12333:

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

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

It is very convenient to use lists when displaying statistical data:

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

It’s often necessary to get the total number of unique entries across a set of lists — this can easily be done using the `lists_joint_count()` function.

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

а

</details>


---

# 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/lists.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.