Bot de Telegram

Bot de Telegram — Chuva Bot

Chuva Bot es el componente de Telegram de Kairo. Está integrado directamente en el sistema — cualquier cambio que hagas desde el bot se refleja en tiempo real en el portal web, y viceversa. No es una herramienta externa: comparte la misma base de datos y lógica de negocio que el portal.

---

Vincular tu cuenta (primer paso)

Antes de usar el bot, debes vincular tu cuenta de Kairo con tu cuenta de Telegram. Esto se hace una sola vez.

1. Abre Telegram y busca Chuva Bot
2. Envía el siguiente comando:

   /login tu@email.com tuContraseña
   

3. El bot confirmará la vinculación con un mensaje de bienvenida

⚠️ El comando /login maneja credenciales directamente. Úsalo solo en una conversación privada con el bot, nunca en grupos o canales.

💡 Si cambias tu contraseña en el portal, deberás hacer /login nuevamente para re-vincular.

---

Comandos disponibles

Comando	Descripción
/start	Muestra el mensaje de bienvenida y el menú principal
/help	Lista todos los comandos disponibles con descripción
/my_projects	Lista los proyectos donde eres manager o miembro
/my_tasks	Lista las tareas que tienes asignadas
/task {id}	Muestra el detalle de una tarea (estado, prioridad, asignado, sprint)
/task_status {id} {status} [horas]	Cambia el estado de una tarea
/comment {id} {texto}	Agrega un comentario a una tarea

Cambiar el estado de una tarea

/task_status {id} {status} [horas]

Los estados válidos son: TODO, IN_PROGRESS, BLOCKED, DONE

⚠️ Si el nuevo estado es DONE, las horas reales son obligatorias. Ejemplo:

/task_status 5 DONE 3.5

Omitir las horas devuelve un mensaje de error.

---

Lenguaje natural

No necesitas memorizar los comandos exactos. Chuva Bot entiende mensajes en lenguaje natural gracias a su integración con Claude API.

Ejemplos

Lo que escribes	Lo que ejecuta el bot
"hola" / "menú" / "comenzar"	/start
"ayuda" / "qué puedo hacer"	/help
"dame mis proyectos" / "en qué proyectos estoy"	/my_projects
"dame mis tareas" / "qué tengo pendiente"	/my_tasks
"muéstrame la tarea 5" / "detalle de tarea 3"	/task 5 / /task 3
"pon la tarea 5 en progreso"	/task_status 5 IN_PROGRESS
"marca la 3 como done con 2 horas"	/task_status 3 DONE 2
"comenta en la tarea 5: revisé el código"	/comment 5 revisé el código

Comportamiento cuando faltan parámetros

Si el bot entiende tu intención pero le falta información, responde con un mensaje específico:

Situación	Respuesta del bot
Quieres marcar DONE pero no diste las horas	"Para marcar una tarea como DONE debes especificar tus horas reales. Ejemplo: marca la tarea 5 como done con 3.5 horas"
No identifica qué tarea quieres ver	"No identifiqué qué tarea quieres ver. Dime el ID de la tarea."
No entiende el estado	"No identifiqué el nuevo estado. Los estados válidos son: TODO, IN_PROGRESS, BLOCKED, DONE."
No entiende el mensaje	"No entendí tu mensaje. Escribe /help para ver los comandos disponibles."

💡 El comando /login no está disponible en lenguaje natural por razones de seguridad.

---

Notificaciones automáticas

Chuva Bot envía notificaciones proactivas en los siguientes eventos:

Evento	Quién recibe
Sprint próximo a vencer (≤ 3 días)	Manager + miembros con tareas no-DONE
Tarea marcada como BLOCKED	Manager del proyecto
Cambio de estado en una tarea	Miembro asignado a esa tarea

Las notificaciones se envían como mensajes directos del bot a tu chat privado. Si una notificación falla, el sistema la reintenta automáticamente.

⚠️ Para recibir notificaciones debes tener tu cuenta vinculada con /login. Sin vinculación, las notificaciones no pueden entregarse.

---

Preguntas frecuentes del bot

¿El bot necesita estar activo para que Kairo funcione? No. El bot de Telegram es opcional. El portal web y la API funcionan de forma independiente. El bot solo requiere que la variable de entorno TELEGRAM_BOT_TOKEN esté configurada en el servidor.

¿Qué pasa si el bot no responde a mis mensajes en lenguaje natural? El NLU requiere que la variable ANTHROPIC_API_KEY esté configurada. Si no lo está, los mensajes sin / reciben una respuesta genérica de "no entendí". Los comandos con / siempre funcionan.

¿Puedo desvincular mi cuenta de Telegram? Actualmente no hay un comando de desvinculación. Para desvincular, contacta a un administrador del sistema.

Ver más respuestas en Preguntas Frecuentes.