• Cuenta de Telegram (la app que ya usas, en móvil o escritorio)
  • Una terminal — si no has usado ninguna, en la guía de webhooks se explica cómo abrirla
  • Nada que instalar ni pagar

Introducción

Un bot de Telegram es una cuenta de Telegram que no maneja una persona, sino un programa. No se controla desde la app: se le dan órdenes llamando a una dirección web que Telegram pone a tu disposición, la Bot API.

Esa dirección tiene esta forma, y a la parte final (sendMessage) se le llama método: es la orden que le estás dando.

text
https://api.telegram.org/bot<TOKEN>/sendMessage

Le mandas dos datos —a qué chat y qué texto— y Telegram entrega el mensaje. Quien haga esa llamada da igual: un script tuyo, un servidor, una tarea automática que corre al desplegar, o tú desde la terminal para probar.

En una frase: algo llama a esa dirección → aparece un mensaje en tu chat.

El <TOKEN> que aparece ahí es la contraseña del bot, y te la dará BotFather en el primer paso.

Problema que resuelve

Quieres que algo te avise al móvil, o al grupo del equipo, sin montar infraestructura. Con un bot mínimo basta: se despliega algo y falla, entra un pedido, alguien rellena un formulario. Cualquier cosa que tu sistema ya detecte puede acabar en un mensaje.

Piezas que debes conocer

PiezaQué esCuidado
BotCuenta creada con @BotFatherSolo envía a chats donde alguien haya iniciado conversación (o a grupos donde esté añadido)
Token123456:ABC… que da BotFatherQuien lo tenga controla el bot — secreto
chat_idIdentificador del chat (número; en grupos suele ser negativo)No es secreto como el token, pero no lo publiques en sitios raros
sendMessageMétodo de la API para publicar textoHay límites de longitud y de ritmo
Modelo mental

Setup mínimo

Haz primero el camino chat privado contigo (es el más simple). El grupo viene después.

Un detalle que sorprende: un bot no puede escribirte hasta que tú le hables primero. Telegram lo impone para que nadie pueda spamearte creando un bot y adivinando tu usuario. De ahí que el tercer paso sea pulsar Start: sin eso, el envío falla aunque el token sea correcto.

  1. En Telegram, habla con @BotFather → /newbot → elige nombre y un username que acabe en bot.
  2. Copia el token (no lo pegues en issues ni capturas).
  3. Abre el chat con tu bot y pulsa Start (o escribe hola).
  4. Con el token, pide getUpdates para ver el chat_id y prueba un sendMessage.

1. Obtener el chat_id

Tras el Start, abre una terminal. Elige tu sistema en el bloque y pega el token de BotFather (parecido a 123456:AAH…) donde dice pega-aqui-tu-token.

bash
TOKEN="pega-aqui-tu-token"
curl -sS "https://api.telegram.org/bot${TOKEN}/getUpdates"

Ese comando pregunta a Telegram «¿qué mensajes ha recibido mi bot?», y la respuesta incluye de quién venían — que es justo el dato que buscas.

Lo que sale es un JSON: el formato en el que las APIs devuelven datos, con etiquetas y valores entre llaves. Viene largo y en una sola línea; no hace falta entenderlo entero. Busca un trozo como este (los números serán los tuyos):

json
"chat": {
  "id": 123456789,
  "type": "private"
}

Ese "id" es tu chat_id. Si la lista viene vacía ("result": []), manda otro mensaje al bot y vuelve a lanzar el comando.

2. Enviar un mensaje de prueba

Usa el mismo token y el chat_id que acabas de ver (solo el número). Sustituye también 123456789 por el tuyo.

bash
TOKEN="pega-aqui-tu-token"
CHAT_ID="123456789"
curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d "{\"chat_id\":${CHAT_ID},\"text\":\"Hola desde la guía\"}"

Respuesta típica si fue bien: "ok": true y un message_id. En Telegram deberías ver el texto.

Eso basta para comprobar token + chat + sendMessage.

¿Y un grupo?

  1. Crea un grupo (o usa uno) y añade el bot.
  2. Dale permiso para enviar mensajes.
  3. Escribe algo en el grupo (para que haya un update).
  4. Vuelve a lanzar getUpdates. El "chat"."id" del grupo suele ser negativo (p. ej. -100123…). Úsalo igual en sendMessage.

Si solo necesitas avisos a ti, quédate con el chat privado.

Seguridad

  • Preferible un bot solo para avisos operativos, no mezclado con otros usos personales.
  • No hace falta exponer una URL pública para enviar avisos (este flujo usa sendMessage saliente).
  • Manda texto plano. Telegram admite un parámetro parse_mode para poner negritas y enlaces, pero entonces trata caracteres como _ o . como marcas de formato: un nombre de rama o un mensaje de error los lleva a menudo y el envío falla con un error poco descriptivo. Empieza sin él.

Errores habituales

SíntomaCausa probableQué hacer
UnauthorizedToken mal copiadoRegenera / vuelve a pegar sin espacios
chat not foundNadie ha hablado al botStart en el chat privado, o añade el bot al grupo
Sin chat_id en getUpdatesNo hay mensajes recientes al botEnvía un mensaje y reintenta el comando
getUpdates vacío aunque escribisteTelegram solo guarda los mensajes recientes, y algunas herramientas los dan por leídosManda otro hola al bot y lanza el comando justo después

Siguiente paso

Cuando sendMessage te funcione:

  1. Engánchalo a tu origen — el mismo POST desde un script, un cron, un job de CI o el receptor de un webhook.
  2. Piensa el formato — empieza en texto plano; añade Markdown/HTML solo si lo necesitas.
  3. Secretos — token (y a veces chat_id) en variables de entorno o el almacén de secretos de tu plataforma.

Con sendMessage funcionando, el bot ya está listo para tus propios flujos: cualquier origen que pueda hacer un POST sirve.

Automatizaciones guiadas

Aplica lo aprendido en la guía con una de nuestras automatizaciones: