Notificaciones por Telegram — módulo de Convive

Reenvía a Telegram las notificaciones que el núcleo de Convive emite (nuevos gastos, tareas asignadas, recordatorios, etc.).

Token y chat_id se gestionan desde la propia app, sin tocar archivos de entorno. Cada hogar tiene su propio bot privado y cada usuario su propio chat_id.

Instalación

convive/module-telegram-notifications

(O desde la UI de Convive en /settings/modules → Marketplace → Instalar.)

Cómo configurarlo (una sola vez)

1) Crear un bot en Telegram

1. Abre un chat con @BotFather.
2. Manda /newbot y sigue los pasos: nombre y username (debe acabar en bot).
3. BotFather te dará un token del estilo 123456:AA…ZZ.

2) Pegar el token en Convive

En la app: Telegram (menú lateral) → "Token del bot" → pegar y guardar. Solo el dueño del hogar puede tocarlo.

Pulsa "Verificar bot" para que Convive llame a la Bot API y te diga nombre + username del bot.

3) Vincular tu chat de Telegram

1. Abre un chat con tu bot recién creado y manda /start. El bot no responderá nada (es esperado: este módulo solo envía).
2. Para saber tu chat_id, escribe a @userinfobot. Te devolverá tu id (un número entero).
3. Vuelve a Convive: Telegram → Tu chat_id → pegar y guardar.
4. Pulsa "Probar" — recibirás un mensaje del bot inmediatamente.

A partir de ese momento, cualquier notificación dirigida a ti llegará también por Telegram.

Endpoints

Todos bajo /api/m/telegram-notifications (y /api/telegram legacy).

Método	Ruta	Descripción
GET	/settings	Token del hogar y estado
PUT	/settings	Guardar/actualizar token (owner)
DELETE	/settings	Borrar el token (owner)
GET	/bot-info	getMe para verificar el token
GET	/me	Tu chat_id
PUT	/me	Guardar/actualizar tu chat_id
DELETE	/me	Desvincular tu Telegram
POST	/test	Enviar un mensaje de prueba a tu chat

Tablas

• telegram_settings(household_id PK, bot_token, enabled, updated_at)
• telegram_links(id, household_id, user_id, chat_id, enabled, …)

Privacidad

• El token vive en la BD de Convive del LXC. Nunca sale de tu LAN salvo cuando se llama a api.telegram.org para enviar un mensaje.
• Si desinstalas el módulo, las tablas se conservan; reinstalarlo no pierde el token ni los chat_ids.
• Para borrar también los datos: DROP TABLE telegram_settings; DROP TABLE telegram_links;.

Variables de entorno (opcional)

• TELEGRAM_API_BASE — sustituye el host por defecto. Útil para tests con un servidor mock (http://localhost:9000).

Licencia

MIT