# Реферальная программа

A **реферальная программа** — это система, которая вознаграждает клиентов или партнеров компании, предлагая стимулы или бонусы за привлечение новых участников.

С технической точки зрения реферальная программа включает несколько ключевых компонентов:

1. Пригласительную **ссылку**— уникальный идентификатор, который позволяет пользователям или клиентам приглашать других к участию в программе. Приглашающий может делиться этой ссылкой через различные каналы (например, в этой статье будет рассмотрено создание ссылок через бот WhatsApp, но ссылки реферальной программы можно распространять через любой мессенджер, который вы предпочитаете).
2. A **базу данных участников**, реализованную через интеграцию MaviBot и функциональности Google Sheets, где записывается информация как о приглашенных, так и о приглашающих пользователях.
3. A **систему отслеживания рефералов** которая отслеживает действия, связанные с привлечением новых участников по реферальным ссылкам. Система хранит данные обо всех рефералах, позволяя проверить, существует ли уже данный реферал в системе как ранее приглашенный пользователь.

{% hint style="success" %}
Мы настоятельно рекомендуем ознакомиться с разделами «Основы построения ботов на Mavibot.ai» <mark style="color:красный;">**ссылка**</mark> и «Google Sheets» <mark style="color:красный;">**ссылка**</mark> перед созданием сценария вашего чат-бота.
{% endhint %}

## Реферальная система в WhatsApp

Функциональность создаваемого бота будет включать блоки, состоящие из следующих компонентов:

1. генерация реферальной (партнерской) ссылки; <mark style="color:красный;">**ссылка**</mark>
2. проверка, находится ли новый пользователь уже в базе данных; <mark style="color:красный;">**ссылка**</mark>
3. уведомление приглашающего пользователя о новом реферале; <mark style="color:красный;">**ссылка**</mark>
4. запись пользователей в базу данных; <mark style="color:красный;">**ссылка**</mark>
5. запрос списка рефералов. <mark style="color:красный;">**ссылка**</mark>

### Генерация реферальной ссылки

Давайте создадим блок со встроенной ссылкой, которую бот отправит пользователю по команде «link». Для этого создайте новый блок в сценарии одним из двух способов:

1. Дважды щелкните по пустой области на холсте конструктора:

<figure><img src="/files/6c069d6c1fbd71af83c7b0bc6b030e3cbe57817b" alt="" width="563"><figcaption><p>Как создать блок щелчком мыши</p></figcaption></figure>

2. С помощью **кнопки «Save»** внизу экрана и выбрав тип блока:

<figure><img src="/files/019c857b2e798f7d1f21eb27137a4c5b2cc49054" alt="" width="563"><figcaption><p>Как создать блок с выбранным типом</p></figcaption></figure>

После этого в условии блока введите слово **«Link»** и установите тип совпадения **«Игнорировать опечатки и неточности»** (это полезно в случае опечаток пользователя или других ошибок в сообщении):

<figure><img src="/files/f63fea5887c4a1d083abb67b79b054be0ad85823" alt="" width="310"><figcaption><p>Рис. 1</p></figcaption></figure>

Чтобы определить, кто пригласил пользователя, бот создает ссылку по следующему шаблону: [https://wa.me/(ваш](https://wa.me/%28your) номер телефона, привязанный к боту)text=You%20were%20recommended%20by%20#{phone}%20😌Hello

<figure><img src="/files/4b1a9819f26e7dcf89c21a11f7b88bb370607eac" alt=""><figcaption><p>Рис. 2 Как вставить ссылку в блок сценария</p></figcaption></figure>

Давайте подробнее рассмотрим шаблон ссылки: [https://wa.me/(ваш](https://wa.me/%28your) номер телефона, привязанный к боту)?text=You%20were%20recommended%20by%20#{phone}%20😌Hello, где:

1. Замените скобки "(ваш номер телефона, привязанный к боту)" на соответствующий номер телефона;
2. \#{phone} автоматически заменяется на номер телефона пользователя, который запросил свою партнерскую ссылку.

Мы отправляем сгенерированную ссылку не как текст блока, а как вложение — кликабельную ссылку с уведомлением (см. рис. 2 и рис. 3):

* выберите вставку вложения
* &#x20;выберите тип — Link и вставьте его в поле 'Attachment URL':

<figure><img src="/files/9b1d92bebf60b5b40325758179a5d3053701f35e" alt="" width="323"><figcaption><p>Рис. 3. Attachment -> type ->link</p></figcaption></figure>

В этом случае ссылка визуально будет отображаться сокращенной:

![Рис. 4. Вид в WhatsApp](https://lh5.googleusercontent.com/vW_tS8GIDqDbN0PkdgQsa6xeeiBBfxuC4Qp8QuzXRz98yI4fphKEUIE22MiBcq4q_RvlQLlAEtlVzcL-hln5DbHaM-F1tuSBNp9y5zhvR5efRmjzDbcTlox5AUDvhnVorlBEdYsX)

Давайте протестируем работу ссылки с помощью функции **«Test Bot»** .

<figure><img src="/files/2746f366cc561e8f548a40f28a23b0a46bcab006" alt="" width="237"><figcaption><p>Рис. 5. Как протестировать бота</p></figcaption></figure>

Вот результат: ссылка перенаправляет пользователя в соответствующий чат мессенджера с вашим номером телефона:

<figure><img src="/files/b5752db091e13f3d77f9e735be2522cada8ce909" alt="" width="563"><figcaption><p>Тестирование работы ссылки</p></figcaption></figure>

Таким образом, вы успешно сгенерировали пригласительную ссылку, которую потенциальные пользователи могут использовать для доступа к чат-боту. Кроме того, при переходе по этой ссылке пользователь перенаправляется в окно чата с уже заполненным сообщением. (См. рис. 6)

![Рис. 6. Заполненное сообщение в WhatsApp](https://lh5.googleusercontent.com/60e0Pcv5362t53lD5Y0evDiAAmeyCoL-eSg_1wXPsgFiKw-Nn0Zmb3WUwBE16lCBr84e56RB863VJd8GFW4kqZAsXMRzEEIFum_ThIdbr58IqV9_JP-kp3IVnfNZoAsJ7d_n4OI4)

### Проверка пользователя&#x20;

**Использование функций и регулярных выражений в блоке**

Команда проверки и записи в базу данных будет работать только в том случае, если бот найдет в сообщении пользователя номер телефона. Поэтому необходимо разделить полученную фразу на части.

Для этого используется функция **splitter()** .

{% tabs %}
{% tab title="Функция Splitter()" %}
**splitter(str, s, n)** — разбивает строку на части. Функция возвращает массив элементов. <br>

Параметры:

<mark style="color:красный;">**!**</mark> <mark style="color:красный;">**str**</mark> <mark style="color:красный;"></mark><mark style="color:красный;">— исходная строка</mark>

<mark style="color:красный;">**!**</mark> <mark style="color:красный;">**s**</mark> <mark style="color:красный;"></mark><mark style="color:красный;">— разделитель строки</mark>

**n** — максимальное количество элементов
{% endtab %}

{% tab title="Пример" %}
Функция разбиения строки:

<figure><img src="/files/dbc29e2bbfeb2071133e00c05242b55826fffc5d" alt=""><figcaption><p>Рис. 8. Разбиение строки</p></figcaption></figure>
{% endtab %}
{% endtabs %}

Далее боту нужно проверить, действительно ли последовательность цифр в строке является номером телефона. Для этого мы используем следующие регулярные выражения:

* Общий номер телефона: `^(\+)?((\d{2,3}) ?\d|\d)(([ -]?\d)|( ?(\d{2,3}) ?)){5,12}\d$`
* <mark style="color:красный;">**Поменять русский номер!**</mark> Только российский номер телефона: `^((\+7|7|8)+([0-9]){10})$`

<figure><img src="/files/5e5bc9533c370d491519e73b34a980b1a0782c18" alt="" width="500"><figcaption><p>Рис. 9. Регулярное выражение для номера телефона</p></figcaption></figure>

{% hint style="info" %}
Для получения информации о работе с регулярными выражениями см. статью «Регулярные выражения». <mark style="color:красный;">**ссылка**</mark>
{% endhint %}

После того как бот проверит, что последовательность цифр действительно является номером телефона, сохраните его из сообщения как переменную (например, #{reff}).

**Проверка номера телефона пользователя как реферала в базе данных**

Теперь необходимо проверить, является ли номер телефона пользователя, перешедшего по ссылке, уже рефералом (ранее приглашенным кем-то и записанным в нашу базу данных). Для этого создайте в сценарии блок с функцией поиска по столбцу.

Используйте функцию поиска по столбцу, нажав **«API Request»** в блоке, где нужно задать следующие значения параметров:

<figure><img src="/files/e7ab22b0b0009cb69973d6ceca26ab28e0629c1d" alt="" width="337"><figcaption><p>Рис. 9</p></figcaption></figure>

<mark style="color:красный;">**!**</mark>**&#x20;URL функции**: <https://store.salebot.pro/function/findcell> <mark style="color:красный;">**ссылка**</mark>

<mark style="color:красный;">**!**</mark>**&#x20;JSON** **параметры запроса:**&#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" }**

Параметры ответа:

"status": "1" — значение найдено

"status": "0" — значение не найдено

"data" — найденное значение

"cell\_number" — найденное расположение ячейки

{% tabs %}
{% tab title="Поиск по столбцу и вывод текста из всей строки" %}
Параметр return нужно установить в 0.\
\&#xNAN;**{ "id": "your\_table\_id", "find": "text\_to\_search", "col": 2, "return": 0 }**\
Ответ: {"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"}}\
Разбор ответа:&#x20;

data — ответ

data|0 — Ячейка 1

data|1 — Ячейка 2

data|2 — Ячейка 3

data|3 — Ячейка 4

cell\_number|row — строка&#x20;

cell\_number|col — столбец&#x20;
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Чтобы узнать больше о доступных функциях для работы с таблицами, см. статью «Google Sheets». <mark style="color:красный;">**ссылка**</mark>
{% endhint %}

### Блок уведомления

Чтобы уведомить пользователя, который поделился реферальной ссылкой, о том, что новый клиент успешно перешел по ней, мы создадим отдельный блок. Для отправки уведомления о создании нового реферала используйте следующие параметры запроса (тип: **POST - JSON**):

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

Запросы выполняются с использованием **POST** метода по адресу URL: **`https://chatter.salebot.pro/api/{api_key}/{action}`** Где:

* **`api_key`** — это ключ доступа API вашего проекта, который можно получить в настройках проекта (см. рис. 11).

<figure><img src="/files/adb8296e20004aaa7d54d7d85d8205b435490d8b" alt="" width="563"><figcaption><p>Рис. 11.</p></figcaption></figure>

Вы можете получить ключ доступа с помощью переменной **#{api\_key}**, которая хранит текущий сгенерированный токен доступа. **Не забудьте сгенерировать токен перед его использованием.**

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

<figure><img src="/files/f05ba782ffec4cf4f0b8834d470abe4567a179c5" alt="" width="563"><figcaption><p>Рис. 12. Уведомление в Whatsapp</p></figcaption></figure>

{% hint style="info" %}
ППодробнее о функциях API-запросов можно узнать здесь. <mark style="color:красный;">**ссылка**</mark>
{% endhint %}

### Добавление приглашенного и приглашающего пользователей в базу данных

Для этого мы будем использовать построчную запись в конкретные столбцы, которая выполняется с помощью **mapping** .

{% hint style="danger" %}
Таблица должна иметь заполненную шапку (хотя бы одна ячейка в первой строке).
{% endhint %}

<mark style="color:красный;">**!**</mark>**&#x20;URL функции** <https://store.salebot.pro/function/gsheets> <mark style="color:красный;">**ссылка**</mark>

<mark style="color:красный;">**!**</mark>**&#x20;JSON** **параметры запроса:**&#x20;

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

Если вы хотите записывать строки не на первый лист, добавьте параметр **list\_name** в запрос:

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

Параметры:

* **id** — идентификатор таблицы\*
* **a, b, c, d** — названия столбцов
* **list\_name** — имя вашего листа (например, "Sheet2")

\*Обязательно замените на фактический ID вашей таблицы.

> Пример ответа:  **{"number\_row":8}**

Если запрос выполнится успешно, в ответе будет указан номер строки, который вы можете сохранить и использовать для дальнейших операций.

### Просмотр списка рефералов

Давайте добавим в бота дополнительную команду, позволяющую пользователям просматривать список своих рефералов.

Чтобы найти все указанные значения в столбце, используйте функцию **findcell** с параметром **"find\_all"**. Это позволит найти все вхождения **"find\_all"** значения в указанном **столбце** "col" и вернуть список уникальных значений из **"return"** столбца в виде строки.

<mark style="color:красный;">**!**</mark>**&#x20;URL функции:**  <https://store.salebot.pro/function/findcell> <mark style="color:красный;">**ссылка**</mark>

<mark style="color:красный;">**!**</mark>**&#x20;Параметры JSON-запроса:**&#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/c6605b25f2aa1fb1bcaee27e1db7c8aae20b8d6d" alt="" width="449"><figcaption></figcaption></figure>

В сохраненных значениях укажите:

list → Список

quantity → Количество

Для пользователя отображайте сообщение:
*"Вы пригласили #{spisok}, всего ваших рефералов: #{quantity}"*

В других мессенджерах реализовать такую реферальную систему еще проще, потому что данные приглашающего передаются как скрытый параметр при переходе по ссылке, поэтому новому пользователю не нужно отправлять сообщение вроде *«Меня пригласил этот номер.»*


---

# 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/doc/ru/kak-sdelat.../referalnaya-programma.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.