Referrals
The referral system lets players earn currency rewards by inviting new members to the Discord server. Each player can generate a unique permanent Discord invite link; when someone joins via that link and later claims a dzbot account, the referrer is automatically credited.
How it works
- A player with the
profile.generate_referralaccess right generates their personal referral link on the Profile page. - dzbot creates a permanent Discord invite for the first available text channel in the guild and stores it.
- When a new user joins the Discord server using that invite, dzbot records the join against the referral.
- When the new user later claims their in-game account through the bot, dzbot credits the referrer's balance with the configured reward amount.
Each join is credited at most once, per member and per referral. If the new user's account was already claimed before they joined, or if there is no unclaimed join for them at claim time, no reward is issued.
How dzbot identifies the invite
Discord never reports which invite a joining member used. The only available signal is that an invite's use-count changed, so dzbot keeps a record of the use-count of every invite on the guild — including invites members created themselves — and compares it against the live list each time somebody joins.
A referral is credited only when exactly one use accrued across the whole guild, on an invite that was already being tracked. That is the only situation in which the joining member can be tied to a specific invite with certainty.
Everything else is recorded as an unattributed join rather than credited to a best guess:
| Situation | What happens |
|---|---|
| A member's own invite or the vanity URL was used | Resolved to that invite; no referral involved, nothing recorded |
| dzbot added the member itself when they linked their account | No invite was used, so there is no referrer; nothing recorded |
| Several invites were used at the same moment | Recorded, listing the invites that moved |
| The invite was created after the last observation | Recorded |
| The bot had just restarted and had no baseline yet | Recorded |
| The guild invite list could not be read (missing Manage Server permission) | Recorded |
Admins see these under Admin → Referrals → Unattributed joins and can assign one to the correct referrer, which creates the join and pays the reward. Rows that genuinely have no referrer — the invite had already expired, or the bot could not read the list — can be dismissed instead. An unattributed join is deleted 30 days after the member joined, so assign it within that time.
Joins that happened while the bot was offline are a separate case: Discord does not deliver those events afterwards, so the member is never seen at all and cannot appear in this list. They surface as an issue on the affected referral instead, showing how many uses went uncredited. Because the member is unknown, those cannot be assigned retroactively.
The bot needs the Manage Server permission on the guild to read the invite list. Without it no referral can ever be attributed, and every join lands in the unattributed list.
Configuration
The reward amount is controlled by a single server setting:
| Setting | Location | Default |
|---|---|---|
| Referral reward amount | Admin → Economy settings | 0 (disabled) |
Setting the reward amount to 0 disables the referral feature entirely. Players will not see the referral card on their profile when the reward is zero.
Player experience
Players visit Profile and, if the feature is enabled and they have the required access right, a Referral Link card is shown. The card displays:
- The configured reward per referral.
- A Generate referral link button (shown before a link exists).
- The generated invite URL with a copy button (shown once generated).
- Statistics: total Discord joins via the link and how many resulted in a paid reward.
Access rights
| Access right | Who needs it |
|---|---|
profile.access | View the profile page |
profile.generate_referral | Generate and view a referral link |
Admins grant these rights through the access control system. See Access control.