Telegram Bot API

Bot inline no Telegram: como ativar o modo inline e responder às consultas

· 8 min de leitura

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:

  1. 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.
  2. O bot recebe um update inline_query.
  3. O bot chama answerInlineQuery com uma lista de resultados: artigos, fotos, GIFs, vídeos, figurinhas, localizações e mais.
  4. 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.
  5. Opcionalmente, o bot recebe um update chosen_inline_result dizendo 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

  1. Mande /setinline para o @BotFather e escolha o seu bot.
  2. 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…
  3. Opcional: /setinlinegeo pede a localização do usuário em cada consulta; /setinlinefeedback ativa os updates chosen_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:

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:

CampoSignificado
idID único da consulta; passe para o answerInlineQuery como inline_query_id
fromO usuário que digitou a consulta
queryTexto da consulta, até 256 caracteres; pode vir vazio — nesse caso devolva resultados padrão ou populares
offsetPosição dos resultados a devolver; controlada pelo seu bot via next_offset
chat_typeOpcional: sender (chat privado com quem fez a consulta), private, group, supergroup ou channel; em chats secretos costuma ser desconhecido
locationOpcional; 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âmetroDescrição
inline_query_idObrigatório. O id da consulta
resultsObrigatório. Array de objetos InlineQueryResult (≤ 50)
cache_timeTempo máximo, em segundos, que o resultado pode ficar em cache no servidor; padrão 300
is_personaltrue guarda o cache só para este usuário; por padrão, qualquer usuário que fizer a mesma consulta pode recebê-los
next_offsetValor que o app envia na próxima consulta com o mesmo texto; string vazia se não houver mais resultados; até 64 bytes
buttonInlineQueryResultsButton 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:

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, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

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 resultados
const 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:

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

SintomaCausa provável e solução
Nada acontece depois de digitar @seu_botO modo inline não está ativado: use /setinline ou setMySettings.
Nenhum update inline_queryO 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 aparecendoCache 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 invalidA resposta chegou tarde demais ou com o ID errado. Responda na hora e deixe o trabalho pesado em segundo plano.
Nenhum chosen_inline_resultO feedback inline está desligado: /setinlinefeedback ou inline_feedback_share_denominator.
Resultados com foto não aparecemO 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.

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.