deep links

use telegram start payloads for referrals, onboarding, invite attribution, and group setup.

private chat links

link.ts

const payload = "ref_67";
const url = "https://t.me/my_bot?start=" + encodeURIComponent(payload);

read the payload

telegram delivers the payload as arguments to /start. in yaebal command handlers, read ctx.args.

start.ts

bot.command("start", async (ctx) => {
  const payload = ctx.args?.trim();

  if (payload?.startsWith("ref_")) {
    await saveReferral(ctx.from!.id, payload.slice(4));
  }

  await ctx.reply("welcome");
});

group links

use startgroup when the link should add the bot to a group and carry setup context.

group-link.ts

const url = "https://t.me/my_bot?startgroup=" + encodeURIComponent("team_67");

safety rules

treat payloads as untrusted user input.
keep payloads short and url-safe.
store attribution server-side if the payload would expose sensitive data.
make referral writes idempotent; users can click the same link multiple times.
test the first-message path with @yaebal/test.