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.

We strongly recommend reviewing the sections “Basics of Bot Building on Mavibot.ai” ссылка and “Google Sheets” ссылка before creating your chatbot flow.

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; ссылка

2. checking if the new user is already in the database; ссылка

3. notifying the inviting user about a new referral; ссылка

4. recording users in the database; ссылка

5. requesting a list of referrals. ссылка

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:

How to create a block by mouse click

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

How to create a block with a selected type

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

Fig. 1

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

Fig. 2 How to insert a link into a flow block

Let's take a closer look at the template link: https://wa.me/(your 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

• select type — Link, and paste it into the 'Attachment URL' field:

Pic. 3. Attachment -> type ->link

In this case, the link will visually appear shortened:

Fig. 4. View in WhatsApp

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

Fig. 5. How to test a bot

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

Testing the link functionality

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

User verification

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.

Splitter() fucnction

splitter(str, s, n) - splits a string into parts. The function returns an array of elements.

Parameters:

! str - the original string

! s - the string delimiter

n - the maximum number of elements

Example

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$

• Поменять русский номер! Russian phone number only: ^((\+7|7|8)+([0-9]){10})$

Fig. 9. Regular expression for phone number

For information on working with regular expressions, please refer to the article titled "Regular Expressions." ссылка

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:

Fig. 9

! Function URL: https://store.salebot.pro/function/findcell ссылка

! JSON request parameters:

{ "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

Search by column and display text from the entire row

The return parameter must be set to 0. { "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:

data — response

data|0 — Cell 1

data|1 — Cell 2

data|2 — Cell 3

data|3 — Cell 4

cell_number|row — row

cell_number|col — column

To learn more about the available functions for working with tables, refer to the article titled "Google Sheets." ссылка

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

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

Fig. 11.

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.

! Request URL: https://chatter.salebot.pro/api/#{api_key}/whatsapp_message ссылка

Fig. 12. Notification in Whatsapp

ПYou can find more details about API request functions here. ссылка

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.

The table must have a header filled in (at least one cell in the first row).

! Function URL https://store.salebot.pro/function/gsheets ссылка

! JSON request parameters:

{ "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.

! Function URL: https://store.salebot.pro/function/findcell ссылка

! JSON request parameters:

{ "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": "!" }

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