# kq-whatsapp-agent — Sam

Agente de WhatsApp con IA para atención y calificación de prospectos de Kings & Queens English Learning.

## Contexto

- **Canal:** WhatsApp Business (+5492915658257)
- **Persona:** Sam — asistente virtual de Kings & Queens
- **Modelo:** GPT-4o
- **Orquestación:** n8n self-hosted (`n8n.edd-os.com.ar`)
- **CRM:** Chatwoot account 4 (`chat.bah-ia.com.ar/app/accounts/4/`)

## Flujo

```
WhatsApp (+5492915658257)
  → Evolution API [Kings-and-Queens]
  → Chatwoot account 4 (inbox Kings-and-Queens)
  → webhook message_created
  → n8n: kq-chatwoot-agent
  → Sam (GPT-4o-mini + Whisper)
    ├─ tool: qualify_student
    └─ tool: escalate_to_ale
  → POST Chatwoot API → WhatsApp

Si cualquier workflow falla:
  → n8n: agent-error-notifier
  → WhatsApp personal de Edelmar (+5492915708124)
```

## Soporte multimedia

- **Audio:** transcripción automática via OpenAI Whisper antes de pasar al agente
- **Imagen:** detectada y pasada como contexto al agente (describe contenido)

## Regla dura de errores

- Sam nunca debe mostrar al cliente errores técnicos, nombres de workflows, n8n, APIs, webhooks, tokens, stack traces, tools ni nodos internos.
- Si una herramienta o automatización falla, el cliente recibe un mensaje humano y genérico.
- La falla se reporta internamente mediante `agent-error-notifier`.
- El celular personal de fallback para alertas operativas es `+5492915708124`; si se define `ADMIN_ALERT_WHATSAPP` al ejecutar `create_agent.py`, se usa ese valor.
- Las alertas operativas salen por la instancia Evolution `Bah-IA` por defecto (`+5492915107422`). Si se define `ADMIN_ALERT_EVOLUTION_INSTANCE`, se usa ese valor.

## Credenciales de integración

| Variable | Valor |
|---|---|
| Chatwoot URL (interno Docker) | `http://chatwoot-web:3000` |
| Chatwoot Account ID | `4` |
| Chatwoot API Token | `vqkZ6e57n5BcN1QDBQkSqsFq` |
| Evolution API URL | `https://wa.bah-ia.com.ar` |
| Evolution Instance | `Kings-and-Queens` |
| Número escalamiento (Ale) | `+5492914227793` |

## IDs de Workflows en n8n

| Workflow | ID |
|---|---|
| agent-error-notifier | `agentErrorKQ001` |
| kq-tool-qualify-student | `IOR5NJw4jjgN4Efn` |
| kq-tool-escalate-to-ale | `K3sm7VWSaTqbLbTv` |
| kq-tool-analyze-image | `ds2jEUbN03t39n4c` |
| kq-tool-transcribe-audio | `8jcBAMIq7SQkXYcK` |
| kq-chatwoot-agent | `StL4PRyRwgNOyc4U` |

## Deploy

```bash
cd /home/edd/Proyectos/Edd-OS/projects/kings-and-queens/whatsapp-agent/workflows
N8N_API_KEY="eyJ..." python3 create_agent.py
```

Luego en n8n UI:
1. Asignar credencial OpenAI al nodo "GPT-4o-mini"
2. Activar los 3 workflows principales
3. Chatwoot account 4 → Settings → Integrations → Webhooks
   - URL: `https://n8n.edd-os.com.ar/webhook/kq-chatwoot`
   - Event: `message_created`

## Handoff humano

Para que Ale tome control de una conversación:
1. Ir a `chat.bah-ia.com.ar` → account 4 (Kings & Queens)
2. Abrir la conversación
3. Asignársela a sí misma → Sam deja de responder mientras haya agente asignado