Telegram Bot API

Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard

· 9 min de leitura

O inline keyboard do Telegram é um conjunto de botões preso a uma mensagem do bot: você passa um objeto InlineKeyboardMarkup no parâmetro reply_markup do sendMessage, e um toque num botão de callback envia ao bot um update callback_query, que você precisa responder com answerCallbackQuery. Já o reply keyboard (ReplyKeyboardMarkup) substitui o teclado de letras do usuário por respostas prontas. Este guia cobre os dois tipos de botões de bot do Telegram, todos os tipos de botão, a edição da mensagem após o toque e um exemplo completo e funcional em Python e JavaScript.

Inline keyboard ou reply keyboard?

Inline keyboardReply keyboard
ObjetoInlineKeyboardMarkupReplyKeyboardMarkup
Onde apareceEmbaixo de uma mensagem específicaNo lugar do teclado do usuário
O que o toque fazCallback query, abre URL, Mini App, inline mode, copia texto…Envia o texto do botão como mensagem, ou compartilha contato, localização, usuários, chat
Pode ser editado depoisSim, com editMessageReplyMarkupNão; envie um teclado novo ou remova-o
CanaisSuportadoNão suportado

Os dois vão no mesmo parâmetro reply_markup, junto com ReplyKeyboardRemove e ForceReply. Uma mensagem leva só um desses quatro objetos.

Enviar um inline keyboard no Telegram

inline_keyboard é um array de linhas, e cada linha é um array de botões:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Escolha uma opção:",
    "reply_markup": {
      "inline_keyboard": [
        [{"text": "Curtir", "callback_data": "like"}, {"text": "Ajuda", "callback_data": "help"}],
        [{"text": "Docs do Bot API", "url": "https://core.telegram.org/bots/api"}]
      ]
    }
  }'

Além de text, cada botão precisa ter exatamente um campo que define o seu tipo:

CampoO que o botão faz
callback_dataEnvia ao bot um callback query com essa string, 1–64 bytes
urlAbre um link HTTP ou tg://
web_appAbre uma Mini App; só em chats privados entre o usuário e o bot
login_urlAbre uma URL HTTPS e autoriza o usuário no seu site
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chatColoca o username do bot e uma consulta no campo de texto de outro chat, do chat atual ou de um chat do tipo escolhido
copy_textCopia {"text": "…"} (1–256 caracteres) para a área de transferência
payBotão de pagamento; só em mensagens de fatura, precisa ser o primeiro botão da primeira linha
callback_gameAbre um jogo; precisa ser o primeiro botão da primeira linha
disabledUm DisabledButton que não faz nada (Bot API 10.3)

Dois campos opcionais mudam a aparência do botão (Bot API 9.4, também disponíveis em botões de reply keyboard): style com "danger" (vermelho), "success" (verde) ou "primary" (azul), e icon_custom_emoji_id para um emoji personalizado antes do texto. Emojis personalizados só funcionam se o bot puder usá-los: ele comprou usernames adicionais no Fragment, ou o dono tem Telegram Premium e a mensagem é enviada diretamente a um chat privado, grupo ou supergrupo.

Como planejar o callback_data

O limite de 64 bytes conta bytes, não caracteres, então use valores curtos e legíveis por máquina, como like, page:3 ou del:8812, e deixe os dados reais no banco. A API também avisa que a mensagem pode não ter nenhum botão com o data recebido, então trate esse valor como entrada não confiável do usuário: faça o parse, valide e confira se o usuário pode executar a ação. Um valor longo demais é rejeitado no envio do teclado, normalmente com Bad Request: BUTTON_DATA_INVALID.

Responda todo toque com answerCallbackQuery

Um toque num botão de callback gera um update com o campo callback_query: id, from (o usuário), data e, para mensagens enviadas pelo bot, message com a mensagem original. Depois do toque, os apps do Telegram mostram um indicador de progresso até o bot chamar answerCallbackQuery, então chame o método sempre, mesmo sem outros parâmetros além do id.

ParâmetroSignificado
callback_query_idObrigatório, o id do callback query
textTexto da notificação, 0–200 caracteres; se omitido, nada aparece
show_alerttrue mostra um alerta em vez de uma notificação no topo do chat
urlURL de um jogo (para botões callback_game) ou um link como t.me/your_bot?start=XXXX
cache_timeSegundos em que o resultado pode ficar em cache no app, padrão 0

Responda rápido: um query antigo falha com Bad Request: query is too old and response timeout expired or query ID is invalid. Veja a referência do answerCallbackQuery para mais detalhes.

Editar a mensagem depois do toque

Atualizar a mensagem existente é mais rápido e mais limpo do que mandar uma nova, e o Telegram recomenda isso para configurações e paginação. Pegue chat.id e message_id de callback_query.message e chame:

Se o texto e o teclado novos forem idênticos aos atuais, a API devolve Bad Request: message is not modified, então compare antes de editar ou ignore esse erro específico.

Exemplo completo: menu inline com botões de callback

Este bot responde ao /start com um menu, conta curtidas por mensagem, mostra um alerta no botão Ajuda e edita a mensagem a cada mudança. Ele usa long polling com getUpdates, então roda em localhost sem webhook. Defina BOT_TOKEN no ambiente antes.

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {}  # (chat_id, message_id) -> contagem


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 menu(count):
    return {"inline_keyboard": [
        [{"text": f"Curtir ({count})", "callback_data": "like", "style": "success"},
         {"text": "Zerar", "callback_data": "reset", "style": "danger"}],
        [{"text": "Ajuda", "callback_data": "help"},
         {"text": "Docs do Bot API", "url": "https://core.telegram.org/bots/api"}],
    ]}


def on_callback(cq):
    msg, data = cq.get("message"), cq.get("data")
    if not msg or data not in ("like", "reset", "help"):
        call("answerCallbackQuery", callback_query_id=cq["id"], text="Botão desconhecido")
        return
    if data == "help":
        call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
             text="Curtir soma um, Zerar recomeça do zero.")
        return
    key = (msg["chat"]["id"], msg["message_id"])
    old = likes.get(key, 0)
    new = old + 1 if data == "like" else 0
    call("answerCallbackQuery", callback_query_id=cq["id"],
         text="Valeu!" if data == "like" else "Contador zerado")
    if new != old:  # evita "message is not modified"
        likes[key] = new
        call("editMessageText", chat_id=key[0], message_id=key[1],
             text=f"Curtidas: {new}", reply_markup=menu(new))


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "callback_query"])
    for update in updates:
        offset = update["update_id"] + 1
        if "callback_query" in update:
            on_callback(update["callback_query"])
        elif update.get("message", {}).get("text") == "/start":
            chat_id = update["message"]["chat"]["id"]
            call("sendMessage", chat_id=chat_id, text="Curtidas: 0", reply_markup=menu(0))
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> contagem

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;
}

function menu(count) {
  return { inline_keyboard: [
    [{ text: `Curtir (${count})`, callback_data: "like", style: "success" },
     { text: "Zerar", callback_data: "reset", style: "danger" }],
    [{ text: "Ajuda", callback_data: "help" },
     { text: "Docs do Bot API", url: "https://core.telegram.org/bots/api" }],
  ] };
}

async function onCallback(cq) {
  const msg = cq.message;
  const data = cq.data;
  if (!msg || !["like", "reset", "help"].includes(data)) {
    await call("answerCallbackQuery", { callback_query_id: cq.id, text: "Botão desconhecido" });
    return;
  }
  if (data === "help") {
    await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
      text: "Curtir soma um, Zerar recomeça do zero." });
    return;
  }
  const key = `${msg.chat.id}:${msg.message_id}`;
  const old = likes.get(key) ?? 0;
  const next = data === "like" ? old + 1 : 0;
  await call("answerCallbackQuery", { callback_query_id: cq.id,
    text: data === "like" ? "Valeu!" : "Contador zerado" });
  if (next !== old) { // evita "message is not modified"
    likes.set(key, next);
    await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
      text: `Curtidas: ${next}`, reply_markup: menu(next) });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", { offset, timeout: 30,
    allowed_updates: ["message", "callback_query"] });
  for (const update of updates) {
    offset = update.update_id + 1;
    if (update.callback_query) {
      await onCallback(update.callback_query);
    } else if (update.message?.text === "/start") {
      await call("sendMessage", { chat_id: update.message.chat.id, text: "Curtidas: 0",
        reply_markup: menu(0) });
    }
  }
}

Salve a versão JavaScript como bot.mjs (ela usa await no nível superior) e rode com Node.js 18+. O contador fica em memória; um bot de verdade guarda isso num banco de dados. Tire os campos style se preferir as cores padrão dos botões.

Reply keyboard no Telegram

O reply keyboard oferece respostas prontas. Um botão de texto simples, que também pode ser escrito só como string, envia o texto ao chat como se o usuário tivesse digitado, então o bot o trata como qualquer outra mensagem:

{
  "keyboard": [
    ["Catálogo", "Carrinho"],
    [{"text": "Compartilhar meu telefone", "request_contact": true},
     {"text": "Enviar localização", "request_location": true}]
  ],
  "resize_keyboard": true,
  "one_time_keyboard": true,
  "input_field_placeholder": "Escolha uma seção"
}
CampoEfeito
resize_keyboardAjusta a altura ao número de linhas; por padrão o teclado tem a altura do teclado normal
one_time_keyboardEsconde o teclado depois de um toque; o usuário pode abri-lo de novo pelo ícone de teclado
is_persistentMostra o teclado sempre que o teclado normal estiver escondido
input_field_placeholderPlaceholder no campo de texto, 1–64 caracteres
selectiveMostra o teclado só para usuários @mencionados ou para o autor da mensagem respondida

Botões especiais funcionam só em chats privados: request_contact envia o telefone do usuário como contato, request_location a localização atual, request_poll pede que ele crie uma enquete e web_app abre uma Mini App. request_users (KeyboardButtonRequestUsers) e request_chat (KeyboardButtonRequestChat) abrem um seletor e devolvem o resultado nas mensagens de serviço users_shared e chat_shared; os dois precisam de um request_id, um número de 32 bits com sinal, único dentro da mensagem:

{"keyboard": [[
  {"text": "Escolher um usuário", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
  {"text": "Escolher meu grupo", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}

ReplyKeyboardRemove e ForceReply

O reply keyboard continua visível até o bot enviar outro. Para removê-lo, envie uma mensagem com {"remove_keyboard": true}. O ForceReply, {"force_reply": true, "input_field_placeholder": "Sua cidade"}, abre a interface de resposta à mensagem do bot, como se o usuário tivesse tocado em Responder. É útil para coletar dados passo a passo em grupos, porque a resposta chega ao bot mesmo com o privacy mode ativado. Assim como os reply keyboards, nenhum dos dois funciona em canais.

Teste no Bot API Tester

  1. Abra o sendMessage no Bot API Tester e informe o seu token e o chat id.
  2. Cole um dos teclados JSON acima em reply_markup e execute.
  3. Toque num botão de callback no Telegram, rode getUpdates no tester para ver o update callback_query e responda com answerCallbackQuery.

Problemas comuns com botões de bot do Telegram

SintomaCausa e solução
Indicador de carregamento depois do toqueFalta a chamada answerCallbackQuery. Responda todo callback query.
Nenhum update callback_query chegaallowed_updates não inclui callback_query, ou outro processo está consumindo os updates (um webhook ou uma segunda instância de polling).
BUTTON_DATA_INVALIDcallback_data vazio ou com mais de 64 bytes.
message is not modifiedA edição não muda nem o texto nem o teclado.
query is too old…A resposta chegou tarde demais, por exemplo depois de um restart que processou updates antigos.
Botão de contato ou localização não faz nada num grupoEsses botões só existem em chats privados.

Para a lista completa de mensagens de erro, veja erros do Telegram Bot API. Formatação e outras opções do sendMessage estão em como enviar mensagens pela API do Telegram, e os botões de switch-to-inline combinam com o inline mode.

Perguntas frequentes

Qual a diferença entre inline keyboard e reply keyboard no Telegram?

O inline keyboard (InlineKeyboardMarkup) fica preso a uma mensagem específica; tocar nos botões não envia nada ao chat. O reply keyboard (ReplyKeyboardMarkup) substitui o teclado de letras do usuário; um botão de texto simples envia o próprio texto como mensagem normal.

Qual o tamanho máximo do callback_data?

1–64 bytes. Bytes, não caracteres: letras acentuadas e outros caracteres fora do ASCII ocupam 2 bytes ou mais em UTF-8. Guarde chaves curtas como item:42 e deixe os dados reais no seu servidor.

Por que o botão fica carregando depois que eu toco nele?

O bot não chamou answerCallbackQuery. Os apps do Telegram mostram um indicador de progresso até você responder, então chame o método para todo callback query, mesmo sem text.

Como trocar os botões depois que o usuário toca em um?

Chame editMessageReplyMarkup com o chat_id e o message_id de callback_query.message para trocar só o teclado, ou editMessageText para mudar o texto e o teclado juntos.

Como remover um reply keyboard?

Envie uma mensagem com reply_markup igual a {"remove_keyboard": true} (ReplyKeyboardRemove). Se quiser só escondê-lo depois de um toque, mantendo-o disponível, use one_time_keyboard.

Dá para colocar botões em mensagens de canal?

Inline keyboards, sim. Reply keyboards, ReplyKeyboardRemove e ForceReply não são suportados em canais.

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.

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.

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

Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.

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.