# Gamification methods

## Gamification methods in Instagram and Facebook 

{% hint style="warning" %}
For configuring function operations, we recommend using the gamification[ template for Instagram chats as a reference](#gamification-methods-in-instagram-and-facebook). 
{% endhint %}

To use the functions listed below, you need to declare common variables in the **Project settings**:

<table data-header-hidden><thead><tr><th width="270.3333333333333">Variable name</th><th width="323">Variable purpose</th><th align="center">Value, example</th></tr></thead><tbody><tr><td>comment_score</td><td>how many points to award for comments</td><td align="center">10</td></tr><tr><td>comment_max_actions </td><td>maximum number of comments per day</td><td align="center">5</td></tr><tr><td>min_comment_len</td><td>minimum comment length</td><td align="center">25</td></tr><tr><td>stories_score</td><td>how many points to award for reactions in stories</td><td align="center">15</td></tr><tr><td>stories_max_actions</td><td>maximum number of actions per day</td><td align="center">1</td></tr><tr><td>stories_mention_score</td><td>how many points to award for mentions in stories</td><td align="center">5</td></tr><tr><td>stories_mention_max_actions</td><td>maximum number of actions per day</td><td align="center">2</td></tr><tr><td>post_mention_score</td><td>how many points to award for mentions in post</td><td align="center">10</td></tr><tr><td>post_mention_max_actions</td><td>maximum number of actions per day</td><td align="center">3</td></tr><tr><td>end_game_date</td><td>game end date</td><td align="center">30.12.2021</td></tr></tbody></table>

**game\_add\_comment**(text=None) - adds points for a comment on Instagram or FB; you can also pass any text.

**game\_add\_stories**() - adds points for reactions in stories

**game\_add\_message**() - add points for Direct messages

**game\_add\_stories\_mention**() - add points for mentions in stories

**game\_get\_user\_score**() - return's user points

**game\_get\_user\_place**() - displays user’s position in the ranking

**game\_get\_leader\_score**() - returns leader’s points in the ranking

**game\_get\_top(count=99999999, shift=0, humanize=False, delimiter=None, platform=None)** - calling the function without arguments returns a sorted ranking as an array of users. It accepts the following 5 parameters: **count** - how many users to return; **shift** - the starting rank position for the selection (0 means the list starts from the leader and goes downward by points; for example, 3 means the selection starts from the 4th place and below); **humanize** **0** - returns an array of user dictionaries, **1** returns a formatted list for display to the user; **delimiter** - the separator between the username and their score (used if **humanize=1**); **platform 1** - outputs the Instagram login (e.g., **@nik**) instead of the username.

Example 1: game\_get\_top(10, 0, 1, ' - ') will return: John - 40 Anna - 30 George - 10\
\
Example 2: game\_get\_top(3, 0, 1, ' - ', 1) will return: @john - 40 @anna - 30 @privet - 10&#x20;

**game\_add\_score**(count=1, client\_id=None) - adds points to user

**game\_set\_score**(score, client\_id=None) - sets user's total points

**game\_ban\_player**() - blocks user

**game\_unban\_player**() - unblocks user

**game\_user\_banned**() - returns user’s ban status; True if banned, False if not

\# allows working with arbitrary values in leaderboard.&#x20;

**game\_add\_value**(val\_name, count=1, client\_id=None) -&#x20;

**game\_set\_value**(val\_name, value, client\_id=None)

{% hint style="info" %}
If **client\_id** is not provided, the function works with the current client.
{% endhint %}

**game\_minus\_user\_score**(count =10) - subtracts points from user (**count** - how many points to subtract)

**game\_get\_today\_user\_comment\_action**() - number of comments made by user today

**game\_get\_today\_user\_message\_actions**() - number of messages sent by user today

**game\_get\_today\_user\_stories\_actions**() - number of stories posted by user today

**game\_get\_today\_user\_mention\_actions**() - number of user activities (mentions) today

**game\_get\_today\_user\_post\_mention\_actions**() - number of posts with mentions by user today

**game\_get\_total\_comment\_action**() - total number of comments during the entire game

**game\_get\_total\_message\_actions**() -  total number of messages during the entire game

**game\_get\_total\_stories\_actions**() - total number of stories during the entire game

**game\_get\_total\_stories\_mention\_actions()** - total number of mentions in stories during the entire game

**game\_get\_total\_post\_mention\_actions()** - total number of mentions in posts during the entire game

## Getting ranking in Telegram &#x20;

{% hint style="warning" %}
For configuring function operations, we recommend using the gamification[ template for Telegram chats as a reference](#getting-ranking-in-telegram).
{% endhint %}

In the global variables, you should create a dictionary named tg\_thanks\_score\_data to store client information in the following format:

`{"total_thanks":20,"326659632":{"name":"John","user_name":"john","score":5},"403051597":{"name":"Timm","user_name":"dbeing","score":15,"banned":false}}`

**tg\_get\_top(count=99999999, shift=0, humanize=False, delimiter=None)**&#x20;

Parameters:&#x20;

**count** - how many users to return\
**shift** - the starting rank position for selection (0 means the list starts from the leader and goes downward by points; for example, 3 means selection starts from the 4th place and below)\
**humanize** - 0 returns an array of user dictionaries, 1 returns a formatted list for displaying to the user\
**delimiter** -  the separator between the username and his score (used if humanize=1)

**tg\_get\_user\_info()**

{'score': user\_score, 'place': place, 'name': name}


---

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