Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start
Os comandos de um bot do Telegram são /palavras-chave como /start ou /help que os apps destacam nas mensagens, sugerem quando o usuário digita / e listam no menu do bot. Você define a lista com /setcommands no @BotFather ou com o método setMyCommands, que também aceita escopos (comandos diferentes para grupos, admins ou um chat específico) e listas por idioma. O bot recebe o comando como uma mensagem de texto comum, e o /start pode trazer um parâmetro de deep link. Este guia cobre tudo isso com exemplos em curl, Python e JavaScript.
Como funcionam os comandos do bot do Telegram
Um comando é só uma mensagem cujo texto começa com /. Registrar comandos não muda o que o bot recebe; apenas diz aos apps do Telegram o que sugerir. Regras da lista registrada com setMyCommands (objeto BotCommand):
command: 1–32 caracteres, só letras minúsculas do alfabeto inglês, dígitos e underscore, sem a barra inicial.description: 1–256 caracteres, aparece ao lado do comando na lista de sugestões.- No máximo 100 comandos por lista.
O Telegram pede que todo bot suporte os comandos globais /start (inicia a interação e também recebe parâmetros de deep link) e /help (o que o bot faz e a lista de comandos), além de /settings se o bot tiver configurações. Prefira comandos específicos como /newlocation a um /new genérico que exige argumentos extras.
Definir comandos pelo @BotFather
O caminho sem código, bom para uma lista fixa:
- Abra o @BotFather e mande
/setcommands. - Escolha o seu bot.
- Envie a lista, um comando por linha no formato
comando - descrição:
start - Iniciar o bot
help - Como usar o bot
settings - Suas configurações
Ainda não tem um bot? Comece por como criar um bot no Telegram.
Definir comandos com setMyCommands
O setMyCommands faz o mesmo via código, então a lista de comandos pode ficar no seu repositório e ser atualizada a cada deploy. Parâmetros: commands (obrigatório, array de BotCommand), scope (opcional, padrão é o escopo default) e language_code (opcional, código ISO 639-1 de duas letras). Devolve true:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"Iniciar o bot"},{"command":"help","description":"Como usar o bot"}]}'
Para testar sem código, abra o setMyCommands no Bot API Tester, cole o token, preencha os comandos e clique em Execute. Depois chame getMyCommands para ver a lista salva.
Escopos de comandos e idiomas
O escopo define quem vê a lista. Existem 7 tipos de BotCommandScope:
type do escopo | Quem vê a lista | Campos extras |
|---|---|---|
default | Todo mundo, se nenhuma lista mais específica se aplicar | — |
all_private_chats | Todos os chats privados com o bot | — |
all_group_chats | Todos os grupos e supergrupos | — |
all_chat_administrators | Administradores de todos os grupos e supergrupos | — |
chat | Um chat específico | chat_id |
chat_administrators | Administradores de um grupo ou supergrupo | chat_id |
chat_member | Um membro de um grupo ou supergrupo | chat_id, user_id |
O chat_id é um id numérico ou o @username de um supergrupo; canais e chats de mensagens diretas de canais não são suportados. Cada escopo também pode ter listas por idioma: com language_code a lista vale para usuários com o app nesse idioma; sem ele, para todos do escopo que não têm uma lista própria no seu idioma.
O Telegram mostra a primeira lista definida, conferindo do escopo mais específico para o mais amplo. No chat privado a ordem é chat → all_private_chats → default; em grupos é chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default (os escopos de admin só valem para administradores). Em cada etapa, a lista com o language_code do usuário ganha da lista sem idioma.
Este script define uma lista padrão em português, uma versão em inglês e comandos extras para admins de grupo, e depois lê uma delas:
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=10).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
# Lista padrão para todo mundo
call("setMyCommands", commands=[
{"command": "start", "description": "Iniciar o bot"},
{"command": "help", "description": "Como usar o bot"},
{"command": "settings", "description": "Suas configurações"},
])
# Os mesmos comandos para quem usa o Telegram em inglês
call("setMyCommands", language_code="en", commands=[
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "How to use the bot"},
{"command": "settings", "description": "Your settings"},
])
# Comandos extras para administradores de todos os grupos
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
{"command": "help", "description": "Como usar o bot"},
{"command": "stats", "description": "Estatísticas do grupo"},
])
print(call("getMyCommands", scope={"type": "all_chat_administrators"}))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),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
// Lista padrão para todo mundo
await call("setMyCommands", {
commands: [
{ command: "start", description: "Iniciar o bot" },
{ command: "help", description: "Como usar o bot" },
{ command: "settings", description: "Suas configurações" },
],
});
// Os mesmos comandos para quem usa o Telegram em inglês
await call("setMyCommands", {
language_code: "en",
commands: [
{ command: "start", description: "Start the bot" },
{ command: "help", description: "How to use the bot" },
{ command: "settings", description: "Your settings" },
],
});
// Comandos extras para administradores de todos os grupos
await call("setMyCommands", {
scope: { type: "all_chat_administrators" },
commands: [
{ command: "help", description: "Como usar o bot" },
{ command: "stats", description: "Estatísticas do grupo" },
],
});
console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));Escopos só controlam o que o usuário vê. O update não diz de qual escopo veio o comando, e o usuário pode digitar qualquer comando, inclusive os que você nunca registrou. Sempre confira no servidor se o comando existe e se o usuário pode executá-lo (por exemplo, verificando os direitos de admin com getChatMember).
getMyCommands e deleteMyCommands
O getMyCommands devolve o array de BotCommand para um scope e language_code, ou um array vazio se nada foi definido. O deleteMyCommands apaga a lista daquele escopo e idioma; os usuários afetados passam a ver a próxima lista na ordem de busca:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"all_chat_administrators"}}'
Tratar comandos e o parâmetro do /start
Os comandos chegam como updates message comuns, com o texto do jeito que foi digitado. Em grupos o comando pode ser endereçado a um bot específico como /command@seu_bot, então remova a parte @username e ignore comandos de outros bots. O deep linking funciona assim:
https://t.me/seu_bot?start=airplaneabre o chat com o seu bot, e ele recebe/start airplane.https://t.me/seu_bot?startgroup=spaceshippede que o usuário escolha um grupo para adicionar o bot; o bot recebe/start@seu_bot spaceship.- O parâmetro aceita até 64 caracteres, e só
A-Z,a-z,0-9,_e-são permitidos. Para dados binários ou outros, o Telegram recomenda base64url.
Um bot com long polling que interpreta comandos, trata o /start com e sem parâmetro e gera um deep link em base64url:
import base64
import os
import re
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
BOT_USERNAME = requests.get(f"{API}/getMe", timeout=10).json()["result"]["username"]
COMMAND_RE = re.compile(r"^/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+(.*))?$", re.S)
def make_start_link(payload: str) -> str:
# base64url sem o padding "=": sobram só A-Z a-z 0-9 _ - (máx. 64 caracteres)
code = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
return f"https://t.me/{BOT_USERNAME}?start={code}"
def read_start_param(code: str) -> str:
return base64.urlsafe_b64decode(code + "=" * (-len(code) % 4)).decode()
def parse_command(text):
m = COMMAND_RE.match(text)
if not m or (m[2] and m[2].lower() != BOT_USERNAME.lower()):
return None # não é comando, ou é comando para outro bot
return m[1].lower(), (m[3] or "").strip()
def send(chat_id, text):
requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=10)
print("Compartilhe este link:", make_start_link("ref:42"))
offset = 0
while True:
resp = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
for update in resp["result"]:
offset = update["update_id"] + 1
msg = update.get("message")
parsed = parse_command(msg.get("text", "")) if msg else None
if not parsed:
continue
name, args = parsed
chat_id = msg["chat"]["id"]
if name == "start" and args:
try:
send(chat_id, "Bem-vindo! Você veio de: " + read_start_param(args))
except ValueError:
send(chat_id, "Bem-vindo! Parâmetro de início desconhecido.")
elif name == "start":
send(chat_id, "Bem-vindo! Mande /help para ver o que eu sei fazer.")
elif name == "help":
send(chat_id, "/start - iniciar o bot\n/help - esta mensagem\n/settings - suas configurações")
elif name == "settings":
send(chat_id, "Ainda não há configurações.")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const BOT_USERNAME = (await (await fetch(`${API}/getMe`)).json()).result.username;
const COMMAND_RE = /^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+([\s\S]*))?$/;
function makeStartLink(payload) {
// o base64url do Node não tem padding "=": sobram só A-Z a-z 0-9 _ - (máx. 64 caracteres)
const code = Buffer.from(payload).toString("base64url");
return `https://t.me/${BOT_USERNAME}?start=${code}`;
}
function readStartParam(code) {
return Buffer.from(code, "base64url").toString("utf8");
}
function parseCommand(text) {
const m = COMMAND_RE.exec(text);
if (!m || (m[2] && m[2].toLowerCase() !== BOT_USERNAME.toLowerCase())) {
return null; // não é comando, ou é comando para outro bot
}
return { name: m[1].toLowerCase(), args: (m[3] ?? "").trim() };
}
async function send(chatId, text) {
await fetch(`${API}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: chatId, text }),
});
}
console.log("Compartilhe este link:", makeStartLink("ref:42"));
let offset = 0;
while (true) {
const resp = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
for (const update of resp.result) {
offset = update.update_id + 1;
const msg = update.message;
const parsed = msg ? parseCommand(msg.text ?? "") : null;
if (!parsed) continue;
const { name, args } = parsed;
const chatId = msg.chat.id;
if (name === "start" && args) {
await send(chatId, "Bem-vindo! Você veio de: " + readStartParam(args));
} else if (name === "start") {
await send(chatId, "Bem-vindo! Mande /help para ver o que eu sei fazer.");
} else if (name === "help") {
await send(chatId, "/start - iniciar o bot\n/help - esta mensagem\n/settings - suas configurações");
} else if (name === "settings") {
await send(chatId, "Ainda não há configurações.");
}
}
}Salve a versão JavaScript como bot.mjs e rode com Node.js 18+ (ela usa await no nível superior). Trate o parâmetro do start como entrada não confiável: qualquer pessoa pode montar um link, então nunca coloque nele um segredo que dê acesso sozinho. O getUpdates não funciona com webhook ativo; para produção, veja como configurar o webhook do bot do Telegram.
Comandos em grupos e modo de privacidade
Em grupos, bots funcionam por padrão no modo de privacidade. Nesse modo recebem os comandos endereçados a eles (/command@seu_bot), comandos genéricos como /start só se foram o último bot a mandar mensagem no grupo, respostas às suas mensagens e mensagens de serviço. Quando vários bots dividem o grupo, peça que os usuários toquem nos comandos da lista, que já incluem o @seu_bot. Para receber todas as mensagens, torne o bot admin ou desligue o modo de privacidade com /setprivacy no @BotFather.
O botão de menu
Nos chats privados, um botão de menu ao lado do campo de mensagem abre a lista de comandos por padrão. Com setChatMenuButton você pode apontá-lo para uma Mini App ou de volta para os comandos; sem chat_id, ele muda o padrão de todos os chats:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button":{"type":"commands"}}'
Os outros tipos são web_app (com text e web_app) e default. Desde a Bot API 10.2 um BotCommand também pode ter is_ephemeral: true: esse comando, enviado num grupo, fica invisível para os outros membros e bots, e só o bot o recebe.
Boas práticas para comandos de bot
- Mantenha a lista curta. Registre os comandos que as pessoas realmente usam; ferramentas de admin pouco usadas ficam melhor num escopo só para admins.
- Escreva descrições que indiquem a ação. "Criar um lembrete" diz mais do que "Lembretes".
- Defina os comandos no deploy. Chamar
setMyCommandsno script de deploy mantém o menu em sincronia com o código que trata os comandos. - Responda com educação a comandos desconhecidos nos chats privados, por exemplo indicando o
/help. - Use botões para escolhas. Em fluxos de várias etapas, teclados inline costumam ser mais práticos do que comandos com argumentos.
Problemas comuns
| Sintoma | Causa provável | Solução |
|---|---|---|
400 com BOT_COMMAND_INVALID | Letras maiúsculas, hífens, / no início ou mais de 32 caracteres em command | Use de 1 a 32 letras minúsculas, dígitos e underscore, sem a barra |
| Comandos definidos, mas o usuário vê outra lista | Um escopo mais específico ou uma lista no idioma do usuário tem prioridade | Confira cada escopo e idioma com getMyCommands |
Bot ignora /start no grupo | Modo de privacidade e outro bot falou por último | Mande /start@seu_bot ou altere o modo de privacidade |
| O parâmetro do start não chega | Caracteres fora de A-Z a-z 0-9 _ - (como o padding =) ou mais de 64 caracteres | Codifique em base64url, tire o padding, encurte o payload |
401 Unauthorized | Token errado ou revogado | Veja o guia do token do bot |
Perguntas frequentes
Como adicionar comandos ao meu bot do Telegram?
Mande /setcommands para o @BotFather e escolha o bot, ou chame o método setMyCommands da Bot API com uma lista de objetos BotCommand. Os apps do Telegram passam a sugerir os comandos quando o usuário digita / e mostram a lista no menu.
Quais caracteres um comando de bot do Telegram pode ter?
No setMyCommands o comando tem de 1 a 32 caracteres e só aceita letras minúsculas do alfabeto inglês, dígitos e underscore. A descrição tem de 1 a 256 caracteres. São no máximo 100 comandos por escopo e idioma.
Como passar um parâmetro para o /start?
Use um deep link como https://t.me/seu_bot?start=airplane. O bot recebe a mensagem /start airplane. O parâmetro aceita até 64 caracteres entre A-Z, a-z, 0-9, _ e -; para outros dados, use base64url.
Por que meu bot não vê os comandos no grupo?
Com o modo de privacidade ligado (o padrão), o bot no grupo recebe os comandos endereçados a ele, como /command@seu_bot, e comandos genéricos como /start só se foi o último bot a mandar mensagem ali. Use a forma com @seu_bot, torne o bot admin ou desligue o modo de privacidade com /setprivacy.
Como mostrar comandos diferentes para os admins do grupo?
Chame setMyCommands com scope igual a {"type": "all_chat_administrators"} para todos os grupos, ou {"type": "chat_administrators", "chat_id": ...} para um grupo só. Mesmo assim, confira as permissões no servidor: o update não diz de qual escopo veio o comando.
Como remover todos os comandos de um bot?
Chame deleteMyCommands para cada escopo e language_code que você definiu. Depois disso, o usuário vê a próxima lista na ordem de busca, por exemplo os comandos padrão.
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.
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.
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.