Skip to content

Inline mode

Let people type @yourbot and a few words in any chat and send one of your bot's answers. Articles, photos, GIFs, paging, switch to the bot and chosen results.

With inline mode, people type @yourbot and a few words in any chat, 1:1 or group, even one your bot isn't in. Your bot answers with a list of results. The person taps one, and it's sent into their chat as their own message, marked via @yourbot.

The query and the answer are encrypted between the person and your bot. Your bot never learns which chat the query came from, or who else is in it. It learns the person's address, what they typed and their app's language.

Turn it on

In the app, turn on Answer @username in any chat on your bot's page in My bots, and set a Placeholder. Or from code:

TypeScript
await bot.setInline({ placeholder: 'Search a token', feedback: true });
Python
await bot.set_inline(True, placeholder="Search a token", feedback=True)

feedback asks the app to tell your bot which result was picked. It's off unless you turn it on.

Answer queries

TypeScript
import { InlineResult, fmt, bold } from '@morsel/bot';

const TOKENS: Record<string, string> = { sol: 'Solana', jup: 'Jupiter', bonk: 'Bonk' };

bot.inline(async (ctx) => {
  const q = ctx.inlineQuery!.query.toLowerCase();
  const results = Object.keys(TOKENS)
    .filter((k) => k.startsWith(q))
    .map((k) => InlineResult.article(k, TOKENS[k], fmt`${bold(k.toUpperCase())} is ${TOKENS[k]}`, { description: `Share ${k.toUpperCase()}` }));
  await ctx.answer(results, { cache: 30, switchToBot: { text: 'Open the bot', start: 'inline' } });
});
Python
from morsel_bot import InlineQuery, InlineResult, bold, fmt

TOKENS = {"sol": "Solana", "jup": "Jupiter", "bonk": "Bonk"}


@bot.inline()
async def search(q: InlineQuery) -> None:
    results = [
        InlineResult.article(k, name, fmt(bold(k.upper()), f" is {name}"), description=f"Share {k.upper()}")
        for k, name in TOKENS.items()
        if k.startswith(q.query.lower())
    ]
    await q.answer(results, cache_time=30, switch_to_bot=("Open the bot", "inline"))

In Python, an inline handler gets the InlineQuery itself, not a context. In TypeScript, the query is ctx.inlineQuery: query, offset, from and lang.

Answer optionTypeScriptPython
Next pagenextnext_offset=Up to 64 characters. The app sends it back as offset when the person scrolls.
Cachecachecache_time=0 to 300 seconds the app may reuse this answer.
Switch to the botswitchToBot: { text, start }switch_to_bot=(text, start)A button above the results that opens your bot's chat, and sends /start <start> when they tap Start.

Kinds of results

KindTypeScriptPythonWhat's sent when picked
ArticleInlineResult.article(id, title, text, { description, thumb, keyboard })InlineResult.article(id, title, text, description=, thumb=, keyboard=)The text, with its formatting and buttons.
PhotoInlineResult.photo(id, bytes, { caption, thumb, keyboard })InlineResult.photo(id, data, caption=, thumb=, keyboard=)The photo, with its caption.
GIFInlineResult.gif(id, gif, { caption })InlineResult.gif(id, gif, caption=)The GIF, with its caption.

In TypeScript, a plain object works for an article too: { id, title, description, message: { text } }. When every result is a photo or a GIF, the app shows a grid. Otherwise a list.

Photos and GIFs

TypeScript
import { readFile } from 'node:fs/promises';

bot.inline(async (ctx) => ctx.answer([
  InlineResult.photo('chart', await readFile('chart.png'), { caption: 'SOL, 24 h' }),
  InlineResult.gif('party', {
    id: 'xT9IgG50Fb7Mi0prBC',
    mp4: { u: 'https://media.giphy.com/media/xT9IgG50Fb7Mi0prBC/giphy.mp4', w: 480, h: 270 },
  }),
]));
Python
@bot.inline()
async def pictures(q: InlineQuery) -> None:
    with open("chart.png", "rb") as f:
        chart = f.read()
    await q.answer([
        InlineResult.photo("chart", chart, caption="SOL, 24 h"),
        InlineResult.gif("party", {
            "id": "xT9IgG50Fb7Mi0prBC",
            "mp4": {"u": "https://media.giphy.com/media/xT9IgG50Fb7Mi0prBC/giphy.mp4", "w": 480, "h": 270},
        }),
    ])

No result ever makes the person's phone load something from a server you pick. That would give you their IP address and the moment they looked.

  • A photo is a chat file of your bot's. The SDK encrypts it with the chat media encryption and uploads it when the answer goes, once per process for the same bytes, for 20 hours. Morsel then lets only the person who asked fetch it and send it, for an hour. PNG, JPEG or WebP. thumb is an optional tiny preview, base64, up to 2400 characters, shown blurred until the picture loads.
  • A GIF is a GIPHY GIF, the provider Morsel already uses for GIFs, from GIPHY's media hosts only.
  • An article's thumb is an https picture. The app loads it through Morsel's image proxy.

Chosen results

With feedback on, your bot hears which result was picked. Use it for stats, not for anything that must be exact: the person's app sends it.

TypeScript
bot.on('chosen_inline', (ctx) => console.log('picked', ctx.update.chosenInline?.resultId));
Python
@bot.chosen_inline()
async def chosen(ctx: Context) -> None:
    assert ctx.chosen_inline is not None
    logging.info("picked %s", ctx.chosen_inline.result_id)

Rules and limits

  • Answer within 30 seconds, once per query. Answer fast: the app waits about 10 seconds for results before it shows The bot didn't answer. Try again.
  • Up to 50 results an answer. A result id is 1 to 64 characters of A-Z a-z 0-9 _ . : -. A title is up to 128 characters, a description up to 256.
  • A query is up to 256 characters.
  • Queries asked while your bot was offline are kept for a minute, and the SDK answers them when it reconnects.
  • People can send 5 queries a second, and a bot gets up to 200 a second.
  • A query reaches your bot only when inline mode is on. Otherwise the app gets 409 INLINE_OFF.

Try one of these