get_deep_link
Build a sharable Telegram bot deep-link for a project, plan, or access code.
Purpose
Build a sharable Telegram bot deep-link for a project. 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. |
Required ability
distribution:read
Input schema
{
"type": "object",
"required": ["project_id"],
"properties": {
"project_id": {
"type": "string",
"description": "UUID of the project whose bot URL to embed in the deep-link."
},
"plan_id": {
"type": "string",
"description": "Optional plan UUID. When set, the payload is that UUID verbatim and the bot opens the plan checkout."
},
"access_code": {
"type": "string",
"description": "Optional access-code UUID. When set, payload is the UUID verbatim for one-tap redemption."
},
"custom": {
"type": "string",
"description": "Optional caller-supplied payload. Useful for campaign / referral tracking."
}
}
}Output shape
{
"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"
}
}Example prompts
"Give me the Telegram link for my $29 Premium plan so I can post it on X."
"Build a deep-link for access code
abc123so I can DM it to a subscriber."
Failure modes
RESOURCE_NOT_FOUND—project_idis not a valid UUID or out of tenant scope; orplan_iddoesn't belong to the project.VALIDATION_FAILED—plan_idis malformed, or the project has no Telegram bot attached (reason: no_bot_attached).TOKEN_MISSING_ABILITY— token lacksdistribution:read.
Related
get_bot_status— check connection status before building deep-links.get_portal_url- Distribution API
How is this guide?