bioreactor-multiparametric-daq-shield/docs/TELEGRAM_BOT_SETUP.md

Guia de configuracion de Telegram

Esta guia explica como activar notificaciones de alarmas del Photobioreactor Dashboard hacia Telegram. El envio ocurre desde el backend de la Raspberry Pi, por lo que las alertas pueden salir aunque el navegador del dashboard este cerrado.

Requisitos

• Raspberry Pi con acceso a Internet.
• API y recolector funcionando mediante systemd.
• Un token de API configurado en API_AUTH_TOKEN si se desea proteger cambios desde el dashboard.
• Un bot de Telegram creado con BotFather.
• Un chatId de usuario, grupo o canal donde el bot pueda escribir.

Flujo general

Sensor EZO
  |
Recolector de adquisicion
  |
Evaluacion de umbrales
  |
Evento de alarma o recuperacion
  |
logs/alarms.csv
  |
api/notification-service.js
  |
Telegram Bot API
  |
Chat configurado

El sistema no envia mensajes en cada lectura. Solo envia notificaciones cuando se genera un evento de alarma elegible, por ejemplo una transicion a WARNING, CRITICAL, OFFLINE o una recuperacion si la severidad minima lo permite.

Crear el bot

1. Abra Telegram y busque @BotFather.
2. Envie:

/newbot

3. Asigne un nombre visible al bot.
4. Asigne un usuario terminado en bot, por ejemplo:

photobioreactor_alerts_bot

5. BotFather entregara un token con formato parecido a:

1234567890:AAExampleTokenDoNotShare

Guarde este token como secreto. No lo publique en Git, capturas o mensajes.

Obtener el chatId

Chat directo con el bot

1. Abra el bot recien creado.
2. Presione Start o envie cualquier mensaje, por ejemplo:

hola

3. En una terminal, consulte las actualizaciones:

curl "https://api.telegram.org/bot<TOKEN_DEL_BOT>/getUpdates"

4. Busque el campo chat.id. El valor puede verse como:

"chat":{"id":123456789,"first_name":"Cristian","type":"private"}

En este ejemplo, el chatId es:

123456789

Grupo de Telegram

1. Agregue el bot al grupo.
2. Envie un mensaje dentro del grupo mencionando o usando el bot.
3. Ejecute:

curl "https://api.telegram.org/bot<TOKEN_DEL_BOT>/getUpdates"

4. Busque el chat.id del grupo. Normalmente es negativo, por ejemplo:

-1001234567890

Si no aparece ningun resultado, envie otro mensaje en el grupo y repita la consulta. En algunos grupos puede ser necesario permitir que el bot lea mensajes o usar comandos dirigidos al bot.

Configuracion desde el dashboard

1. Abra el dashboard en la red local de la Raspberry Pi.
2. Si API_AUTH_TOKEN esta configurado, escriba ese valor en el campo Token API.
3. Vaya al panel de notificaciones.
4. Active Activas.
5. Seleccione la severidad minima:

Severidad minima	Resultado
WARNING	Envia warnings, offline y criticos
OFFLINE	Envia offline y criticos
CRITICAL	Solo envia alarmas criticas

6. Active Telegram.
7. Escriba el Chat ID.
8. Escriba el Bot token.
9. Guarde la configuracion.

Despues de guardar, el backend nunca devuelve el token completo al navegador. El dashboard lo mostrara como configurado y en guardados posteriores puede dejar el campo de token vacio para conservar el valor existente.

Configuracion directa en Raspberry Pi

En produccion, el instalador usa:

/etc/photobioreactor/notifications.json

La ruta se define en:

NOTIFICATION_CONFIG_FILE=/etc/photobioreactor/notifications.json

Ejemplo de configuracion:

{
    "enabled": true,
    "minSeverity": "CRITICAL",
    "channels": {
        "webhook": {
            "enabled": false,
            "url": "",
            "headers": {}
        },
        "telegram": {
            "enabled": true,
            "botToken": "1234567890:AAExampleTokenDoNotShare",
            "chatId": "123456789"
        }
    }
}

Proteja el archivo porque contiene secretos:

sudo chown photobioreactor:photobioreactor /etc/photobioreactor/notifications.json
sudo chmod 600 /etc/photobioreactor/notifications.json
sudo systemctl restart photobioreactor-acquisition

Prueba manual de Telegram

Antes de probar el dashboard, confirme que Telegram acepta el token y el chat:

curl -X POST "https://api.telegram.org/bot<TOKEN_DEL_BOT>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"<CHAT_ID>","text":"Prueba de alarmas del fotobiorreactor"}'

Si Telegram responde con "ok":true, el bot y el chat estan bien configurados.

Prueba desde el sistema

1. Confirme que el recolector esta activo:

systemctl status photobioreactor-acquisition

2. Revise eventos recientes:

tail -n 20 /opt/photobioreactor/logs/alarms.csv

3. Genere una condicion de alarma de prueba ajustando temporalmente un umbral desde el dashboard. Por ejemplo, establezca un maximo de temperatura por debajo de la lectura actual para forzar CRITICAL.
4. Espere el siguiente ciclo de adquisicion.
5. Confirme que se registro el evento y llego el mensaje.
6. Restaure el umbral correcto.

Evite hacer esta prueba durante una calibracion real o una corrida experimental critica.

Mensaje enviado

El mensaje tiene este formato:

Photobioreactor alarm: CRITICAL
Sensor: temperature
Value: 31.2
Message: Temperature is above configured range.
Time: 2026-06-27T12:00:00.000Z

El texto se construye en api/notification-service.js. Si mas adelante se necesita un formato distinto, ese es el punto central para modificarlo.

Seguridad recomendada

• Configure API_AUTH_TOKEN en produccion.
• No suba tokens de Telegram al repositorio.
• Use /etc/photobioreactor/notifications.json para secretos en Raspberry Pi.
• Mantenga permisos 600 en el archivo de notificaciones.
• Si el token se expone, regenere el token desde BotFather.
• No publique el dashboard directamente a Internet.

Diagnostico

No llega ningun mensaje

• Verifique Internet en la Raspberry:

curl https://api.telegram.org

• Verifique token y chat con la prueba manual de sendMessage.
• Confirme que enabled y channels.telegram.enabled estan en true.
• Confirme que minSeverity no esta filtrando el evento.
• Confirme que realmente hubo una transicion de alarma en logs/alarms.csv.

El dashboard no permite guardar

• Si API_AUTH_TOKEN esta configurado, debe escribirlo en el campo Token API.
• Revise rate limit si se hicieron muchos cambios seguidos.
• Consulte logs de la API:

journalctl -u photobioreactor-api -f

El bot responde en chat directo pero no en grupo

• Confirme que el bot esta agregado al grupo.
• Use el chatId del grupo, no el chat privado.
• En grupos, el chatId normalmente es negativo.
• Envie un mensaje nuevo al grupo y repita getUpdates.

El token aparece como [configured]

Ese comportamiento es correcto. El backend redacta el secreto cuando el dashboard consulta la configuracion. Para cambiar el token, escriba uno nuevo y guarde. Para conservarlo, deje el campo vacio.

Estado actual de implementacion

Implementado:

• Configuracion persistente en config/notifications.json o NOTIFICATION_CONFIG_FILE.
• Canal Telegram mediante Bot API sendMessage.
• Redaccion de token hacia el frontend.
• Conservacion de token existente desde el dashboard.
• Filtro por severidad minima.
• Integracion con eventos generados por el recolector.

Pendiente de validacion en Raspberry:

• Envio real desde la red donde trabajara el equipo.
• Comportamiento durante desconexiones fisicas de sensores.
• Registro operativo de errores de envio en corridas largas.