Telegram Bot API

Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start

· 8 min de lectura

Los comandos de un bot de Telegram son /palabras como /start o /help que las apps de Telegram resaltan en los mensajes, sugieren cuando el usuario escribe / y muestran en el menú del bot. La lista se define con /setcommands en @BotFather o con el método setMyCommands, que además admite scopes (comandos distintos para grupos, administradores o un chat concreto) y listas por idioma. Tu bot recibe cada comando como un mensaje de texto normal, y /start puede traer un parámetro de deep link. Esta guía lo cubre todo con ejemplos en curl, Python y JavaScript.

Cómo funcionan los comandos de un bot de Telegram

Un comando es simplemente un mensaje cuyo texto empieza con /. Registrar comandos no cambia lo que recibe tu bot; solo le dice a las apps de Telegram qué sugerir. Las reglas de la lista que registras con setMyCommands (el objeto BotCommand):

Telegram pide que todos los bots admitan los comandos globales /start (inicia la interacción y también recibe los parámetros de deep link) y /help (qué hace el bot y lista de comandos), además de /settings si el bot tiene configuración. Prefiere comandos concretos como /newlocation a uno genérico como /new que necesite argumentos extra.

Configurar comandos con @BotFather

La vía sin código, ideal para una lista fija:

  1. Abre @BotFather y envía /setcommands.
  2. Elige tu bot.
  3. Envía la lista, un comando por línea con el formato comando - descripción:
start - Iniciar el bot
help - Cómo usar el bot
settings - Tu configuración

Si todavía no tienes bot, empieza por cómo crear un bot en Telegram.

Configurar comandos con setMyCommands

setMyCommands hace lo mismo desde código, así la lista de comandos vive en tu repositorio y se actualiza en cada deploy. Parámetros: commands (obligatorio, arreglo de BotCommand), scope (opcional; por defecto, el scope default) y language_code (opcional, código ISO 639-1 de dos letras). Devuelve true:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands":[{"command":"start","description":"Iniciar el bot"},{"command":"help","description":"Cómo usar el bot"}]}'

Para probarlo sin código, abre setMyCommands en Bot API Tester, pega tu token, completa los comandos y pulsa Execute. Luego llama a getMyCommands para ver la lista guardada.

Scopes de comandos e idiomas

El scope decide quién ve una lista. Hay 7 tipos de BotCommandScope:

type del scopeQuién ve la listaCampos extra
defaultTodos, si no aplica una lista más específica—
all_private_chatsTodos los chats privados con el bot—
all_group_chatsTodos los grupos y supergrupos—
all_chat_administratorsAdministradores de todos los grupos y supergrupos—
chatUn chat concretochat_id
chat_administratorsAdministradores de un grupo o supergrupochat_id
chat_memberUn miembro de un grupo o supergrupochat_id, user_id

chat_id es un id numérico o el @username de un supergrupo; los canales y los chats de mensajes directos de canales no están soportados. Cada scope puede tener además listas por idioma: con language_code la lista llega a los usuarios con ese idioma en la app; sin él, a todos los del scope que no tengan una lista propia para su idioma.

Telegram muestra la primera lista definida, revisando desde el scope más específico hacia el más general. En un chat privado el orden es chat → all_private_chats → default; en grupos es chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default (los scopes de administradores solo aplican a administradores). En cada paso, la lista con el language_code del usuario gana a la que no lo tiene.

Este script define una lista por defecto, una versión en inglés y comandos extra para los administradores de grupos, y luego lee una de ellas:

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 por defecto para todos
call("setMyCommands", commands=[
    {"command": "start", "description": "Iniciar el bot"},
    {"command": "help", "description": "Cómo usar el bot"},
    {"command": "settings", "description": "Tu configuración"},
])

# Los mismos comandos para usuarios con Telegram en 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 extra para los administradores de todos los grupos
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
    {"command": "help", "description": "Cómo usar el bot"},
    {"command": "stats", "description": "Estadísticas del 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 por defecto para todos
await call("setMyCommands", {
  commands: [
    { command: "start", description: "Iniciar el bot" },
    { command: "help", description: "Cómo usar el bot" },
    { command: "settings", description: "Tu configuración" },
  ],
});

// Los mismos comandos para usuarios con Telegram en 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 extra para los administradores de todos los grupos
await call("setMyCommands", {
  scope: { type: "all_chat_administrators" },
  commands: [
    { command: "help", description: "Cómo usar el bot" },
    { command: "stats", description: "Estadísticas del grupo" },
  ],
});

console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));

Los scopes solo controlan lo que los usuarios ven. Las actualizaciones no indican de qué scope vino un comando, y cualquiera puede escribir cualquier comando, incluso uno que nunca registraste. Verifica siempre en el servidor que el comando existe y que el usuario puede ejecutarlo (por ejemplo, revisa los permisos de administrador con getChatMember).

getMyCommands y deleteMyCommands

getMyCommands devuelve el arreglo de BotCommand para un scope y un language_code dados, o un arreglo vacío si no hay ninguno. deleteMyCommands borra la lista de ese scope e idioma; los usuarios afectados verán la siguiente lista en el orden de búsqueda:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"scope":{"type":"all_chat_administrators"}}'

Procesar comandos y el parámetro de /start

Los comandos llegan como actualizaciones message normales, con el texto tal como se escribió. En grupos un comando puede ir dirigido a un bot concreto como /command@tu_bot, así que quita la parte @username e ignora los comandos destinados a otros bots. El deep linking funciona así:

Un bot con long polling que interpreta comandos, maneja /start con y sin parámetro y genera un deep link en 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 sin relleno "=": solo quedan A-Z a-z 0-9 _ - (máximo 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  # no es un comando, o es un comando para otro 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("Comparte este enlace:", 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, "¡Bienvenido! Llegaste desde: " + read_start_param(args))
            except ValueError:
                send(chat_id, "¡Bienvenido! Parámetro de inicio desconocido.")
        elif name == "start":
            send(chat_id, "¡Bienvenido! Envía /help para ver lo que puedo hacer.")
        elif name == "help":
            send(chat_id, "/start - iniciar el bot\n/help - este mensaje\n/settings - tu configuración")
        elif name == "settings":
            send(chat_id, "Todavía no hay opciones de configuración.")
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) {
  // base64url de Node no lleva relleno "=": solo quedan A-Z a-z 0-9 _ - (máximo 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; // no es un comando, o es un comando para otro 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("Comparte este enlace:", 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, "¡Bienvenido! Llegaste desde: " + readStartParam(args));
    } else if (name === "start") {
      await send(chatId, "¡Bienvenido! Envía /help para ver lo que puedo hacer.");
    } else if (name === "help") {
      await send(chatId, "/start - iniciar el bot\n/help - este mensaje\n/settings - tu configuración");
    } else if (name === "settings") {
      await send(chatId, "Todavía no hay opciones de configuración.");
    }
  }
}

Ejecuta la versión de JavaScript como bot.mjs con Node.js 18+ (usa await de nivel superior). Trata el parámetro de inicio como entrada no confiable: cualquiera puede armar un enlace, así que nunca pongas en él un secreto que por sí solo dé acceso. getUpdates no funciona mientras haya un webhook configurado; para producción revisa cómo configurar el webhook de un bot de Telegram.

Comandos en grupos y modo privacidad

En los grupos, los bots funcionan en modo privacidad por defecto. Así reciben los comandos dirigidos explícitamente a ellos (/command@tu_bot), los comandos generales como /start solo si el bot fue el último bot en escribir en el grupo, las respuestas a sus mensajes y los mensajes de servicio. Cuando varios bots comparten un grupo, pide a los usuarios que toquen los comandos desde la lista, que añade la parte @tu_bot. Para recibir todos los mensajes, haz al bot administrador o desactiva el modo privacidad con /setprivacy en @BotFather.

En los chats privados, un botón de menú junto al campo de texto abre por defecto la lista de comandos. Con setChatMenuButton puedes hacer que abra una Mini App, o que vuelva a mostrar los comandos; sin chat_id cambia el valor por defecto de todos los chats:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button":{"type":"commands"}}'

Los otros tipos son web_app (con text y web_app) y default. Desde Bot API 10.2 un BotCommand también puede tener is_ephemeral: true: ese comando enviado en un grupo queda invisible para los demás miembros y bots, y solo lo recibe el bot.

Buenas prácticas para los comandos

Solución de problemas

SíntomaCausa probableSolución
400 con BOT_COMMAND_INVALIDMayúsculas, guiones, una / inicial o más de 32 caracteres en commandUsa de 1 a 32 letras minúsculas, dígitos y guiones bajos, sin la barra
Configuraste comandos, pero un usuario ve otra listaTiene prioridad un scope más específico o una lista para el idioma del usuarioRevisa cada scope e idioma con getMyCommands
El bot ignora /start en un grupoModo privacidad y otro bot escribió al últimoEnvía /start@tu_bot o cambia el modo privacidad
El parámetro de inicio no llegaCaracteres fuera de A-Z a-z 0-9 _ - (por ejemplo, el relleno =) o más de 64 caracteresCodifica en base64url, quita el relleno y acorta el payload
401 UnauthorizedToken incorrecto o revocadoConsulta la guía del token del bot

Preguntas frecuentes

¿Cómo agrego comandos a mi bot de Telegram?

Envía /setcommands a @BotFather y elige tu bot, o llama al método setMyCommands de la Bot API con una lista de objetos BotCommand. Las apps de Telegram sugerirán los comandos cuando el usuario escriba / y los mostrarán en el menú.

¿Qué caracteres puede tener un comando de bot de Telegram?

En setMyCommands el texto del comando tiene de 1 a 32 caracteres y solo admite letras inglesas minúsculas, dígitos y guiones bajos. La descripción va de 1 a 256 caracteres. Se pueden definir hasta 100 comandos por scope e idioma.

¿Cómo paso un parámetro a /start?

Usa un deep link como https://t.me/tu_bot?start=airplane. El bot recibe el mensaje /start airplane. El parámetro puede tener hasta 64 caracteres de A-Z, a-z, 0-9, _ y -; para otros datos usa base64url.

¿Por qué mi bot no ve los comandos en un grupo?

Con el modo privacidad activado (por defecto), un bot en un grupo recibe los comandos dirigidos explícitamente a él, como /command@tu_bot, y los generales como /start solo si fue el último bot en escribir ahí. Usa la forma @tu_bot, haz al bot administrador o desactiva el modo privacidad con /setprivacy.

¿Cómo muestro otros comandos a los administradores del grupo?

Llama a setMyCommands con scope igual a {"type": "all_chat_administrators"} para todos los grupos, o {"type": "chat_administrators", "chat_id": ...} para uno solo. Aun así, valida los permisos en el servidor: las actualizaciones no indican de qué scope vino un comando.

¿Cómo elimino todos los comandos de un bot?

Llama a deleteMyCommands para cada scope y cada language_code que hayas definido. Después, los usuarios verán la siguiente lista en el orden de búsqueda, por ejemplo los comandos por defecto.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless

Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.

Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más

Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.

Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes

Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.

Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard

Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Bot inline de Telegram: cómo activar el modo inline y responder consultas

Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.

Cómo probar una Mini App de Telegram: del navegador a Telegram real

Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.