Every inline Telegram bot lives or dies by two things: relevance and latency. There is no onboarding, no menu, no conversation — a user types @yourbot query in any chat, a panel appears above the keyboard, and they tap a result.

I built an image search bot (@repinlybot) and this post is about the Telegram side of it: how inline mode works, which parameters actually change behaviour, and

Six actions to send one reference image, reduced to one query

Enabling inline mode

In BotFather:

/setinline Choose a bot: @yourbot Prompt: Search images… 

The prompt is the placeholder users see. Keep it short and make it obvious what they can type.

The update flow

User types "@yourbot cats" | v Telegram --inline_query--> your backend <--answerInlineQuery-- your backend | v Panel with results -> tap -> content sent to the chat 

Inline query flow: the user types, Telegram calls the bot, results appear above the keyboard

Two update types matter:

  • inline_query — the user typed or changed the query.
  • chosen_inline_result — the user picked a result. This is your conversion event.

chosen_inline_result is only delivered if you enable it in BotFather (/setinlinefeedback). It is off by default, and without it you have no idea whether anyone actually uses your results.

Answering a query

A minimal handler:

bot.on('inline_query', async (ctx) => { const query = ctx.inlineQuery.query.trim(); const offset = Number(ctx.inlineQuery.offset || 0); if (query.length < 2) { return ctx.answerInlineQuery([], { switch_pm_text: 'Type a search query', switch_pm_parameter: 'empty', cache_time: 0, }); } const page = await search(query, offset, 24); await ctx.answerInlineQuery( page.items.map(toResult), { cache_time: 300, is_personal: false, next_offset: page.hasMore ? String(offset + 24) : '', } ); }); 

Four parameters do most of the work.

cache_time

How long Telegram caches the answer for the same query. For image search, 300 seconds is reasonable. But for short or empty queries use 0 — otherwise a user who fixes a typo still sees the cached "nothing found" result.

is_personal

Set true if results depend on the user (history, saved items, language). Otherwise Telegram may serve one user's cached results to another. For a public image search, false is correct.

next_offset

Pagination. Telegram calls you again with this offset when the user scrolls. Return an empty string when there is nothing more. If you always return empty, users see one page and think that is all.

switch_pm_text / switch_pm_parameter

Renders a button that opens a private chat with the bot. Use it for empty states instead of leaving a blank panel.

The inline result panel inside a chat: a grid of pins above the keyboard

Result types: URL vs cached file

For photos you have two options:

// 1. Let Telegram fetch and cache the file { type: 'photo', id: String(item.id), photo_url: item.fullUrl, thumbnail_url: item.thumbUrl, photo_width: item.width, photo_height: item.height, title: item.title, description: item.author, } // 2. Send a file Telegram already has { type: 'photo', id: String(item.id), photo_file_id: item.fileId, title: item.title, } 

The second one is effectively instant, but file_id is only valid for your bot. The pattern that works well:

  1. Return photo_url the first time.
  2. On chosen_inline_result, look up the item by result_id.
  3. Store the file_id that Telegram assigned to the file.
  4. On subsequent queries, return photo_file_id.

This avoids re-downloading the same image on every search.

The 500 ms budget

If the panel takes a second to appear, users describe the bot as slow or broken. Everything else is secondary.

Perceived quality by response time: 300 ms feels instant, 2500 ms feels broken

What helped:

Small thumbnails. The panel is a grid. Serving 1000 px images there is the fastest way to make it feel sluggish. 200–300 px on the long edge is enough.

Query normalization and cache. " Scandinavian Bedroom " and "scandinavian bedroom" should hit the same cache entry.

Skip the origin for short queries. You cannot stop Telegram from sending an inline_query on every keystroke, but you can avoid hitting the backend: check the cache first, and skip search under 2 characters.

Paginate, do not dump. 20–30 results per page. More results means a bigger response and a slower panel.

Images that Telegram cannot fetch

A direct image URL is not always fetchable. Some CDNs require a Referer, block unknown user agents, or return HTML instead of an image. Telegram then silently drops the thumbnail.

The fix is an image proxy or CDN you control:

Telegram -> your proxy -> origin | +- cache: 300 px thumb + original on demand 

This also gives you resizing, format normalization, and the ability to swap the origin later without touching the bot. Budget for it: it is the least glamorous part and the one that decides whether half your results render at all.

Metrics that matter

  • Queries — how many times the bot is invoked.
  • Answers — how many inline_query calls got a non-empty result.
  • Choices — how many chosen_inline_result events.
  • Choice rate = choices / answers.

If the choice rate is low, the problem is relevance. If the answer rate is low, the problem is coverage or normalization. Neither is fixed by adding features.

Also log queries with zero results. It is the cheapest product research you will ever do.

Lessons

  1. Latency is the feature. A relevant result that arrives in 2 seconds loses to a good result in 300 ms.
  2. Handle the empty state. A blank panel reads as "the bot is dead".
  3. Cache the file, not just the search. file_id reuse is a free speedup.
  4. Treat mobile networks as the default. Thumbnails, not originals.
  5. Enable chosen_inline_result early. Otherwise you are flying blind.

Try it

@repinlybot — inline image search for Telegram chats.

If you are building an inline bot, the two areas worth over-investing in are thumbnails and the query cache. Everything else is comparatively straightforward.