Telegram Operations
Learn how to launch your bot, activate plans, and execute commands using deep links.
Your Subscriby bot supports powerful deep linking capabilities. You can create special links to:
- Launch the bot.
- Automatically open a specific subscription plan.
- Execute commands (including custom ones).
- Activate access codes.
Bot Links
There are two primary ways to share your bot:
Short Link (Telegram Only)
Inside Telegram (channels, groups, and chats), you can simply mention your bot by its username.
@YourBotNameFull Link
A universal link that works anywhere (websites, emails, social media) starts with t.me.
https://t.me/YourBotNameDeep Linking
You can pass parameters to your bot using the ?start query parameter. This allows for powerful automation and seamless user onboarding.
What the bot accepts
A start payload is read in one of three ways, in this order:
| Payload shape | Handled as |
|---|---|
auth_<token> | Portal sign-in handoff (internal) |
-<command> | An admin command — see below |
| A bare UUID | A plan id, or an access code |
| Anything else | Ignored; the bot opens its home |
Subscriber payloads must be a bare UUID
There is no key=value syntax. The bot checks the payload with
Str::isUuid() and, if it matches, looks for a plan with that id in the
project; failing that it tries the value as an access code. A payload of any
other shape — a plain word, a campaign tag, a code=ABC123 pair — is silently
ignored and the subscriber simply lands on the project home screen.
Subscription Plan Links
Link straight to one plan and skip the selection menu. Ideal for "Buy Now" buttons on your site and pricing tables.
https://t.me/YourBotName?start=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6dThe payload is the plan's own UUID. You do not have to assemble it by hand.
Open the project's Subscription Plans
Pick the project in the top-left project picker, then choose Subscription Plans in the sidebar.
Open the row menu for the plan you want to link
Click the ⋯ button at the right-hand end of that plan's row.
Choose "Copy Plan Bot Deeplink"
The full link is copied to your clipboard and the item briefly reads Copied!. Paste it into a button, a post, an email — anywhere a link goes.
The item only appears once the project has a Telegram bot connected. Without a bot there is no link to build — connect one from Bot setup first.
Getting the link programmatically
For automation, ask the API instead — it returns the assembled link so you never have to concatenate the bot URL and the plan id yourself:
curl "https://api.subscriby.net/v1/projects/$PROJECT_ID/distribution/deep-link?plan_id=$PLAN_ID" \
-H "Authorization: Bearer $SUBSCRIBY_TOKEN"See Distribution API, or the
get_deep_link MCP tool for the same thing from an
AI agent.
Access Code Links
The same slot redeems an access code — codes are UUIDs, so the link looks identical. The bot tries the payload as a plan first and falls back to a code.
https://t.me/YourBotName?start=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6dYou rarely need to build these by hand: the access-code CSV export has a Join Link column, and the bot's own "share" messages already contain the link. See Access codes.
Admin Command Links
Two admin commands can be driven from a link, for use in your own dashboards or integrations. Both act on the operator who taps the link, so they only do anything for a project admin.
Format. Drop the leading /, prefix the command with -, and join each
argument with _-.
Only `check` and `ban` are reachable
The payload is split on _, so a command whose own name contains an
underscore cannot be addressed — -cancel_subscription resolves to the
command cancel, which does not exist, and the link falls through to the home
screen. There is no escape sequence that works, and there is no mechanism for
user-defined custom commands.
Example: Check User Status Shows detailed information about a user (Subscription, Plans, Resources, Payments).
Original Command: /check 12345
Deep Link:
https://t.me/YourBotName?start=-check_-12345Example: Ban User Bans a user, revokes their invite links, and removes them from all resources.
Original Command: /ban 12345
Option 1: Interactive (Recommended)
https://t.me/YourBotName?start=-ban_-12345This link opens a safety menu with a confirmation button to prevent accidental bans.
Option 2: Immediate (Automated)
https://t.me/YourBotName?start=-ban_-12345_-confirmThis link bans the user immediately without confirmation. Use this only for automated systems where you are sure about the action.
How is this guide?