# Alta de un cliente nuevo

Qué hay que pedirle a cada taller y qué hacemos nosotros, para poner en marcha el bot de
reservas por WhatsApp. El detalle técnico de las piezas está en [whatsapp.md](whatsapp.md);
acá está el orden operativo y quién hace cada cosa.

Cada cliente necesita **su propia** cuenta de Meta, su propia app y su propio número.
Nada se comparte entre clientes: ni el token, ni el App Secret, ni el número.
`Taller Beldor` es nuestro ambiente de pruebas y no sirve como cuenta productiva de nadie.

Tiempo realista: **una tarde** si el cliente tiene todo a mano, **varios días** si hay que
esperar la aprobación del Display Name o liberar el número de WhatsApp.

---

## 1. Lo que le pedimos al cliente antes de empezar

Conviene mandarle esta lista completa de entrada, porque casi todo depende de él.

| Qué | Para qué | Cuidado |
|---|---|---|
| Quién va a ser **titular** de la cuenta de Meta | Todo cuelga de esa cuenta | Si es el dueño, mejor; si es un empleado y se va, se complica |
| **Cuenta de Facebook** de esa persona, con sesión iniciada | Es la puerta de entrada a todo | — |
| **Celular con SMS** para verificar esa cuenta | Meta exige verificar la cuenta de desarrollador | **El número tiene que estar confirmado en el Centro de cuentas ANTES de empezar** |
| **Nombre público exacto** del taller | Nombre del portfolio comercial y base del Display Name | Sin caracteres especiales |
| **Email del negocio** | Contacto del portfolio y de la app | Tiene que poder recibir el mail de verificación |
| **Número de WhatsApp** que va a atender | Es el número del bot | **No puede estar activo en WhatsApp normal ni Business** (ver punto 5) |
| **Jefes mecánicos** con nombre | El bot los ofrece como botones | Más de 3 → los primeros 3 son botón, el resto se elige por número |
| **Tipos de servicio** y duración | El bot los ofrece después del mecánico | Pueden ser globales o propios de cada jefe |
| **Horarios de atención** | Cálculo de los turnos disponibles | — |

## 2. Cuentas de Meta — lo hace el cliente, nosotros guiamos

Son actos que quedan a nombre del cliente: aceptan condiciones legales y crean cuentas.
**Nosotros no los hacemos por él**, aunque estemos compartiendo pantalla.

1. **Confirmar el teléfono** en el Centro de cuentas → Perfiles y datos personales →
   Información de contacto → Agregar número → **Confirmar número** con el código del SMS.
2. **Portfolio comercial** en `business.facebook.com`: nombre del negocio, su nombre, email.
3. **Cuenta de desarrollador** en `developers.facebook.com` → "Empezar". Cuatro pasos:
   Register (acepta condiciones) → Verify account (el SMS) → Contact info → About you.
4. **Crear la app**: tipo Business, caso de uso **"Conectarte con los clientes a través de
   WhatsApp"**, vinculada al portfolio del paso 2.

> **El SMS es el punto donde más veces se traba el alta.** Si no llega: verificar que el
> número ya esté confirmado en el Centro de cuentas (es un SMS distinto del de la cuenta de
> desarrollador), revisar la bandeja de spam del teléfono, y **no reintentar muchas veces
> seguidas** — Meta deja de entregar los códigos por un rato sin avisar. Si pasó eso,
> esperar unas horas y pedir uno solo.

## 3. Credenciales — las saca el cliente, nosotros no las tocamos

Las cuatro variables del `.env`. **Nunca pasan por chat, mail ni WhatsApp**: el cliente las
copia de la pantalla de Meta y las pega directo en el `.env` del servidor, o nos da acceso
al servidor y las carga él ahí.

| Variable | De dónde sale | Forma esperada |
|---|---|---|
| `WHATSAPP_PHONE_NUMBER_ID` | Caso de uso WhatsApp → Paso 1 "Pruébalo" | Numérico, ~16 dígitos. **No es el teléfono** |
| `WHATSAPP_TOKEN` | Business Settings → Usuarios del sistema → Generar token | **Empieza con `EAA`**, ~200 chars |
| `WHATSAPP_VERIFY_TOKEN` | Lo inventamos nosotros | Alfanumérico, sin símbolos ni espacios |
| `WHATSAPP_APP_SECRET` | App → Configuración → Básica → "Mostrar" | **32 caracteres hexadecimales** |

**System user** (de donde sale el token):

- Crear uno por cliente, por ejemplo `taller-bot`, rol Employee.
- Asignarle **dos activos**: la app (permiso *Desarrollar app*) y la cuenta de WhatsApp
  (permisos *Mensajes* y *Números de teléfono — ver y administrar*).
- Generar token con caducidad **Nunca** y los permisos `whatsapp_business_messaging` y
  `whatsapp_business_management`.
- **El token se muestra una sola vez.** Tener el `.env` abierto antes de apretar el botón.

Errores que ya nos pasaron y conviene chequear:

- Token **cortado al copiar**: si no empieza con `EAA`, está incompleto.
- Placeholders sin reemplazar: que no queden `<...>` en el `.env`.
- `APP_SECRET` que no tiene 32 hex: quedó truncado.
- Sin `APP_SECRET` correcto, **el webhook rechaza todo con 403** y no entra ningún mensaje.

## 4. Lo que hacemos nosotros

1. Desplegar la app para ese cliente con su dominio propio y certificado válido.
   Meta **exige HTTPS** para el webhook.
2. Cargar las 4 variables en el `.env` de ese despliegue y `docker compose up -d`.
   El `.env` no está en el repo: un `git push` no lo toca.
3. Verificar el webhook **antes** de darlo de alta en Meta:

   ```bash
   curl "https://<dominio-del-cliente>/api/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=<VERIFY_TOKEN>&hub.challenge=12345"
   ```

   Tiene que devolver exactamente `12345` en texto plano. Si devuelve 403, la variable no
   llegó al contenedor.
4. Verificar que el token funciona contra la Graph API:

   ```bash
   curl "https://graph.facebook.com/v21.0/<PHONE_NUMBER_ID>?fields=display_phone_number,verified_name" \
     -H "Authorization: Bearer <TOKEN>"
   ```
5. Dar de alta el webhook en Meta: **WhatsApp → Configuration → Webhook**, con la Callback
   URL del cliente, el mismo verify token, y **suscribir el campo `messages`**.
   Sin esa suscripción no llega ningún mensaje.
6. Cargar los datos del taller: jefes mecánicos, tipos de servicio y horarios.
7. Probar punta a punta con el número de prueba gratis de Meta, mirando
   `docker logs -f taller_app`.

## 5. Migrar el número real del taller

El último paso, y el que más fricción genera con el cliente.

- El número **no puede estar activo en la app de WhatsApp normal o Business**. Hay que
  **borrar esa cuenta** antes de migrarlo a Cloud API. Se pierde el historial de chats.
- Avisarle al cliente con tiempo: si el taller venía atendiendo por ese número, va a querer
  elegir el momento.
- El **Display Name** necesita aprobación de Meta. Suele salir rápido, pero puede demorar.
- La **Business Verification** se saltea mientras el cliente esté abajo de 1000 usuarios
  únicos cada 24hs. Para un taller eso es muchísimo, así que en la práctica no aplica.

## 6. Costos a aclarar antes de vender

- El flujo del bot ocurre **dentro de la ventana de 24hs que abre el cliente final**, así que
  **no usa plantillas aprobadas y no tiene costo por conversación**.
- Si en algún momento se quisiera que el taller **inicie** la conversación (recordatorios de
  turno, por ejemplo), eso **sí** requiere plantillas aprobadas y **sí** tiene costo.
  Hoy el bot no lo hace.