Why your Telegram referral bot is not counting referrals

First identify which event is missing

A user saying “my referral did not count” can describe three different failures. Attribution means the bot received and stored a sponsor from the start payload. Qualification means the invited user completed the required action. Credit means the ledger rewarded the sponsor exactly once. Looking only at the final balance hides where the chain broke.

Create an internal diagnostic record for each stage. Support should be able to answer whether a start payload arrived, which sponsor was recorded, which qualification is pending and whether a credit already exists. Do not repair the issue by adding balance until the unique source event is understood, or the same referral may later credit again.

Check the exact deep link

Telegram bot referral links use a start parameter. The payload must follow Telegram's supported format and reach the bot's first start update. Copying only the bot username, removing the query parameter, adding unescaped characters or routing through a service that drops the parameter turns a referral link into a normal bot link.

Open the exact link in a clean account and inspect the server update. Do not infer success from Telegram opening the chat. The bot must receive the payload. Keep campaign or sponsor codes short, opaque and free of secrets; resolve them to an internal sponsor on the server.

• The URL targets the correct bot username.
• The start parameter is present once and uses the expected prefix.
• No redirect or URL shortener removes the query string.
• The payload maps to an existing sponsor or campaign.
• The bot records the raw payload and normalized result for support.
• No API token, wallet key or personal information appears in the link.

Opening the bot is not the same as starting it

A person can open a Telegram bot profile or chat without sending the start command. Until Telegram delivers the bot update, the backend cannot reliably attribute the new relationship. The first screen and referral message should make the Start action obvious without claiming that a preview or click has already earned a reward.

Test on mobile and desktop because the presentation of the start button can differ. If the destination is a Mini App, preserve the referral through the supported start or startapp route and confirm that the Mini App's server-side initialization resolves the same campaign or sponsor.

Existing users need a deliberate policy

Many referral systems lock the sponsor on the first valid start. An account that already used the bot cannot be safely reassigned every time it opens a new link; allowing overwrites enables sponsor theft and referral trading. The correct result may therefore be “not a new referral,” not a tracking bug.

Publish whether returning users can join a new campaign, whether campaigns differ from permanent sponsor attribution and whether an existing unattributed account can be backfilled. Store sponsor and campaign as separate concepts when the product needs both. Never silently rewrite historical attribution after rewards exist.

A referral can be attributed but still pending

If the program rewards a qualified action, the referral count visible to the sponsor may intentionally exclude raw starts. The invited account may need to complete onboarding, join a required channel, make a first valid claim, remain active or satisfy a purchase rule. The interface should show invited, pending, qualified and rewarded separately instead of displaying one unexplained number.

For channel membership, the bot needs the appropriate access and must check the current member state through Telegram. For an in-product action, verification should be server-side and tied to a unique event. A browser-side Done button is not proof.

Prevent duplicate credit while allowing safe retry

Network retries, repeated callbacks and concurrent requests are normal. The credit operation should use a unique key such as program, invited account and qualification event. If the same event arrives again, the system returns the existing result rather than writing another reward.

A failed database or payout operation should remain retryable without losing the referral or paying twice. Keep attribution immutable, qualification explicit and credit idempotent. This separation lets support replay the missing stage rather than editing a total.

Run a five-account diagnostic matrix

Record the expected update, database state and user-facing message for every row. This becomes both the regression test and the support playbook. Run it after changing deep-link parsing, onboarding, task verification or reward rules.

1. Clean valid account

   Open the exact referral link, press Start and complete qualification. Expect one attribution and one credit.

2. Existing account

   Open a different sponsor link after prior use. Confirm the published no-reassignment policy.

3. Self-referral

   Use the sponsor's own account. Expect rejection with no pending reward.

4. Incomplete account

   Start through the link but stop before qualification. Expect attribution and a visible pending state.

5. Repeated event

   Replay the qualification or callback. Expect the existing credit, never a second ledger entry.

When to correct a missing referral manually

Manual correction is appropriate only when evidence proves the source event and the automated path failed. Create a compensating ledger entry linked to the incident, operator and evidence. Do not edit aggregate counters or historical balances in place. The correction must obey the same uniqueness rule as the automated credit.

If evidence is incomplete, explain the missing stage and improve instrumentation. Paying every disputed referral without proof trains abuse; rejecting every dispute without diagnostics destroys trust. A mature builder exposes enough state to make a consistent decision.