get_deep_link
Build a sharable deep link into a project's bot on its connector, for a project, plan, or access code.
Build a sharable deep link into a project's bot on its connector. The start payload depends on which optional input wins, in this precedence order:
| Input | Resulting payload | Use case |
|---|---|---|
access_code | the UUID verbatim | Hand out one-time redemption links. |
plan_id | the plan's bare UUID | Send a subscriber straight to a plan's checkout flow. |
custom | caller-supplied | Track ad campaigns or referral codes with your own payload. |
| (none) | project_<uuid> | Default — opens the bot on the project home flow. |
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose bot URL to embed in the deep-link.
plan_idstringoptionalOptional plan UUID. When set, the payload is that UUID verbatim and the bot opens the plan checkout.
access_codestringoptionalOptional access-code UUID. When set, payload is the UUID verbatim for one-tap redemption.
customstringoptionalOptional caller-supplied payload. Useful for campaign / referral tracking.
What it returns
{ "data": { "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "bot_url": "https://t.me/research_bot", "start_payload": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "deep_link": "https://t.me/research_bot?start=a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }}How it fails
RESOURCE_NOT_FOUNDproject_id is not a valid UUID or out of tenant scope; or plan_id doesn't belong to the project.
VALIDATION_FAILEDplan_id is malformed, or the project has no bot attached (reason: no_bot_attached).
TOKEN_MISSING_ABILITYtoken lacks distribution:read.
How is this guide?
Last updated on