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

Один **реферальний програм** — це система, яка винагороджує клієнтів або партнерів компанії, пропонуючи заохочення чи бонуси за залучення нових учасників.

З технічної точки зору реферальна програма включає кілька ключових компонентів:

1. Посилання **для запрошення**— унікальний ідентифікатор, який дає змогу користувачам або клієнтам запрошувати інших взяти участь у програмі. Запрошувач може ділитися цим посиланням через різні канали (наприклад, у цій статті буде розглянуто створення посилань через бот WhatsApp, але посилання реферальної програми можна надсилати через будь-який месенджер, який ви надаєте перевагу).
2. Один **база даних учасників**, реалізована через інтеграцію функціоналу MaviBot і Google Sheets, де записується інформація як про запрошених, так і про тих, хто запросив.
3. Один **система відстеження рефералів** яка відстежує дії, пов’язані із залученням нових учасників через реферальні посилання. Система зберігає дані про всі реферали, даючи змогу перевірити, чи існує певний реферал у системі як раніше запрошений користувач.

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

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

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

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

### Створення реферального посилання

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

1. Двічі клацніть у порожній області на полотні конструктора:

<figure><img src="/files/1f7ef3e0fb53ea3485c1c7c346934bf6266c15cc" alt="" width="563"><figcaption><p>Як створити блок натисканням миші</p></figcaption></figure>

2. Використовуючи **кнопку «Save»** внизу екрана та вибравши тип блоку:

<figure><img src="/files/acb3fbf7e797d196e5e73fdf9d643d26d8e89fd1" alt="" width="563"><figcaption><p>Як створити блок із вибраним типом</p></figcaption></figure>

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

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

Щоб визначити, хто запросив користувача, бот створює посилання за таким шаблоном: [https://wa.me/(ваш](https://wa.me/%28your) номер телефону, прив’язаний до бота)text=Вас%20рекомендував%20#{phone}%20😌Hello

<figure><img src="/files/a566cc4a78dab5c32bb552566c8e9e269da7861a" alt=""><figcaption><p>Рис. 2 Як вставити посилання в блок потоку</p></figcaption></figure>

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

1. Замініть дужки «(ваш номер телефону, прив’язаний до бота)» на відповідний номер телефону;
2. \#{phone} автоматично замінюється на номер телефону користувача, який запросив своє партнерське посилання.

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

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

<figure><img src="/files/f6c28f7c260559563193bd999dac97d82538e5eb" 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/1d628871c438e4884502f7f9e10df2fbecfc2dc2" alt="" width="237"><figcaption><p>Рис. 5. Як протестувати бота</p></figcaption></figure>

Ось результат: посилання спрямовує користувача до відповідного чату месенджера з вашим номером телефону:

<figure><img src="/files/13bb85b8cc66c6e05f8b3ecc15b0cde19e08f88e" 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:red;">**!**</mark> <mark style="color:red;">**str**</mark> <mark style="color:red;"></mark><mark style="color:red;">— початковий рядок</mark>

<mark style="color:red;">**!**</mark> <mark style="color:red;">**s**</mark> <mark style="color:red;"></mark><mark style="color:red;">— роздільник рядка</mark>

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

{% tab title="Приклад" %}
Функція розбиття рядка:

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

Далі боту потрібно перевірити, чи є послідовність цифр у рядку справді номером телефону. Для цього ми використовуємо такі регулярні вирази:

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

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

{% hint style="info" %}
Щоб дізнатися більше про роботу з регулярними виразами, будь ласка, зверніться до статті під назвою «Регулярні вирази». <mark style="color:red;">**посилання**</mark>
{% endhint %}

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

**Перевірка номера телефону користувача як реферала в базі даних**

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

Використайте функцію пошуку в колонці, натиснувши **«API Request»** у блоці, де потрібно встановити такі значення параметрів:

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

<mark style="color:red;">**!**</mark>**&#x20;URL функції**: <https://store.salebot.pro/function/findcell> <mark style="color:red;">**посилання**</mark>

<mark style="color:red;">**!**</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:red;">**посилання**</mark>
{% endhint %}

### Блок сповіщення

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

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

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

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

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

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

<mark style="color:red;">**!**</mark>**&#x20;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/4796999a8fe1ca82453a1f96af06ebd25a1bc893" alt="" width="563"><figcaption><p>Рис. 12. Сповіщення у Whatsapp</p></figcaption></figure>

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

### Додавання запрошених і тих, хто запросив, у базу даних

Для цього ми використаємо пострічкове внесення в певні колонки, яке виконується за допомогою **mapping** функцію.

{% hint style="danger" %}
Таблиця має містити заповнений заголовок (принаймні одну комірку в першому рядку).
{% endhint %}

<mark style="color:red;">**!**</mark>**&#x20;URL функції** <https://store.salebot.pro/function/gsheets> <mark style="color:red;">**посилання**</mark>

<mark style="color:red;">**!**</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:red;">**!**</mark>**&#x20;URL функції:**  <https://store.salebot.pro/function/findcell> <mark style="color:red;">**посилання**</mark>

<mark style="color:red;">**!**</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/7e8c3030c4ede31bc200e26111706c24a4382942" alt="" width="449"><figcaption></figcaption></figure>

У збережених значеннях вкажіть:

list → List

quantity → Quantity

Для користувача відобразіть повідомлення:
*"Ви запросили #{spisok}, усього ваших рефералів: #{quantity}"*

В інших месенджерах реалізувати таку реферальну систему ще простіше, оскільки дані запрошувача передаються як прихований параметр під час переходу за посиланням, тож новому користувачу не потрібно надсилати повідомлення на кшталт *«Мене запросив цей номер».*&#x20;


---

# 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/uk/yak-zrobiti.../referalna-programa.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.