Bot inline no Telegram: como ativar o modo inline e responder às consultas
Um bot inline no Telegram responde a consultas digitadas direto no campo de mensagem: o usuário escreve @seu_bot e um texto em qualquer chat, o bot recebe um update inline_query e responde com answerInlineQuery, e o usuário toca num dos resultados para enviá-lo. Para montar o seu, ative o modo inline (com /setinline no @BotFather ou, desde a Bot API 10.5, com setMySettings), trate os updates inline_query e devolva até 50 resultados. A seguir, cada passo e um exemplo completo em Python e JavaScript.
Como funciona o modo inline
O modo inline funciona em qualquer chat, mesmo onde o bot não é membro. O fluxo:
- O usuário digita o username do bot e uma consulta no campo de mensagem, por exemplo
@seu_bot olá. Nada é enviado ao chat ainda. - O bot recebe um update
inline_query. - O bot chama
answerInlineQuerycom uma lista de resultados: artigos, fotos, GIFs, vídeos, figurinhas, localizações e mais. - O usuário toca num resultado. A mensagem é enviada pelo usuário, e o username do bot aparece ao lado do nome do remetente; na Bot API essa mensagem tem o campo
via_bot. - Opcionalmente, o bot recebe um update
chosen_inline_resultdizendo qual resultado foi enviado.
Ativar o modo inline do bot do Telegram
Em bots novos o modo inline vem desligado. Se você ainda não tem um bot, comece por como criar um bot no Telegram. Depois escolha um dos dois caminhos.
Opção 1: @BotFather
- Mande
/setinlinepara o @BotFather e escolha o seu bot. - Digite o placeholder que o usuário verá no campo de mensagem depois de digitar o username do bot, por exemplo Digite o texto para formatar…
- Opcional:
/setinlinegeopede a localização do usuário em cada consulta;/setinlinefeedbackativa os updateschosen_inline_result.
Opção 2: setMySettings (Bot API 10.5)
Desde a Bot API 10.5 o bot pode alterar as próprias configurações com setMySettings. O que você não passar continua como está:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
-H "Content-Type: application/json" \
-d '{"supports_inline_queries": true, "inline_query_placeholder": "Digite o texto para formatar…", "inline_feedback_share_denominator": 1}'
Os parâmetros do modo inline:
supports_inline_queries—trueliga o modo inline,falsedesliga.inline_query_placeholder— o texto do placeholder; string vazia volta ao padrão.needs_inline_query_location— pede a localização do usuário em toda consulta inline.inline_feedback_share_denominator— recebe 1 de cada N resultados escolhidos; precisa ser 1, 10, 100 ou 1000, e0desliga os updateschosen_inline_result.
Para conferir sem escrever código, abra o setMySettings no Bot API Tester, cole o token e execute; depois chame getMe: o resultado BotFullInfo traz supports_inline_queries e, se você definiu um placeholder próprio, inline_query_placeholder.
O update inline_query
Enquanto o usuário digita, o bot recebe objetos InlineQuery com estes campos:
| Campo | Significado |
|---|---|
id | ID único da consulta; passe para o answerInlineQuery como inline_query_id |
from | O usuário que digitou a consulta |
query | Texto da consulta, até 256 caracteres; pode vir vazio — nesse caso devolva resultados padrão ou populares |
offset | Posição dos resultados a devolver; controlada pelo seu bot via next_offset |
chat_type | Opcional: sender (chat privado com quem fez a consulta), private, group, supergroup ou channel; em chats secretos costuma ser desconhecido |
location | Opcional; só se o bot pedir a localização do usuário |
Se você passa allowed_updates no getUpdates ou no setWebhook, inclua inline_query (e chosen_inline_result, se precisar); senão esses updates não chegam.
Parâmetros do answerInlineQuery
answerInlineQuery devolve True em caso de sucesso. São permitidos no máximo 50 resultados por consulta.
| Parâmetro | Descrição |
|---|---|
inline_query_id | Obrigatório. O id da consulta |
results | Obrigatório. Array de objetos InlineQueryResult (≤ 50) |
cache_time | Tempo máximo, em segundos, que o resultado pode ficar em cache no servidor; padrão 300 |
is_personal | true guarda o cache só para este usuário; por padrão, qualquer usuário que fizer a mesma consulta pode recebê-los |
next_offset | Valor que o app envia na próxima consulta com o mesmo texto; string vazia se não houver mais resultados; até 64 bytes |
button | InlineQueryResultsButton exibido acima dos resultados |
Tipos de resultado inline
Os apps do Telegram suportam 20 tipos de resultado. Doze descrevem conteúdo novo (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game), e oito tipos InlineQueryResultCached… reaproveitam arquivos já guardados nos servidores do Telegram via file_id. Todo resultado precisa de type e de um id de 1 a 64 bytes. Os mais usados:
- article —
titleeinput_message_contentsão obrigatórios; opcionais:description,url,thumbnail_url,reply_markup. O conteúdo costuma ser umInputTextMessageContentcommessage_text(1–4096 caracteres) eparse_modeopcional. - photo —
photo_url(JPEG, até 5 MB) ethumbnail_urlsão obrigatórios; opcionais:caption(0–1024 caracteres),title,description.
Todas as URLs dos resultados inline ficam visíveis para o usuário final, então trate-as como públicas. As regras de formatação do parse_mode são as mesmas de enviar mensagens pela API do Telegram.
Exemplo: bot inline em Python e JavaScript
Este bot formata a consulta em negrito, itálico ou monoespaçado. Consulta vazia recebe um botão para o chat privado, onde o /start responde com botões que voltam ao modo inline. Defina a variável de ambiente BOT_TOKEN antes de rodar.
import html
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def article(result_id, title, text, message_html):
return {
"type": "article",
"id": result_id, # 1-64 bytes, único dentro de uma resposta
"title": title,
"description": text[:100],
"input_message_content": {"message_text": message_html, "parse_mode": "HTML"},
}
def on_inline_query(query):
text = query["query"].strip()
if not text: # consulta vazia: sem resultados, só um botão que abre o chat privado
call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
button={"text": "Como usar este bot", "start_parameter": "help"})
return
safe = html.escape(text)
results = [
article("bold", "Negrito", text, f"<b>{safe}</b>"),
article("italic", "Itálico", text, f"<i>{safe}</i>"),
article("mono", "Monoespaçado", text, f"<code>{safe}</code>"),
]
call("answerInlineQuery", inline_query_id=query["id"], results=results, cache_time=5)
def on_message(msg):
if msg.get("text", "").startswith("/start"): # inclui "/start help" vindo do botão
call("sendMessage", chat_id=msg["chat"]["id"],
text="Digite meu username e um texto em qualquer chat para formatar.",
reply_markup={"inline_keyboard": [[
{"text": "Testar aqui", "switch_inline_query_current_chat": "Olá"},
{"text": "Escolher um chat", "switch_inline_query": "Olá"},
]]})
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "inline_query", "chosen_inline_result"])
for update in updates:
offset = update["update_id"] + 1
try:
if "inline_query" in update:
on_inline_query(update["inline_query"])
elif "chosen_inline_result" in update:
chosen = update["chosen_inline_result"]
print("escolhido:", chosen["result_id"], "para a consulta:", chosen["query"])
elif "message" in update:
on_message(update["message"])
except RuntimeError as err:
print(err)const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
const escapeHtml = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
function article(id, title, text, messageHtml) {
return {
type: "article",
id, // 1-64 bytes, único dentro de uma resposta
title,
description: text.slice(0, 100),
input_message_content: { message_text: messageHtml, parse_mode: "HTML" },
};
}
async function onInlineQuery(query) {
const text = query.query.trim();
if (!text) { // consulta vazia: sem resultados, só um botão que abre o chat privado
await call("answerInlineQuery", {
inline_query_id: query.id, results: [], cache_time: 5,
button: { text: "Como usar este bot", start_parameter: "help" },
});
return;
}
const safe = escapeHtml(text);
const results = [
article("bold", "Negrito", text, `<b>${safe}</b>`),
article("italic", "Itálico", text, `<i>${safe}</i>`),
article("mono", "Monoespaçado", text, `<code>${safe}</code>`),
];
await call("answerInlineQuery", { inline_query_id: query.id, results, cache_time: 5 });
}
async function onMessage(msg) {
if (msg.text?.startsWith("/start")) { // inclui "/start help" vindo do botão
await call("sendMessage", {
chat_id: msg.chat.id,
text: "Digite meu username e um texto em qualquer chat para formatar.",
reply_markup: { inline_keyboard: [[
{ text: "Testar aqui", switch_inline_query_current_chat: "Olá" },
{ text: "Escolher um chat", switch_inline_query: "Olá" },
]] },
});
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "inline_query", "chosen_inline_result"],
});
for (const update of updates) {
offset = update.update_id + 1;
try {
if (update.inline_query) await onInlineQuery(update.inline_query);
else if (update.chosen_inline_result) {
const chosen = update.chosen_inline_result;
console.log("escolhido:", chosen.result_id, "para a consulta:", chosen.query);
} else if (update.message) await onMessage(update.message);
} catch (err) {
console.error(err.message);
}
}
}Salve a versão JavaScript como bot.mjs e rode com Node.js 18+; depois digite @seu_bot olá em qualquer chat. Os mesmos handlers funcionam com webhook — veja como configurar o webhook do bot do Telegram.
Paginação com next_offset
Mais de 50 resultados? Devolva em páginas: o offset vem vazio na primeira consulta, e o seu next_offset volta quando o usuário rola para baixo:
PAGE_SIZE = 20 # answerInlineQuery aceita no máximo 50 resultados
def answer_page(query, items):
start = int(query["offset"] or 0) # offset é "" na primeira consulta
page = items[start:start + PAGE_SIZE]
more = start + PAGE_SIZE < len(items)
call("answerInlineQuery", inline_query_id=query["id"], results=page,
next_offset=str(start + PAGE_SIZE) if more else "") # "" = não há mais resultadosconst PAGE_SIZE = 20; // answerInlineQuery aceita no máximo 50 resultados
async function answerPage(query, items) {
const start = Number(query.offset || 0); // offset é "" na primeira consulta
const page = items.slice(start, start + PAGE_SIZE);
const more = start + PAGE_SIZE < items.length;
await call("answerInlineQuery", {
inline_query_id: query.id, results: page,
next_offset: more ? String(start + PAGE_SIZE) : "", // "" = não há mais resultados
});
}chosen_inline_result e feedback inline
Com o feedback ativado, o bot recebe um objeto ChosenInlineResult com result_id, from, query, location opcional e inline_message_id opcional. Por causa do cache, bots populares podem receber mais resultados escolhidos do que consultas de fato; com carga alta, receba só 1/10, 1/100 ou 1/1000 deles.
O inline_message_id só vem se a mensagem enviada tiver um teclado inline. Guarde-o para editar a mensagem depois com editMessageText (passando inline_message_id no lugar de chat_id e message_id); os cliques nos botões dessa mensagem chegam como callback_query com o mesmo inline_message_id.
Botão acima dos resultados e volta ao chat
O parâmetro button mostra um InlineQueryResultsButton acima dos resultados (ou no lugar deles). Ele tem um text e exatamente um destes campos:
start_parameter— abre o chat privado com o bot e envia/start <parâmetro>; 1–64 caracteres, sóA-Z,a-z,0-9,_e-.web_app— abre uma Mini App, que pode voltar ao modo inline comswitchInlineQuery.
Uso típico: pedir que o usuário conecte uma conta primeiro e depois mandar um botão de teclado inline com switch_inline_query (o usuário escolhe o chat), switch_inline_query_current_chat (insere @seu_bot consulta no chat atual) ou switch_inline_query_chosen_chat (limita a escolha a usuários, bots, grupos ou canais).
Problemas comuns
| Sintoma | Causa provável e solução |
|---|---|
Nada acontece depois de digitar @seu_bot | O modo inline não está ativado: use /setinline ou setMySettings. |
Nenhum update inline_query | O allowed_updates foi definido antes sem inline_query (a lista fica salva), ou há um webhook ativo e o getUpdates devolve 409 Conflict. |
| Resultados antigos continuam aparecendo | Cache no servidor: reduza o cache_time (padrão 300 s) e use is_personal para resultados por usuário. |
400 Bad Request: query is too old and response timeout expired or query ID is invalid | A resposta chegou tarde demais ou com o ID errado. Responda na hora e deixe o trabalho pesado em segundo plano. |
Nenhum chosen_inline_result | O feedback inline está desligado: /setinlinefeedback ou inline_feedback_share_denominator. |
| Resultados com foto não aparecem | O photo_url precisa ser um JPEG público de até 5 MB, e o thumbnail_url é obrigatório. |
Bots inline com muito tráfego também precisam respeitar os limites da Telegram Bot API.
Perguntas frequentes
Como ativar o modo inline de um bot do Telegram?
Mande /setinline para o @BotFather, escolha o bot e digite o texto do placeholder. Desde a Bot API 10.5 o próprio bot também pode fazer isso com setMySettings e supports_inline_queries: true (mais um inline_query_placeholder opcional).
Quantos resultados o answerInlineQuery pode devolver?
No máximo 50 por chamada. Para listas maiores, devolva uma página e passe next_offset (até 64 bytes); o app manda esse valor de volta em offset quando o usuário rola a lista.
Por que os resultados inline não mudam depois que atualizo o código?
Os resultados podem ficar em cache nos servidores do Telegram por cache_time segundos, 300 por padrão. Use um cache_time baixo durante o desenvolvimento e is_personal: true se os resultados dependem do usuário.
O bot inline precisa ser adicionado ao chat?
Não. O usuário digita o username do bot e a consulta no campo de mensagem de qualquer chat; o bot recebe um update inline_query e quem envia o resultado escolhido é o próprio usuário, com a marca do bot (via_bot).
Como saber qual resultado inline o usuário enviou?
Ative o feedback inline com /setinlinefeedback no @BotFather ou com inline_feedback_share_denominator no setMySettings (1, 10, 100 ou 1000). Aí o bot passa a receber updates chosen_inline_result com result_id e query.
Por que o inline_message_id não vem no chosen_inline_result?
Ele só aparece quando a mensagem enviada tem um teclado inline. Inclua reply_markup no resultado se quiser editar a mensagem depois ou receber callback queries dela.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless
Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.
Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais
Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.
Erros do Telegram Bot API: o que cada erro significa e como resolver
Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.
Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens
Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.
Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start
Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.
Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard
Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.
Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens
Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas
Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.
Como testar uma Mini App do Telegram: do mock no navegador ao app real
Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.