> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/en/app/referral-system.md). # Referral system ### 1. What it is and why you need it The referral system lets your bot track who referred whom, and automatically reward users who bring in new participants. {% hint style="info" %} You can connect graspil's referral system even if you already have your own referral system implemented {% endhint %} **What you can do with it:** * **Track sources** — see which links or tags new users are coming from. * **Keep records of referrers and referrals** — know who invited whom. * **Award rewards** — automatically, when a referral performs the required action (payment, registration, or any other event in your bot). * **Pay out rewards** — manually, via webhook, or automatically on a schedule. * **View statistics** — funnel, top referrers, accrual trends, and use referral data in the report builder > **Referrer** — the one who invites (earns).\ > **Referral** — the one who was invited. *** ### 2. Operating modes: Observe and Manage When setting up the referral system, you need to choose one of two modes. #### Observe You simply track which tags (codes) arrive in the `?start=` parameter of your links. The system records the clicks and links them to users, but it doesn't generate or manage the codes itself — your bot handles that on its own. **When to choose this:** if you already have your own logic for issuing referral links and just want analytics and click tracking without changing your infrastructure. > **Important:** for accruals to work, the system needs to know who the code belongs to (i.e. the referrer's `referrer_id`). In "Manage" mode, this happens automatically. In "Observe" mode — only if you pass the referrer's Telegram ID directly (the "Parameter = Telegram ID" option) or link the code's owner via the API (`set-code-owner`). #### Manage The platform takes over generating unique referral codes and links for each user. You can configure reward rules, see referrer balances, and process payouts — all through the interface or the API. **When to choose this:** if you're building a referral program from scratch or want to hand off code and payout management to the platform. Manage mode unlocks the full feature set: accrual rules, balances, payouts. *** ### 3. Link parameter and user\_id transfer mode #### Parameter name In the settings, you specify which link parameter carries the referral code. By default this is `ref`, so the link looks like this: {% code overflow="wrap" %} ``` https://t.me/your_bot?start=ref- ``` {% endcode %} The parameter name can be changed to any Latin word (letters and digits only). It's important that it matches what your bot passes. {% hint style="info" %} If you have [simplified UTM tag processing mode](/en/app/start-utm/configuring-start.md#uproshennyi-rezhim) enabled, everything after `start=...` will be used as the referrer code. To avoid this, disable simplified tag processing mode and use parameters instead. {% endhint %} #### "Parameter = Referrer's Telegram ID" mode By default, an opaque code is passed in the link, and the system figures out on its own who it belongs to. But there's an alternative mode: your bot puts the referrer's **direct Telegram ID** (a numeric value) into the `?start=` parameter. Enable the **"Parameter = Referrer's Telegram ID"** option if: * Your bot generates links of the form `?start=` itself. * You want to avoid a separate "code → user" mapping layer. With this mode enabled, if a number arrives in the parameter, the system immediately records the referrer with the known Telegram ID — no intermediate steps needed. > Non-numeric values are still processed as regular observed codes in this mode. #### Linking a code's owner via the API Use the `POST v1/referral/set-code-owners` method to tell the system who owns one or more codes. The method accepts an array of objects `[{code, user_id}, ...]` and works in two scenarios: * **In advance (pre-assign):** the code hasn't been used by anyone yet, and you register it with an already-known owner. All future clicks on the code will be linked to the referrer immediately — no extra steps needed. * **After the fact (backfill):** someone has already clicked the code, but the owner wasn't known. The system retroactively assigns the referrer for all past clicks. Codes can be submitted in bulk in a single request, which is convenient when initializing a referral program. *(See the API section for documentation on the methods.)*
*** ### 4. Activation and creating referral codes #### Activation The referral system is disabled by default. To enable it: 1. Go to the **Referral System → Settings → General** section. 2. Choose a mode (Observe or Manage). 3. Specify the parameter name (or leave it as `ref`). 4. Click **Activate**. After activation, the section opens up fully. #### Creating referral codes (in "Manage" mode) In "Manage" mode, each referrer gets a unique link. There are several ways to obtain it: 1. **Through the interface.** Open the referrer's card (the "Referrers" section → the user you need). Their personal referral link and a "Copy" button are displayed there. 2. **Through the API.** The `GET referral/default/referrer-code?key=&user_id=` method returns the link for a specific user. If a code doesn't exist yet, it's created automatically. This is handy to call directly from your bot, to give the user their link in response to a "My referral link" command. 3. Through automation. You can create an automation that sends the referrer's code directly via the Telegram bot. *** ### 5. System sections After activation, a "Referral System" section appears in the menu with subsections:
SectionWhat's here
OverviewA summary dashboard: key figures, funnel, top referrers, mini-charts
SettingsMode, link parameter, accrual rules, payout settings
ReferrersA list of everyone bringing in users, with balances and stats
ReferralsA list of referred users with their referrer indicated
AccrualsThe full accrual history (ledger) with statuses
PayoutsPayout history, manual operations, statuses
StatisticsCharts and tables: trends, funnel, top performers
*** ### 6. Accrual rules Rules are the heart of the referral program. Each rule describes: **what event** triggers it, **how much** to credit the referrer, and **what else to do** (optionally). #### How to create a rule Go to **Settings → Reward Rules** and click "Add rule". #### What you can configure in a rule **Name** — arbitrary, for your own convenience. **Status** — a rule can be enabled or disabled without deleting it. **Trigger event** — which referral event triggers the accrual. This is any event from your bot: a payment, a subscription, completing a step in the bot, etc. Selected from the list of event types the platform already knows about for your bot. {% hint style="info" %} You can create/trigger an event in any way that's convenient — via the API or the bot's message processing rules {% endhint %} **Conditions on the event value** — an additional filter: for example, "a payment event, but only if the amount is ≥ 1000". Fields: minimum value, maximum value, exact value. All optional. **Reward type:** * **Fixed** — the referrer receives a specific amount in the currency you choose (for example, 100 coins for each referral payment). * **Percentage** — the referrer receives a percentage of the event's amount (for example, 10% of the referral's payment). The currency comes from the event itself. * **External** — the platform doesn't calculate the amount itself; it simply notifies your server via a webhook. Useful if the accrual logic (e.g. extending access) is implemented on your side. **Hold period (hold\_days)** — how many days the accrual stays in "on hold" status before becoming available for payout. Useful if you have refunds: the accrual won't go to payout before the refund period has expired. {% hint style="info" %} Set **hold\_days = 0 if no hold period is needed** {% endhint %} **Side effects** — additional actions to perform on each accrual: * **Webhook** — the platform sends a POST request to the specified URL with the accrual data. You set up a request body template with variable substitution (`{{referrer_id}}`, `{{amount}}`, `{{event_value}}`, etc.). * **Custom field** — increment (`inc`) or set (`set`) the value of a [custom field](/en/app/custom-fields.md) on the referrer's user profile in your bot. For example, you can store the accumulated balance directly in the user's profile. #### Rule priority If multiple rules could trigger for the same event, the order they're applied in is determined by priority. Rules with a lower number are checked first. *** ### 7. Payouts Once a referrer has accumulated an approved balance, it can be paid out. #### Payout methods Configured in **Settings → Payouts**. **Manual** — you transfer the money to the user yourself by any convenient method, then mark the payout in the system as "Paid" or "Failed" (with a comment). The platform simply keeps the records. **Webhook** — when a payout is initiated, the platform automatically sends a POST request to your URL with the data "credit X in currency Y to user Z". Your server credits the funds and returns a response; the platform marks the payout as successful or failed. This method is suitable if you have an internal wallet or payment system. **Cryptocurrency and other methods** — in development, coming soon. {% hint style="info" %} Let us know which platform you need an integration for, and we'll add it promptly :) {% endhint %} #### How to initiate a payout * **From the referrer's card** — choose the currency and method, click "Pay out". The platform will take the entire available balance for the selected currency. * **From the "Payouts" section** — the "Create payout" button, choose the referrer, currency, and method. * **Via the public API** (`POST v1/referral/payout`) — your bot can give the user a "Withdraw" button, and clicking it initiates the payout itself. #### Automatic payouts Enable in **Settings → Payouts → Auto-payouts**: * **Schedule** — monthly or every N days. * **Method** — manual or webhook (applies to all auto-payouts). * **Minimum threshold per currency** — a payout is only created if the available balance in that currency has reached the required amount. Configured separately for each currency. Auto-payouts work independently of manual ones: manual and API-based payouts are always available, even without a schedule enabled. #### Payout lifecycle {% code overflow="wrap" %} ``` Requested → Processing → Completed ↘ Failed (returned to balance) ``` {% endcode %} *** ### 8. Balance and accrual statuses A referrer's balance is tracked separately for each currency (without automatic conversion). #### Accrual statuses
StatusWhat it means
On holdAccrued, but the hold period (hold_days) hasn't passed yet. Can't be paid out yet
ConfirmedReady for payout (available balance)
In payoutReserved for the current payout
PaidSent in a payout
RefundedA compensating accrual (refund)
CancelledVoided
#### What makes up a referrer's balance * **Available** — the sum of confirmed accruals not tied to a payout. This is what can be paid out right now. * **Reserved** — confirmed accruals already included in the current payout (in progress). * **On hold** — the hold period hasn't passed yet. * **Paid** — the total amount of all successful payouts. *** ### Frequently asked questions **Can I work in "Observe" mode and then switch to "Manage"?**\ Yes, the mode can be changed at any time in the settings. The accumulated click history is preserved. **Can I pay out in multiple currencies?**\ Yes. Each rule has its own currency. The referrer's balance is tracked per currency, without conversion. **One rule or several for the same event?**\ You can create several rules for one event type — for example, different rates depending on the amount (use the `value_min`/`value_max` conditions). Priority determines the order they're checked in.