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.
Link formats
| Format | Example |
|---|---|
| App link | morsel://bot/price_bot |
| Web link | https://morselwallet.app/b/price_bot |
| With a payload | morsel://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:
AtoZ,atoz,0to9,_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.
bot.command('start', async (ctx) => {
if (ctx.payload.startsWith('ref_')) await saveReferral(ctx.from!, ctx.payload.slice(4));
await ctx.reply('Welcome!');
});@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.
Build links in code
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_42From 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.
Other Morsel links
To open a website in Morsel's browser, or a Morsel screen, see Deep links.