Telegram Deep Linking

TL;DR:

• Deep links let you open a bot with a /start parameter, for example https://t.me/your_bot?start=promo.
• In TeleGo, deep-link entry is designed around the /start command.
• Captured parameters can be used for routing, personalization, attribution, and CRM tracking.

Who this is for

• Bot builders who want to launch a scenario from an ad, website button, QR code, or referral link.
• Owners who want to know which post, ad, or partner brought each client.
• Operators who need to pass a lightweight identifier into the first step of a bot flow.

What you will learn

• How Telegram deep links work in TeleGo.
• How to build a valid /start link with parameters.
• Which values are saved automatically and how to use them in your scenarios.

Overview

A Telegram bot deep link is a regular t.me link with a start parameter:

https://t.me/<bot_username>?start=<parameter>

When the user opens that link, Telegram opens the chat with your bot and passes the value to the bot as:

/start <parameter>

In TeleGo, this means:

1. The Start node with command start becomes the entry point.
2. The parameter is parsed when the scenario session is created.
3. Tracking values are written into the session context before the rest of the flow runs.

WARNING

For TeleGo scenario entry, deep linking is intended for the /start command. If you need multiple entry variations, keep /start as the public entry and branch inside the flow using the parsed parameter.

Key concepts

• Bot username - your Telegram bot username without @ in the URL path.
• Start parameter - the payload passed after ?start=.
• Entry scenario - the scenario connected to the start command in the Start node.
• Tracking context - values like utm_source and traffic_source that TeleGo stores automatically.

Flow example

Supported parameter patterns

TeleGo currently recognizes these deep-link payload shapes:

Link payload	Example link	What TeleGo extracts
Plain source token	https://t.me/your_bot?start=promo	traffic_source = promo
ref_ source	https://t.me/your_bot?start=ref_instagram	traffic_source = instagram
referral_ id	https://t.me/your_bot?start=referral_12345	traffic_source = referral, referrer_id = 12345
UTM payload	https://t.me/your_bot?start=utm_source-google_medium-cpc_campaign-spring	utm_source = google, utm_medium = cpc, utm_campaign = spring, plus matching traffic_* values

What gets saved automatically

When a deep link is received, TeleGo can store these values in the session context:

Key	Meaning
utm_source	Marketing source
utm_medium	Marketing medium
utm_campaign	Campaign name
utm_term	Term / keyword
utm_content	Content / creative
traffic_source	Normalized top-level source
traffic_medium	Normalized top-level medium
traffic_campaign	Normalized top-level campaign
referrer_id	Numeric referral user id from referral_<id>

TIP

If you want values that appear directly in variable pickers, Conditions, and Formula examples, use the utm_* format. TeleGo also stores traffic_* meta for internal tracking and integrations.

How to use it

1. Keep your entry command as /start

Open the Start node for the scenario you want to launch from a link and set:

• Scenario Command → start
• Command Description → any label you want users to see in the menu

If your scenario uses another command such as /help, it can still work as a normal command flow, but your public deep links should still point to /start.

2. Publish the scenario

After saving the Start node, click Publish so the live bot uses the current version.

3. Build the link

Use your bot username without @:

https://t.me/your_bot?start=promo
https://t.me/your_bot?start=ref_instagram
https://t.me/your_bot?start=utm_source-google_medium-cpc_campaign-spring

4. Use the captured values in the flow

Typical ways to use deep-link data:

• Condition Node - branch users based on utm_source, utm_campaign, or another entry value.
• Actions Node - copy UTM values into CRM fields or send them to an integration.
• Formula Node - derive custom flags or campaign labels from incoming tracking data.
• Message Node - personalize the opening text based on the captured entry context.

Parameter formatting rules

Telegram deep-link parameters are limited and should stay compact.

• Allowed characters in Telegram deep links are A-Z, a-z, 0-9, _, and -.
• Telegram's start parameter can be up to 64 characters long.
• If you need spaces, encode them, for example google%20ads.
• For TeleGo's UTM parser, underscores are used as separators between parts like source-google_medium-cpc.

TIP

Recommended format for UTM-style payloads: use _ only to separate parameter segments, and use hyphens or URL encoding inside values.

Good:

utm_source-google_medium-cpc_campaign-spring-sale
utm_source-google%20ads_medium-paid_campaign-launch

Avoid:

utm_source-google_ads_medium-cpc

In the last example, google_ads is ambiguous because _ is treated as a segment separator.

Examples

Example 1 - Simple campaign entry

Goal: Launch the same onboarding flow from a promo button and know where the user came from.
Setup: Publish a scenario with Start command start and share https://t.me/your_bot?start=promo.
Result: The user enters through /start promo, and TeleGo saves traffic_source = promo.

Example 2 - UTM tracking from ads

Goal: Track source, medium, and campaign from a paid ad.
Setup: Share a link like:

https://t.me/your_bot?start=utm_source-google_medium-cpc_campaign-spring

Then use a Condition Node to branch on utm_campaign = spring or forward the same values through Actions / Sync HTTP.
Result: Campaign attribution is available immediately when the flow starts.

Example 3 - Referral id handoff

Goal: Connect a new user to an existing referrer.
Setup: Share https://t.me/your_bot?start=referral_12345.
Result: TeleGo stores traffic_source = referral and referrer_id = 12345, which you can use later in the flow or send to your backend.

Troubleshooting

Link opens the bot, but the expected scenario does not start

Cause: The published entry scenario is not attached to the start command.
Fix: Open the Start node and make sure Scenario Command is start, then publish again.
Prevention: Treat /start as the public entry command for all deep-link campaigns.

UTM fields are empty

Cause: The payload is not in TeleGo's supported UTM format.
Fix: Use utm_source-..._medium-..._campaign-... style segments.
Prevention: Reuse one tested URL template instead of building links manually each time.

Parameter value is cut or parsed incorrectly

Cause: Unsupported characters, an overly long payload, or raw underscores inside UTM values.
Fix: Keep payloads short, use URL encoding for spaces, and avoid raw underscores inside values.
Prevention: Prefer predictable tokens like promo, spring-sale, or URL-encoded text.

User opens the link but the parameter is not applied yet

Cause: Telegram may show the chat with a Start button; the payload is delivered when that start action is sent.
Fix: Ask the user to press Start if the chat opens without triggering the flow immediately.
Prevention: Test the final link in a clean chat before using it in campaigns.

FAQ

• Q: Does deep linking work with commands other than /start?
  A: For TeleGo scenario entry, use /start. If you need different entry paths, pass different parameters and branch inside the flow.

• Q: Can I pass several values at once?
  A: Yes. The supported way is the UTM-style payload format, for example utm_source-google_medium-cpc_campaign-spring.

• Q: Can I use spaces in values?
  A: Yes, but encode them. For example, use google%20ads instead of a raw space.

• Q: Can I use this for referral links?
  A: Yes. TeleGo supports ref_<source> and referral_<id> payloads.

• Q: Where should I look if attribution is missing later in the flow?
  A: First verify the incoming link format, then check the nodes that read or forward the captured values.

Related pages

• Start Node - Configure the entry command and the first step in the flow.
• Variables and Tags - Understand where captured values live and how to use them.
• Condition Node - Route users based on campaign or source values.
• Actions Node - Sync HTTP - Forward captured tracking data to external systems.