telegram-bot-essentials/affiliates

Referral tracking and wallet commission payouts for telegram-bot-essentials/essence

v0.0.16 2026-09-01 12:27 UTC

Requires

• php: ^8.3
• laravel/framework: ^12 || ^13
• telegram-bot-essentials/billing: ~0.0.32
• telegram-bot-essentials/essence: ^0.12
• telegram-bot-essentials/settings: ~0.0.17
• telegram-bot-essentials/user-wallet: ~0.0.22

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.7 || ^4.0
• pestphp/pest-plugin-laravel: ^3.1 || ^4.0

MIT

• Elyar

Published on Packagist.org on 2026-09-02 09:05 UTC

README

A referral program for the telegram-bot-essentials/essence ecosystem. Every user gets a shareable deep link; signups through it are tracked; both the referrer and (optionally) the new user can be paid a signup bonus; and referrers earn an ongoing commission on their referred users' purchases. Bonuses and commissions are paid straight into user-wallet.

Depends on essence's deep-link handling, settings, billing events, and user-wallet.

Installation

composer require telegram-bot-essentials/affiliates
php artisan migrate

Everything is configured per-bot through Settings:

Setting	Type	Default
affiliates.affiliates_status	CHECKBOX	false
affiliates.allow_existing_users	CHECKBOX	false
affiliates.share_percentage	NUMBER	10
affiliates.referrer_signup_bonus	NUMBER	0
affiliates.referred_signup_bonus	NUMBER	0
affiliates.share_tagline	TEXT	—

How it works

• Each user's affiliate menu builds https://t.me/{bot}?start={referral_code}.
• A new user opening that link fires essence's BotDeepLinkReceived; the package creates a Referral and pays the signup bonuses.
• Attribution is first-touch-wins (a unique(bot_id, bot_user_id) constraint) and, by default, new users only. Self-referral is rejected.
• Every paid Billing invoice from a referred user credits the referrer a percentage (rounded down, wallet top-ups excluded). A later invoice revocation claws it back.

Commission listeners are queued (queue: billing) and restore the webhook context first, since invoice events can fire from a gateway callback with no "current user".

Documentation

Full documentation — the attribution rules, commission math, data model, and member UI — lives on the Telegram Bot Essentials documentation site under Modules → Affiliates.

License

MIT.