# Referral program

A **referral program** is a system that rewards customers or company partners by offering incentives or bonuses for bringing in new participants.

From a technical perspective, a referral program includes several key components:

1. An **invite link**—a unique identifier that allows users or clients to invite others to participate in the program. The inviter can share this link through various channels (for example, this article will cover generating links via a WhatsApp bot, but referral program links can be shared through any messenger you prefer).
2. A **participant database**, implemented through the integration of MaviBot and Google Sheets functionality, where information about both the invited and inviting users is recorded.
3. A **referral tracking system** that monitors actions related to bringing in new participants via referral links. The system stores data on all referrals, allowing you to check whether a given referral already exists in the system as a previously invited user.

{% hint style="success" %}
We strongly recommend reviewing the sections “Basics of Bot Building on Mavibot.ai” <mark style="color:red;">**ссылка**</mark> and “Google Sheets” <mark style="color:red;">**ссылка**</mark> before creating your chatbot flow.
{% endhint %}

## Referral System in WhatsApp

The functionality of the bot being created will include blocks consisting of the following components:

1. generation of a referral (affiliate) link; <mark style="color:red;">**ссылка**</mark>
2. checking if the new user is already in the database; <mark style="color:red;">**ссылка**</mark>
3. notifying the inviting user about a new referral; <mark style="color:red;">**ссылка**</mark>
4. recording users in the database; <mark style="color:red;">**ссылка**</mark>
5. requesting a list of referrals. <mark style="color:red;">**ссылка**</mark>

### Referral link generation

Let’s create a block with an embedded link that the bot will send to the user upon the command “link.” To do this, create a new block in the flow using one of two methods:

1. Double-click on an empty area in the builder canvas:

<figure><img src="/files/uFeKTm7dryJkIDcWKBWJ" alt="" width="563"><figcaption><p>How to create a block by mouse click</p></figcaption></figure>

2. By using the **"Save" button** at the bottom of the screen and selecting the block type:

<figure><img src="/files/k1Sny84vHFZ4PTp1jTg2" alt="" width="563"><figcaption><p>How to create a block with a selected type</p></figcaption></figure>

After that, in the block’s condition, enter the word **“Link”** and set the match type to **“Ignore typos and inaccuracies”** (this is useful in case of user typos or other message errors):

<figure><img src="/files/tPOrXzDKBgkhKrPdTbbZ" alt="" width="310"><figcaption><p>Fig. 1</p></figcaption></figure>

To identify who referred the user, the bot creates a link using the following template: [https://wa.me/(your](https://wa.me/%28your) phone number linked to the bot)text=You%20were%20recommended%20by%20#{phone}%20😌Hello

<figure><img src="/files/KT1fEoRhwN2Au9693MWW" alt=""><figcaption><p>Fig. 2 How to insert a link into a flow block</p></figcaption></figure>

Let's take a closer look at the template link: [https://wa.me/(your](https://wa.me/%28your) phone number linked to the bot)?text=You%20were%20recommended%20by%20#{phone}%20😌Hello, where:

1. Replace the brackets "(your phone number linked to the bot)" with the corresponding phone number;
2. \#{phone} is automatically replaced with the phone number of the user who requested their partner link.

We send the generated link not as block text, but as an attachment — a clickable link with a notification (see Fig. 2 and Fig. 3):

* choose to insert an attachment
* &#x20;select type — Link, and paste it into the 'Attachment URL' field:

<figure><img src="/files/nxvyNobGXT9ghi9jXdf9" alt="" width="323"><figcaption><p>Pic. 3. Attachment -> type ->link</p></figcaption></figure>

In this case, the link will visually appear shortened:

![Fig. 4. View in WhatsApp](https://lh5.googleusercontent.com/vW_tS8GIDqDbN0PkdgQsa6xeeiBBfxuC4Qp8QuzXRz98yI4fphKEUIE22MiBcq4q_RvlQLlAEtlVzcL-hln5DbHaM-F1tuSBNp9y5zhvR5efRmjzDbcTlox5AUDvhnVorlBEdYsX)

Let's test the link functionality using the **"Test Bot"** feature.

<figure><img src="/files/grAhttWNnI2IczoT5oNq" alt="" width="237"><figcaption><p>Fig. 5. How to test a bot</p></figcaption></figure>

Here’s the result: the link directs the user to the appropriate messenger chat with your phone number:

<figure><img src="/files/2E75dgfuqzE1ukiinwfr" alt="" width="563"><figcaption><p>Testing the link functionality</p></figcaption></figure>

This way, you’ve successfully generated an invitation link that potential users can use to access the chatbot. Additionally, when clicking this link, the user is redirected to the chat window with a pre-filled message. (See Fig. 6)

![Fig. 6. Filled message in WhatsApp](https://lh5.googleusercontent.com/60e0Pcv5362t53lD5Y0evDiAAmeyCoL-eSg_1wXPsgFiKw-Nn0Zmb3WUwBE16lCBr84e56RB863VJd8GFW4kqZAsXMRzEEIFum_ThIdbr58IqV9_JP-kp3IVnfNZoAsJ7d_n4OI4)

### User verification&#x20;

**Using functions and regular expressions in a block**

The verification and database entry command will only work if the bot finds a phone number in the user’s message. Therefore, it’s necessary to split the received phrase into parts.

For this, the function **splitter()** is used.

{% tabs %}
{% tab title="Splitter() fucnction" %}
**splitter(str, s, n)** -  splits a string into parts. The function returns an array of elements. <br>

Parameters:

<mark style="color:red;">**!**</mark> <mark style="color:red;">**str**</mark> <mark style="color:red;"></mark><mark style="color:red;">- the original string</mark>

<mark style="color:red;">**!**</mark> <mark style="color:red;">**s**</mark> <mark style="color:red;"></mark><mark style="color:red;">- the string delimiter</mark>

**n** - the maximum number of elements
{% endtab %}

{% tab title="Example" %}
String splitting function:

<figure><img src="/files/Aozg4NBb98SGVOEgUHA8" alt=""><figcaption><p>Fig. 8. Splitting the string</p></figcaption></figure>
{% endtab %}
{% endtabs %}

Next, the bot needs to verify whether the sequence of digits in the string is indeed a phone number. To do this, we use the following regular expressions:

* General phone number: `^(\+)?((\d{2,3}) ?\d|\d)(([ -]?\d)|( ?(\d{2,3}) ?)){5,12}\d$`
* <mark style="color:red;">**Поменять русский номер!**</mark> Russian phone number only: `^((\+7|7|8)+([0-9]){10})$`

<figure><img src="/files/tDXOZkFKWBxmsCEk9YGv" alt="" width="500"><figcaption><p>Fig. 9. Regular expression for phone number</p></figcaption></figure>

{% hint style="info" %}
For information on working with regular expressions, please refer to the article titled "Regular Expressions." <mark style="color:red;">**ссылка**</mark>
{% endhint %}

After the bot verifies that the sequence of digits is indeed a phone number, save it from the message as a variable (for example, #{reff}).

**Checking the user’s phone number as a referral in the database**

Now it’s necessary to check whether the phone number of the user who followed the link is already a referral (previously invited by someone and recorded in our database). To do this, create a block in the flow with a column search function.

Use the column search function by clicking **"API Request"** in the block, where you need to set the following parameter values:

<figure><img src="/files/rbwoMxF5bo1bIxrVRfxy" alt="" width="337"><figcaption><p>Fig. 9</p></figcaption></figure>

<mark style="color:red;">**!**</mark>**&#x20;Function URL**: <https://store.salebot.pro/function/findcell> <mark style="color:red;">**ссылка**</mark>

<mark style="color:red;">**!**</mark>**&#x20;JSON** **request parameters:**&#x20;

**{ "id": "your\_table\_id", "find": "text\_to\_search", "col": column\_number\_to\_search\_in, "return": column\_number\_to\_return, "creds\_path": "path\_to\_your\_auth\_credentials\_file" }**

Response parameters:

"status": "1" — value found

"status": "0" — value not found

"data" — the found value

"cell\_number" — the found cell location

{% tabs %}
{% tab title="Search by column and display text from the entire row" %}
The return parameter must be set to 0.\
\&#xNAN;**{ "id": "your\_table\_id", "find": "text\_to\_search", "col": 2, "return": 0 }**\
Response: {"status":"1","data":{"0":"\u0441\u043e\u043b\u043d\u0446\u0435","1":"\u0440\u0430\u0441\u0441\u0432\u0435\u0442","2":"\u043a\u0440\u044b\u0448\u0430","3":"","4":"\u043d\u0435\u0431\u043e"},"cell\_number":{"row":4,"col":1, "col\_letter":"A"}}\
Response breakdown:&#x20;

data — response

data|0 — Cell 1

data|1 — Cell 2

data|2 — Cell 3

data|3 — Cell 4

cell\_number|row — row&#x20;

cell\_number|col — column&#x20;
{% endtab %}
{% endtabs %}

{% hint style="info" %}
To learn more about the available functions for working with tables, refer to the article titled "Google Sheets." <mark style="color:red;">**ссылка**</mark>
{% endhint %}

### Notification block

To notify the user who shared the referral link that a new client has successfully followed it, we will create a dedicated block. For sending a notification about the creation of a new referral, use the following request parameters (type: **POST - JSON**):

<figure><img src="/files/cTcKJ8l4KDD4g57zCiMh" alt="" width="357"><figcaption></figcaption></figure>

Requests are made using the **POST** method to the URL: **`https://chatter.salebot.pro/api/{api_key}/{action}`** Where:

* **`api_key`** is your project’s API access key, which can be obtained in the project settings (see Fig. 11).

<figure><img src="/files/1njNQnDenYUJjq3KGK3x" alt="" width="563"><figcaption><p>Fig. 11.</p></figcaption></figure>

You can retrieve the access key using the variable **#{api\_key}**, which stores the current generated access token. **Don’t forget to generate the token before using it.**

<mark style="color:red;">**!**</mark>**&#x20;Request URL:** [**https://chatter.salebot.pro/api/#{api\_key}/whatsapp\_message**](https://chatter.salebot.pro/api/#{api_key}/whatsapp_message) <mark style="color:red;">**ссылка**</mark>

<figure><img src="/files/8dxvovqcdzkudYBoHP9O" alt="" width="563"><figcaption><p>Fig. 12. Notification in Whatsapp</p></figcaption></figure>

{% hint style="info" %}
ПYou can find more details about API request functions here. <mark style="color:red;">**ссылка**</mark>
{% endhint %}

### Adding the invited and inviting users to the database

To do this, we’ll use row-by-row entry into specific columns, which is done using the **mapping** function.

{% hint style="danger" %}
The table must have a header filled in (at least one cell in the first row).
{% endhint %}

<mark style="color:red;">**!**</mark>**&#x20;Function URL** <https://store.salebot.pro/function/gsheets> <mark style="color:red;">**ссылка**</mark>

<mark style="color:red;">**!**</mark>**&#x20;JSON** **request parameters:**&#x20;

{ "id": "your\_table\_id", "mapping": { "a": "#{variable}", "b": "#{another\_variable}", "d": "plain text" } }

If you want to write rows not on the first sheet, add the parameter **list\_name** to the request:

{ "id": "your\_table\_id", "mapping": { "a": "plain text", "b": "#{variable}" }, "list\_name": "SheetName" }

Parameters:

* **id** — table identifier\*
* **a, b, c, d** — column names
* **list\_name** — your sheet name (e.g., "Sheet2")

\*Make sure to replace with your actual table ID.

> Response example:  **{"number\_row":8}**

If the request executes successfully, the response will include the row number, which you can save and use for further operations.

### Viewing the list of referrals

Let’s add an additional command to the bot that allows users to view their list of referrals.

To find all specified values in a column, use the **findcell** function with the parameter **"find\_all"**. This will locate all occurrences of the **"find\_all"** value in the specified **"col"** column and return a list of unique values from the **"return"** column as a string.

<mark style="color:red;">**!**</mark>**&#x20;Function URL:**  <https://store.salebot.pro/function/findcell> <mark style="color:red;">**ссылка**</mark>

<mark style="color:red;">**!**</mark>**&#x20;JSON request parameters:**&#x20;

{ "id": "table\_id", "find\_all": "search\_value", "list\_name": "sheet\_name", "col": "column\_number\_to\_search\_in", "return": "column\_number\_to\_return\_values\_from", "find": "!" }

<figure><img src="/files/IiZ4GLj63q030eX1r0Tb" alt="" width="449"><figcaption></figcaption></figure>

In the saved values, specify:

list → List

quantity → Quantity

For the user, display the message:
*"You have referred #{spisok}, your total referrals: #{quantity}"*

In other messengers, implementing such a referral system is even easier because the inviter’s data is passed as a hidden parameter during the link transition, so the new user doesn’t need to send a message like *“I was invited by this number.”*


---

# 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/how-to-do.../referral-program.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.