Bot type
A loyalty card that cannot be left at home
A Telegram loyalty bot tracks stamps or points against a customer's chat, issues referral codes that attribute correctly, and redeems rewards at the counter with a code your staff verify. It removes the physical card. It will not make an unremarkable product worth returning to.
Loyalty and referral bots: price, timeline and limits
- Fixed price
- $3,800 USD
- Delivery
- 18 calendar days from kickoff
- Deep-link payload
- 64 characters from a restricted alphabet
- Purchase verification
- Not possible from Telegram alone — requires a till or POS feed
- Device identity
- Telegram gives a bot no persistent device identifier
- Broadcast ceiling
- ~30 messages/second bot-wide
As of 2025-10-01, Telegram Bot API 13.4
The problem this solves
Paper stamp cards have a known and unflattering economics. A large share are lost before completion, the ones that are completed carry no information about who completed them, and the whole scheme is invisible to you until someone presents a full card. You are paying for a discount and buying no data at all.
App-based loyalty solves the data problem and creates a worse one: nobody installs an app for a coffee shop. Install rates for single-merchant loyalty apps are low enough that the scheme reaches only the customers who were already the most loyal — precisely the ones who needed no incentive.
A chat-based scheme sits between the two. There is nothing to install, the balance is a message away, and every accrual is attached to an identity you can talk to later. The referral half matters more than the loyalty half for most operators: a referral code that reliably attributes the new customer to the person who introduced them turns a vague word-of-mouth effect into something you can price and reward.
The part most schemes get wrong is fraud. Any accrual mechanism that a customer can trigger themselves will be triggered by staff for friends, by customers for each other, and by whoever works out that the QR code on the counter can be photographed. Fraud controls are not an add-on here; they decide whether the scheme costs what you modelled.
How the build runs
The customer joins from a code at the point of sale
A QR code on the counter or the receipt opens the bot and creates their account in one tap. No form, no email, no password — the friction at this step determines the whole scheme's reach.
deep-linkAccrual is triggered by staff, not by the customer
The member shows a rotating code from their chat, staff enter it in the till-side bot, and the stamp is added. Customer-triggered accrual is the mechanism every fraudulent scheme is built on, so it is not offered.
inline-keyboardThe rotating code makes screenshots useless
The member's code changes on a short cycle and is single-use. A screenshot shared in a group chat is expired before it is useful, which closes the most common abuse without inconveniencing anyone honest.
commandsRewards unlock automatically and announce themselves
When the threshold is met the customer is told immediately, with the redemption code ready. The message arrives at the counter, while they are still there, which is when it converts.
broadcastReferral codes attribute at a qualifying event you define
Not at signup — at first purchase, or third visit, or whatever you actually want to pay for. Rewarding signups produces a scheme that pays for accounts rather than customers.
deep-linkVelocity limits catch the patterns fraud produces
Ten accruals from one staff member in five minutes, or a referral tree that branches unnaturally, raises a flag rather than paying out. The controls are visible to management, which is most of their deterrent value.
webhook
What Telegram will and will not let you do
A bot cannot verify a real-world purchase; it can only record what someone tells it.
Every accrual traces to a staff action, so the scheme's integrity rests on staff controls and audit rather than on cryptography. Any vendor claiming to prevent staff fraud technically is overselling.
A `start` deep-link payload is capped at 64 characters from a restricted alphabet.
Referral codes are short identifiers resolved server-side rather than encoded data. That also means a code can be revoked, which an encoded one cannot.
Telegram gives no persistent device identifier to a bot.
Device-level fraud detection is limited to behavioural signals. One person running several Telegram accounts is detectable by pattern, not by fingerprint, and the controls are designed accordingly.
A bot may send about 30 messages per second overall.
A campaign blast to twenty thousand members takes around eleven minutes to deliver. Fine for a promotion; not suitable for anything advertised as starting at a precise time.
Telegram will restrict a bot that users repeatedly report as spam.
Promotional volume has a real ceiling enforced by your members' patience. Frequency caps are built in rather than left to whoever is running the campaign that week.
When not to build this
- Your repeat rate is already high for reasons unrelated to price. You will be discounting purchases that were going to happen anyway, which is the classic loyalty scheme failure.
- You cannot control staff behaviour at the till. Every accrual runs through staff, so a scheme without staff accountability becomes a discount for their friends.
- Your margin cannot absorb the reward at the redemption rate a working scheme produces. Model it at eighty per cent redemption, not at the twenty per cent paper cards deliver through loss.
- You have one outlet and fewer than a hundred regulars. You already know them, and a scheme adds process without adding information.
What it runs on
| Component | Version | Why |
|---|---|---|
| grammY | 1.45 | Bot framework, with separate member and staff conversation trees. |
| Cloudflare Workers | current | Runtime, including rotating code generation and verification. |
| Cloudflare D1 | current | Balances, accrual ledger, referral graph and fraud signals. |
| Zod | 4.4 | Validation on every staff-side action, which is the sensitive surface. |
| TypeScript | 5.9 | Strict mode. A points ledger is money and is typed like it. |
Questions people ask before committing
How do you stop staff giving stamps to friends?
You cannot prevent it technically, and anyone claiming otherwise is selling something. What works is a per-staff accrual ledger, velocity limits, and a weekly report that makes an outlier obvious. Deterrence through visibility, not through cryptography.
Can customers check their balance without asking staff?
Yes, at any time, and it is one of the more valuable properties. Balance anxiety is the main reason paper card holders stop participating, because a card at home is a balance they cannot see.
When should a referral actually pay out?
At a qualifying event that costs the referred person something — a first purchase, usually. Paying on signup produces a scheme that generates accounts, and the accounts will be generated by exactly the people you least want to pay.
What redemption rate should we model?
High. Paper schemes see low redemption because cards get lost, and that loss is silently subsidising the discount. A chat-based balance does not get lost, so model at something close to full redemption or the economics will surprise you.
Can it run across multiple branches?
Yes, with accrual and redemption at any outlet and reporting per outlet. Cross-branch redemption is where accounting arguments start, so the reporting is built to settle them rather than to summarise.
Can we message members with promotions?
Yes, to members who joined the bot, subject to frequency caps that are deliberately conservative. Telegram restricts bots that users report as spam, so over-messaging risks the channel itself, not just engagement.