Campaign Kit docs
 v0.1.0
Get help
● Start · Telegram

Telegram bot
and your first campaign.

Each campaign uses its own Telegram bot. This page shows how to create it with @BotFather, what the admin configures automatically, and the one BotFather setting you must add by hand for tracked links and squad invites.

01Create the bot with @BotFather

  1. Open @BotFatherIn Telegram, open @BotFather and send /newbot.
  2. Name itChoose a display name, then a username that ends in bot, for example MyCampaignBot.
  3. Copy the tokenBotFather replies with a token like 123456789:AA…. Treat it like a password. Never commit it or paste it in a chat.
  4. Connect itAdmin → your campaign → Settings → Launch → Bot token → Validate & connect. Only an owner can do this.
One bot, one campaign

A bot already connected to another campaign is refused with bot_in_use_by_another_campaign. Create a new bot for every campaign or client.

02What the admin sets up automatically

  • Validates the token with Telegram and stores it encrypted (AES-256-GCM with ENCRYPTION_KEY). It is never shown again.
  • Webhook: registers <PUBLIC_API_URL>/api/bot/<slug>/webhook with a random secret, for message and pre_checkout_query updates. This only happens when PUBLIC_API_URL starts with https://. Otherwise the admin shows Webhook skipped — the API URL is not https: make the API https, set PUBLIC_API_URL, restart the API and save the token again.
  • Menu button: sets the bot's chat menu button to open the Mini App, labelled with the campaign name. This needs an https Mini App URL.
  • Changing the campaign's slug, name or Mini App URL registers the webhook and the menu button again.

What the bot then does: /start replies with your welcome message and an Open button. A referral start (/start ref_<telegramId>) passes the referral into the Mini App. It handles the Telegram Stars checkout and records each successful payment once (idempotent on Telegram's charge id).

03Mini App URL and welcome message

Launch checklist step 2: enter the https origin where you host apps/miniapp, for example https://play.example.com. The bot's /start button opens <Mini App URL>?c=<slug>, so one Mini App deployment serves every campaign of the installation.

The welcome message is plain text, up to 1000 characters, sent above the Open button.

04Main Mini App in BotFather (needed for startapp links)

Tracked links (https://t.me/<bot>?startapp=l_<code>) and squad invite links (https://t.me/<bot>?startapp=s_<code>) open the bot's Main Mini App. The admin cannot set it through the Bot API, so set it once per bot in BotFather:

  1. Open the bot settingsIn @BotFather: /mybots → your bot → Bot Settings → Configure Mini App, and enable it.
  2. Enter the URL with the campaign slughttps://play.example.com/?c=<slug>. The ?c= part tells the Mini App which campaign to load; a startapp link only carries the link or squad code.
Single-campaign installs

If you only ever run one campaign, you can instead build the Mini App with VITE_DEFAULT_CAMPAIGN=<slug>. It is used when the URL has no ?c=.

Not yet tested on a live bot

The link formats are covered by automated tests, but this BotFather path has not been verified end to end on a production bot for this release. Test one tracked link and one squad invite on your bot before you print or publish them.

05Channel quests: make the bot an admin

For "join channel" quests, add the campaign's bot as an administrator of the channel or group. Otherwise Telegram does not let the bot read membership and players see Can't verify right now (API error verification_unavailable, HTTP 502).

06Telegram Stars

Nothing to enable. Digital goods sold for Stars need no payment provider: the API creates invoices with currency XTR and an empty provider token. Stars arrive in your bot's Stars balance, which you manage in Telegram (withdrawal through Fragment is Telegram's process). Payments only reach the API once the webhook is registered on https. The bot has no /paysupport command yet; Telegram expects payment support from bots that sell for Stars, so add one before you go live.

07Optional BotFather polish

  • /setuserpic: bot profile picture in your campaign's brand.
  • /setdescription and /setabouttext: what people see before they press Start.
  • Keep the token private. If it leaks, use /revoke in BotFather, then paste the new token in the admin (owner only).