Keyboards, callbacks and edits
Put buttons under your bot's messages, answer button presses, show reply buttons above the message box, and edit messages for up to 48 hours.
A bot can show two kinds of buttons. Inline keyboards sit under one of its messages. Reply keyboards sit above the person's message box, and tapping one sends its words.
Inline keyboards
Build one with InlineKeyboard. Buttons fill a row until you call row().
import { InlineKeyboard } from '@morsel/bot';
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const keyboard = new InlineKeyboard()
.text('Refresh', 'refresh') // a callback: sends "refresh" to the bot
.url('Chart', 'https://example.com/sol') // opens a link, after the app shows its domain
.row()
.app('Open app', 'https://app.example.com') // a mini app in Morsel's browser
.copy('Copy code', 'ABC-123')
.row()
.pay('Pro for 5 USDC', { mint: USDC, chain: 'solana', amount: '5', decimals: 6, symbol: 'USDC' });
await ctx.reply('SOL 142.50 USD', { keyboard });from morsel_bot import InlineKeyboard
USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
keyboard = (
InlineKeyboard()
.text("Refresh", "refresh")
.url("Chart", "https://example.com/sol")
.row()
.app("Open app", "https://app.example.com")
.copy("Copy code", "ABC-123")
.row()
.pay("Pro for 5 USDC", mint=USDC, chain="solana", amount="5", decimals=6, symbol="USDC")
)
await ctx.reply("SOL 142.50 USD", keyboard=keyboard)| Button | What it does | Rules |
|---|---|---|
text(label, data) | Sends data back to your bot as a press. | 1 to 64 bytes of data. In TypeScript, data defaults to the label. |
url(label, url) | Opens a link. The app shows the domain first. | https only. |
app(label, url) | Opens the page as a mini app in Morsel's browser. It can connect to the person's wallet, and every signature goes through the usual approval sheet. | https only. |
copy(label, text) | Copies text to the clipboard. | Up to 256 characters. |
pay(label, ...) | Opens Send, filled in to pay your bot's address. The person still confirms. | See Payments. |
Labels are 1 to 64 characters. A keyboard holds up to 8 rows of 8 buttons, 64 in all. The SDKs check all this as you build, so a mistake throws in your code instead of a button quietly missing in the app.
Answer a press
When someone taps a text button, your bot gets a callback. The app shows a spinner on the button until you answer, or for 10 seconds.
bot.callback('refresh', async (ctx) => {
await ctx.answer('Updated'); // a short toast
await ctx.editText('SOL 143.10 USD'); // edit the message that was tapped
});
bot.callback(/^coin:(\w+)$/, async (ctx) => {
const coin = ctx.match![1];
if (coin !== 'sol') return ctx.answer('Unknown coin', { alert: true }); // a dialog
await ctx.answer();
});@bot.callback("refresh")
async def refresh(ctx: Context) -> None:
await ctx.answer("Updated")
await ctx.edit_text("SOL 143.10 USD")
@bot.callback(re.compile(r"^coin:(\w+)$"))
async def coin(ctx: Context) -> None:
assert ctx.match is not None
if ctx.match.group(1) != "sol":
await ctx.answer("Unknown coin", alert=True)
return
await ctx.answer()answer(text)shows a toast. Withalert, a dialog. Withurl, it opens an https link after the same confirm as a link button. The text is up to 200 characters.- Each press can be answered once.
- If your handler doesn't answer, the SDK answers silently for you, so the spinner stops. Turn that off with
autoAnswer: falsein TypeScript orauto_answer_callbacks=Falsein Python. ctx.callbackholds the press: itsdataand the id of the message that was tapped (messageId, ormessage_idin Python).- In a group, only the person who pressed sees your answer. See Groups.
Callback data comes from the person's app. Check it before you act on it.
Edit a message
A bot can edit its own messages for 48 hours, up to 100 times each. Text and buttons can both change. People see the edit in place.
| TypeScript | Python | |
|---|---|---|
ctx.editText(text, { keyboard }) | ctx.edit_text(text, keyboard=) | New text. Inside a press handler, it edits the tapped message. |
ctx.editKeyboard(keyboard) | ctx.edit_keyboard(keyboard) | New buttons, same text. null or None removes them. |
ctx.edit(text, { messageId }) | ctx.edit(message_id, text=) | Edit any of the bot's messages in this chat. |
bot.editMessage(chat, id, text) | bot.edit_message(chat, id, text=) | Edit outside a handler. |
An edit carries the whole message. When you change only the text, the SDK keeps the buttons it last sent. It remembers the last 2000 messages it sent since it started. After a restart, pass the text and keyboard again.
Editing after 48 hours answers 409 EDIT_WINDOW: "Bots can edit their messages for 48 hours."
Reply keyboards
A reply keyboard shows labels above the message box. Tapping one sends that label as a normal text message from the person, so handle it with hears or command.
import { ReplyKeyboard } from '@morsel/bot';
await ctx.reply('Pick a token', {
replyKeyboard: new ReplyKeyboard().text('SOL').text('BONK').text('JUP').row().text('Help').once().placeholder('Pick a token'),
});
bot.hears(['SOL', 'BONK', 'JUP'], (ctx) => ctx.reply(`You picked ${ctx.text}`, { replyKeyboard: ReplyKeyboard.remove() }));from morsel_bot import ReplyKeyboard
await ctx.reply(
"Pick a token",
reply_keyboard=ReplyKeyboard([["SOL", "BONK", "JUP"], ["Help"]]).once().placeholder("Pick a token"),
)
await ctx.reply("Done", reply_keyboard=ReplyKeyboard.remove())| Option | TypeScript | Python |
|---|---|---|
| Hide after one tap | .once() | .once() |
| Placeholder in the message box, up to 64 characters | .placeholder(text) | .placeholder(text) |
| Fit the panel to its buttons | .resized() | .resize() |
| In a group, show it only to some members, up to 50 | .selective(addresses) | .selective(addresses) |
| Remove it | ReplyKeyboard.remove() | ReplyKeyboard.remove() |
Up to 12 rows of 4 labels, each 1 to 64 characters. People can hide the panel themselves with Hide the bot's buttons. Reply keyboards can't be changed by an edit: send a new message.