Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard
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 keyboard | Reply keyboard | |
|---|---|---|
| Objeto | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| Onde aparece | Embaixo de uma mensagem específica | No lugar do teclado do usuário |
| O que o toque faz | Callback 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 depois | Sim, com editMessageReplyMarkup | Não; envie um teclado novo ou remova-o |
| Canais | Suportado | Nã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:
| Campo | O que o botão faz |
|---|---|
callback_data | Envia ao bot um callback query com essa string, 1–64 bytes |
url | Abre um link HTTP ou tg:// |
web_app | Abre uma Mini App; só em chats privados entre o usuário e o bot |
login_url | Abre uma URL HTTPS e autoriza o usuário no seu site |
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat | Coloca 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_text | Copia {"text": "…"} (1–256 caracteres) para a área de transferência |
pay | Botão de pagamento; só em mensagens de fatura, precisa ser o primeiro botão da primeira linha |
callback_game | Abre um jogo; precisa ser o primeiro botão da primeira linha |
disabled | Um 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âmetro | Significado |
|---|---|
callback_query_id | Obrigatório, o id do callback query |
text | Texto da notificação, 0–200 caracteres; se omitido, nada aparece |
show_alert | true mostra um alerta em vez de uma notificação no topo do chat |
url | URL de um jogo (para botões callback_game) ou um link como t.me/your_bot?start=XXXX |
cache_time | Segundos 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:
editMessageTextpara mudar o texto, opcionalmente com um novoreply_markup;editMessageReplyMarkuppara trocar só o teclado; omitareply_markuppara removê-lo.
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"
}
| Campo | Efeito |
|---|---|
resize_keyboard | Ajusta a altura ao número de linhas; por padrão o teclado tem a altura do teclado normal |
one_time_keyboard | Esconde o teclado depois de um toque; o usuário pode abri-lo de novo pelo ícone de teclado |
is_persistent | Mostra o teclado sempre que o teclado normal estiver escondido |
input_field_placeholder | Placeholder no campo de texto, 1–64 caracteres |
selective | Mostra 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
- Abra o sendMessage no Bot API Tester e informe o seu token e o chat id.
- Cole um dos teclados JSON acima em
reply_markupe execute. - Toque num botão de callback no Telegram, rode
getUpdatesno tester para ver o updatecallback_querye responda com answerCallbackQuery.
Problemas comuns com botões de bot do Telegram
| Sintoma | Causa e solução |
|---|---|
| Indicador de carregamento depois do toque | Falta a chamada answerCallbackQuery. Responda todo callback query. |
Nenhum update callback_query chega | allowed_updates não inclui callback_query, ou outro processo está consumindo os updates (um webhook ou uma segunda instância de polling). |
BUTTON_DATA_INVALID | callback_data vazio ou com mais de 64 bytes. |
message is not modified | A 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 grupo | Esses 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.
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.
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.