Telegram Bot API

Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start

· 8 min de leitura

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):

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:

  1. Abra o @BotFather e mande /setcommands.
  2. Escolha o seu bot.
  3. 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 escopoQuem vê a listaCampos extras
defaultTodo mundo, se nenhuma lista mais específica se aplicar—
all_private_chatsTodos os chats privados com o bot—
all_group_chatsTodos os grupos e supergrupos—
all_chat_administratorsAdministradores de todos os grupos e supergrupos—
chatUm chat específicochat_id
chat_administratorsAdministradores de um grupo ou supergrupochat_id
chat_memberUm membro de um grupo ou supergrupochat_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:

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.

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

Problemas comuns

SintomaCausa provávelSolução
400 com BOT_COMMAND_INVALIDLetras maiúsculas, hífens, / no início ou mais de 32 caracteres em commandUse de 1 a 32 letras minúsculas, dígitos e underscore, sem a barra
Comandos definidos, mas o usuário vê outra listaUm escopo mais específico ou uma lista no idioma do usuário tem prioridadeConfira cada escopo e idioma com getMyCommands
Bot ignora /start no grupoModo de privacidade e outro bot falou por últimoMande /start@seu_bot ou altere o modo de privacidade
O parâmetro do start não chegaCaracteres fora de A-Z a-z 0-9 _ - (como o padding =) ou mais de 64 caracteresCodifique em base64url, tire o padding, encurte o payload
401 UnauthorizedToken errado ou revogadoVeja 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.

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.