# 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

```text
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:

```text
/newbot
```

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

```text
photobioreactor_alerts_bot
```

5. BotFather entregara un token con formato parecido a:

```text
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:

```text
hola
```

3. En una terminal, consulte las actualizaciones:

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

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

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

En este ejemplo, el `chatId` es:

```text
123456789
```

### Grupo de Telegram

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

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

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

```text
-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:

```text
/etc/photobioreactor/notifications.json
```

La ruta se define en:

```text
NOTIFICATION_CONFIG_FILE=/etc/photobioreactor/notifications.json
```

Ejemplo de configuracion:

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

Proteja el archivo porque contiene secretos:

```bash
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:

```bash
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:

```bash
systemctl status photobioreactor-acquisition
```

2. Revise eventos recientes:

```bash
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:

```text
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:

```bash
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:

```bash
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.