Skip to content

Bot links and sharing

Link people straight to your bot's chat with morsel://bot and morselwallet.app/b links, and pass a start payload to track where they came from.

A bot link opens your bot's chat in Morsel. When the person taps Start, the app sends /start, or /start <payload> if the link carries one.

FormatExample
App linkmorsel://bot/price_bot
Web linkhttps://morselwallet.app/b/price_bot
With a payloadmorsel://bot/price_bot?start=ref_42
https://morselwallet.app/b/price_bot?start=ref_42
  • The username is the bot's, without @. Case doesn't matter.
  • The web link also works with www.morselwallet.app.
  • Share in a bot's profile gives people the web link.

Inside Morsel, both formats open the bot's chat. From outside, the morsel:// link opens Morsel when it's installed. The web link is the one to share everywhere: on a phone with Morsel it opens the bot's chat directly, and anyone else lands on the bot's page on morselwallet.app, with its name, description, commands and a button to open it in Morsel or get the app.

Start payloads

The payload tells your bot where someone came from: a campaign, a referral, an order.

  • 1 to 64 characters: A to Z, a to z, 0 to 9, _ and -.
  • A payload that breaks these rules is dropped. The link still opens the chat, and Start sends a plain /start.
  • Your bot reads it as ctx.payload.
TypeScript
bot.command('start', async (ctx) => {
  if (ctx.payload.startsWith('ref_')) await saveReferral(ctx.from!, ctx.payload.slice(4));
  await ctx.reply('Welcome!');
});
Python
@bot.command("start")
async def start(ctx: Context) -> None:
    if ctx.payload and ctx.payload.startswith("ref_"):
        await save_referral(ctx.from_, ctx.payload[4:])
    await ctx.reply("Welcome!")

Anyone can edit a link. Never put secrets in a payload, and don't trust it for anything that matters, like who referred whom for money, without checks of your own.

links.ts
const botLink = (username: string, start?: string) =>
  `https://morselwallet.app/b/${encodeURIComponent(username)}${start ? `?start=${encodeURIComponent(start)}` : ''}`;

botLink('price_bot', 'ref_42'); // https://morselwallet.app/b/price_bot?start=ref_42

From inline mode

Inline answers can carry a switch to the bot button. It opens your bot's chat with a payload, as a link would. See Inline mode.

To open a website in Morsel's browser, or a Morsel screen, see Deep links.

Try one of these