docs: lo aprendido en el alta de Taller Beldor

Cuatro preparativos previos (telefono confirmado, nombre del negocio que
coincida con el sitio, sitio con contenido publico, politica de
privacidad), el costo de reintentar a ciegas, la segunda suscripcion
subscribed_apps, la diferencia entre verificar y conectar un numero, y
la revision de cuenta que bloquea el registro.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docker-compose.yml

@@ -33,6 +33,13 @@ services:
       GOOGLE_CLIENT_EMAIL: ${GOOGLE_CLIENT_EMAIL}
       GOOGLE_SHEET_ID: ${GOOGLE_SHEET_ID}
       GOOGLE_PRIVATE_KEY: ${GOOGLE_PRIVATE_KEY}
+      # Bot de WhatsApp. Sin estas cuatro el .env de produccion no llega al
+      # contenedor: los envios avisan que falta el token y el webhook contesta
+      # 403 porque no puede validar la firma. Ver docs/whatsapp.md.
+      WHATSAPP_PHONE_NUMBER_ID: ${WHATSAPP_PHONE_NUMBER_ID}
+      WHATSAPP_TOKEN: ${WHATSAPP_TOKEN}
+      WHATSAPP_VERIFY_TOKEN: ${WHATSAPP_VERIFY_TOKEN}
+      WHATSAPP_APP_SECRET: ${WHATSAPP_APP_SECRET}
     ports:
       - "3004:3000"
 

docs/alta-cliente.md

@@ -0,0 +1,237 @@
+# 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: **varios días**. La configuración activa lleva una tarde, pero Meta mete
+esperas que no se pueden apurar: la revisión de la cuenta, la aprobación del Display Name y
+la liberación del número de WhatsApp. Planificar el alta con margen, nunca para el mismo día.
+
+> **Lo que más caro sale es equivocarse en el orden.** Varios pasos dependen de otros de
+> forma no evidente, y reintentarlos deja basura que después bloquea. Las secciones están en
+> el orden en que hay que hacerlas.
+
+---
+
+## 0. Antes de tocar nada: los cuatro preparativos
+
+Estos cuatro se resuelven **antes** de abrir el panel de Meta. Saltearlos es lo que nos costó
+una jornada entera en el alta de Taller Beldor.
+
+1. **El teléfono del titular tiene que estar confirmado en el Centro de cuentas.**
+   No alcanza con tenerlo a mano: Meta exige que ya esté confirmado antes de dejar verificar
+   la cuenta de desarrollador, y el mensaje de error no lo dice así.
+2. **El nombre del negocio y el del sitio web tienen que coincidir.**
+   Meta compara el nombre declarado contra el `<title>` del sitio que se declara como
+   respaldo. Si no coinciden, rechaza el alta con el error de política `#2494070`, que no
+   explica la causa.
+3. **El sitio tiene que servir contenido público.** Una raíz que redirige al login no sirve:
+   el verificador de Meta ve una pantalla vacía. Hace falta al menos una home con el nombre
+   del taller y qué hace.
+4. **Una política de privacidad en una URL pública.** Es requisito para publicar la app, y
+   sin publicar la app Meta no entrega datos de producción al webhook.
+
+---
+
+## 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 **nombre de la app no puede contener "WhatsApp", "Facebook" ni "Insta"**: Meta los
+   rechaza. Es un nombre interno, no el que ven los clientes.
+
+> **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.
+
+### Reintentar tiene costo: cada intento fallido deja una WABA huérfana
+
+El asistente de alta **crea la cuenta de WhatsApp Business antes de validar el formulario**.
+Si el alta falla después de ese punto, la cuenta queda igual, vacía y contando para el cupo.
+Un portfolio sin verificar admite pocas, así que a los pocos reintentos aparece el error
+`#2494067` ("Se alcanzó el límite de cuentas de WhatsApp Business").
+
+En el alta de Taller Beldor quedaron **seis cuentas, cinco de ellas basura**, y hubo que
+borrarlas a mano para poder seguir. Conclusión práctica: **no reintentar a ciegas**. Si el
+alta falla, averiguar la causa antes del siguiente intento, y revisar después en
+Business Suite → Cuentas de WhatsApp si quedaron cuentas vacías para borrar.
+
+### El campo "Sitio web" es obligatorio
+
+Figura como opcional en algunas pantallas pero el formulario no deja avanzar sin él. Y el
+sitio que se declare es el que Meta va a comparar contra el nombre del negocio (ver punto 0).
+
+## 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: **Paso 2 → Configurar webhooks**, con la Callback URL del
+   cliente y el mismo verify token. Meta suscribe **`messages`** solo al guardar; verificar
+   que el aviso aparezca, porque sin esa suscripción no llega ningún mensaje.
+6. **Suscribir la app a la WABA.** Es una segunda suscripción, distinta de la anterior y
+   fácil de pasar por alto: el campo `messages` se suscribe a nivel app, pero además la app
+   tiene que estar asociada a esa cuenta de WhatsApp. Si falta, Meta recibe los mensajes y
+   los entrega a su propia app de pruebas, no al webhook del cliente.
+
+   ```bash
+   curl -X POST "https://graph.facebook.com/v21.0/<WABA_ID>/subscribed_apps" \
+     -H "Authorization: Bearer <TOKEN>"
+   ```
+
+   Verificar que el nombre de la app aparezca al consultar ese mismo endpoint con GET.
+   **Ojo:** si se crea una WABA nueva, hay que rehacer esta suscripción — es por WABA.
+7. Cargar los datos del taller: jefes mecánicos, tipos de servicio y horarios.
+8. Probar punta a punta, mirando `docker logs -f taller_app`.
+   El endpoint **solo escribe en el log cuando algo falla**, así que un mensaje que entra
+   bien es silencioso: la confirmación real es que aparezcan filas en
+   `MensajeWhatsappProcesado` y `ConversacionWhatsapp`.
+
+> **Los números de prueba de Meta no sirven para probar el bot.** El que regala el panel
+> queda en `status: PENDING`, no se le puede escribir, no envía (`133010 Account not
+> registered`) y no acepta `/register`. Sirve para los ejemplos de curl de la documentación,
+> nada más. La prueba punta a punta necesita el número real ya conectado.
+
+## 5. Migrar el número real del taller
+
+El último paso, el que más fricción genera con el cliente y donde está la espera más larga.
+
+- 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.
+- Después de liberarlo, Meta tarda **hasta 3 minutos** en actualizar el estado. Si al
+  cargarlo dice que sigue registrado, esperar y reintentar: no falló el borrado.
+
+### Verificar el número NO es lo mismo que conectarlo
+
+Son dos cosas distintas y el número tiene un campo para cada una:
+
+| Campo | Qué significa | Cómo se consigue |
+|---|---|---|
+| `code_verification_status: VERIFIED` | El cliente probó que la línea es suya | Código por SMS o llamada |
+| `status: CONNECTED` | El número está operativo sobre Cloud API | Lo aprovisiona Meta |
+
+**Un número en `PENDING` no envía ni recibe, y ni siquiera existe en WhatsApp**: si se
+intenta escribirle desde otro teléfono, WhatsApp solo ofrece "Invitar". Entre que se borra la
+cuenta común y que Meta lo conecta, el número queda en tierra de nadie. Es el estado normal
+durante la espera, no un error de configuración.
+
+### La revisión de la cuenta bloquea todo, y no se puede apurar
+
+Mientras la cuenta de WhatsApp Business figure **`Pending review`**, Meta deshabilita el
+botón "Registrar" del Paso 2 con este mensaje:
+
+> "Number registration and webhook subscription are unavailable for this account now."
+
+No hay nada que configurar mientras tanto. Es el cuello de botella real del alta: **planificar
+el alta de cada cliente contando con esta espera**, y no prometerle una fecha hasta que la
+cuenta salga de revisión.
+
+- El **Display Name** necesita aprobación, pero suele salir sin revisión
+  (`name_status: AVAILABLE_WITHOUT_REVIEW`) si coincide con el nombre del negocio.
+- 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.
+
+## 7. Manejo de credenciales
+
+Vale para todos los clientes y no es negociable:
+
+- **Las credenciales no viajan por chat, mail ni WhatsApp.** Van de la pantalla de Meta al
+  `.env` del servidor, directo. Un token pegado en una conversación queda registrado ahí para
+  siempre y hay que revocarlo y regenerarlo.
+- **El token de System User se muestra una sola vez.** Tener el `.env` abierto antes.
+- Para verificar sin exponer valores, chequear **largo y prefijo** en vez de imprimirlos:
+
+  ```bash
+  docker exec <contenedor> sh -c 'v=$(printenv WHATSAPP_TOKEN); echo "${#v} chars"'
+  ```
+
+- **Cuidado con los mensajes de error de la Graph API**: cuando un token es inválido, la
+  respuesta lo devuelve completo en el campo `message`. No volcar esas respuestas crudas en
+  un log compartido ni en una conversación.
+- El PIN de verificación en dos pasos del número lo elige el cliente y conviene que lo anote:
+  Meta lo pide si alguna vez hay que re-registrar el número.

docs/whatsapp.md

@@ -35,7 +35,9 @@ puede confiar en el payload).
    Para el token definitivo: Business Settings → System Users → crear usuario → Generate Token
    con permisos `whatsapp_business_messaging` y `whatsapp_business_management`.
 4. **App → Settings → Basic → App Secret** → `WHATSAPP_APP_SECRET`.
-5. Cargar las 4 variables en el `.env` de producción y redeployar.
+5. Cargar las 4 variables en el `.env` de producción (`/home/proyecto/taller_automotriz/.env`,
+   al lado del `docker-compose.yml`, que es de donde compose las interpola) y levantar de nuevo
+   con `docker compose up -d`. Un `git push` no alcanza: el `.env` no está en el repo.
 6. **WhatsApp → Configuration → Webhook**:
    - Callback URL: `https://taller.beldo.duckdns.org/api/whatsapp/webhook`
    - Verify token: el mismo `WHATSAPP_VERIFY_TOKEN`

src/app/layout.tsx

@@ -14,8 +14,8 @@ const geistMono = localFont({
 });
 
 export const metadata: Metadata = {
-  title: "Taller MG",
+  title: "Taller Beldor",
-  description: "Sistema de turnos - Taller MG",
+  description: "Sistema de turnos - Taller Beldor",
 };
 
 export default function RootLayout({

src/lib/whatsapp-bot.ts

@@ -183,7 +183,7 @@ async function guardar(
   return resp;
 }
 
-const BIENVENIDA = "¡Hola! 👋 Soy el asistente del *Taller MG*. Te ayudo a sacar un turno.";
+const BIENVENIDA = "¡Hola! 👋 Soy el asistente del *Taller Beldor*. Te ayudo a sacar un turno.";
 
 // ── Entrada principal ──
 export async function procesarMensaje(telefonoRaw: string, textoRaw: string): Promise<RespuestaBot[]> {