# Notificaciones Multicanal — Configuración y Templates

Referencia extendida de la skill `notificaciones-multicanal`. Contiene
configuración completa de canales, formatos de mensaje, rate limiting,
templates y flujo de diagnóstico.

---

## Configuración completa de canales (config.json)

```jsonc
// ~/.claude/notifications/config.json
{
  "version": "2",
  "defaults": {
    "canal_primario": "desktop",
    "prioridad_minima": "normal",
    "idioma": "es-MX",
    "zona_horaria": "America/Mexico_City"
  },

  "canales": {
    "desktop": {
      "habilitado": true,
      "motor": "auto",
      "icono": "~/.claude/assets/swl-icon.png",
      "sonido": true,
      "duracion_ms": 5000,
      "persistente_si_prioridad": "urgente"
    },

    "telegram": {
      "habilitado": true,
      "bot_token": "${TELEGRAM_BOT_TOKEN}",
      "chat_id": "${TELEGRAM_CHAT_ID}",
      "parse_mode": "HTML",
      "disable_preview": true,
      "timeout_segundos": 10
    },

    "whatsapp": {
      "habilitado": false,
      "proveedor": "twilio",
      "account_sid": "${TWILIO_ACCOUNT_SID}",
      "auth_token": "${TWILIO_AUTH_TOKEN}",
      "from_number": "${TWILIO_WHATSAPP_FROM}",
      "to_number": "${WHATSAPP_TO_NUMBER}"
    },

    "email": {
      "habilitado": false,
      "smtp_host": "${SMTP_HOST}",
      "smtp_port": 587,
      "smtp_user": "${SMTP_USER}",
      "smtp_password": "${SMTP_PASSWORD}",
      "from": "swl-notifier@empresa.com",
      "to": ["dev@empresa.com"],
      "asunto_prefijo": "[SWL]"
    },

    "webhook": {
      "habilitado": false,
      "url": "${WEBHOOK_URL}",
      "metodo": "POST",
      "headers": {
        "Authorization": "Bearer ${WEBHOOK_TOKEN}",
        "Content-Type": "application/json"
      },
      "timeout_segundos": 5,
      "reintentos": 2
    }
  }
}
```

---

## Formato de Mensaje por Canal

### Desktop

Limitaciones: título 64 chars, cuerpo 256 chars, sin formato enriquecido.

```json
{
  "canal": "desktop",
  "titulo": "Fase 2 completada — SWL",
  "cuerpo": "8/8 tareas ejecutadas. 0 errores. Listo para revision.",
  "accion_click": "abrir_terminal"
}
```

### Telegram

Soporte completo de HTML. Máximo 4096 chars por mensaje.

```html
<b>Fase 2 Completada</b>
<code>Proyecto: sigaf-backend</code>

<b>Resumen:</b>
- 8 tareas ejecutadas
- 0 errores criticos
- 2 advertencias menores

<b>Artefactos generados:</b>
- <code>PLAN.md</code> — Plan actualizado
- <code>RESUMEN.md</code> — Resumen de ejecucion

<b>Accion requerida:</b>
Revisa los artefactos y responde con: <code>aprobar</code> o <code>ajustar: [feedback]</code>
```

### WhatsApp

Sin HTML. Soporte de *negrita* y _cursiva_ con markdown simple.

```
*SWL — Fase 2 Completada*

Proyecto: sigaf-backend
Tareas: 8/8

Artefactos listos para revision:
- PLAN.md
- RESUMEN.md

Responde APROBAR o AJUSTAR para continuar.
```

### Email

```
Asunto: [SWL] Fase 2 Completada — sigaf-backend

Proyecto:   sigaf-backend
Fase:       2 de 4
Estado:     COMPLETADA
Fecha/hora: 2024-03-20 14:32 CST

TAREAS EJECUTADAS (8/8):
  - Setup de base de datos
  - Modelos SQLAlchemy
  - Endpoints FastAPI
  ... (ver RESUMEN.md adjunto)

ARTEFACTOS ADJUNTOS:
  - RESUMEN.md
  - VERIFICACION.md

ACCION REQUERIDA:
  Revisar artefactos y aprobar para continuar con Fase 3.
  Responder a este email con: APROBAR o AJUSTAR [feedback]

---
SWL Software Engineering System v2
```

### Webhook

Payload JSON normalizado:

```json
{
  "version": "2",
  "evento": {
    "id": "evt-20240320-1432-001",
    "tipo": "checkpoint",
    "subtipo": "human-verify",
    "timestamp": "2024-03-20T20:32:00Z",
    "proyecto": "sigaf-backend",
    "fase": 2,
    "prioridad": "normal"
  },
  "mensaje": {
    "titulo": "Fase 2 Completada",
    "cuerpo": "8/8 tareas ejecutadas sin errores.",
    "accion_requerida": true,
    "opciones": ["aprobar", "ajustar", "rechazar"]
  },
  "metadatos": {
    "agente": "ejecutor",
    "duracion_fase_ms": 84500,
    "artefactos": ["RESUMEN.md", "VERIFICACION.md"]
  }
}
```

---

## Rate Limiting y Supresión

### Configuración de rate limiting

```jsonc
{
  "rate_limiting": {
    "ventana_segundos": 300,
    "maximo_por_ventana": {
      "desktop":  10,
      "telegram": 20,
      "whatsapp":  5,
      "email":     3,
      "webhook":  50
    },
    "excepcion_prioridades": ["critico", "urgente"]
  }
}
```

### Supresión por horario (No molestar)

```jsonc
{
  "no_molestar": {
    "habilitado": true,
    "inicio": "22:00",
    "fin": "08:00",
    "zona_horaria": "America/Mexico_City",
    "excepciones": ["critico"],
    "acumulacion": {
      "habilitada": true,
      "resumen_en": "08:00",
      "canal_resumen": "telegram"
    }
  }
}
```

### Supresión de duplicados

```jsonc
{
  "deduplicacion": {
    "habilitada": true,
    "ventana_segundos": 60,
    "clave": "evento.tipo + evento.proyecto + mensaje.titulo"
  }
}
```

---

## Templates de Mensajes

Los templates usan sintaxis `{{variable}}` con soporte de condicionales simples:

```
# templates/checkpoint-verify.telegram.html
<b>{{icono_estado}} {{titulo}}</b>
{{#si proyecto}}<code>Proyecto: {{proyecto}}</code>{{/si}}

<b>Resumen:</b>
{{resumen}}

{{#si artefactos}}
<b>Artefactos:</b>
{{#cada artefactos}}- <code>{{nombre}}</code>{{/cada}}
{{/si}}

{{#si accion_requerida}}
<b>Accion requerida:</b>
{{accion_descripcion}}
{{/si}}
```

### Variables disponibles en todos los templates

| Variable | Descripción |
|----------|-------------|
| `{{proyecto}}` | Nombre del proyecto actual |
| `{{fase}}` | Número de fase actual |
| `{{agente}}` | Agente que emite la notificación |
| `{{timestamp}}` | Fecha/hora local formateada |
| `{{titulo}}` | Título del evento |
| `{{resumen}}` | Cuerpo principal del evento |
| `{{prioridad}}` | Nivel de prioridad del evento |

---

## Flujo de Diagnóstico

Si una notificación no llega:

```
1. Verificar que el broker este activo:
   claude-notifications-go status

2. Verificar variables de entorno:
   echo $TELEGRAM_BOT_TOKEN | head -c 10

3. Probar canal especifico:
   claude-notifications-go test --canal telegram

4. Revisar log de errores:
   claude-notifications-go log --nivel error --ultimas 10

5. Verificar rate limiting:
   claude-notifications-go stats --canal telegram

6. Verificar horario No Molestar:
   claude-notifications-go no-molestar --estado
```
