docs: manual de alta para cada cliente nuevo

Que pedirle al taller, que hace el cliente y que hacemos nosotros para poner en marcha el bot. Recoge los tropiezos del alta de Taller Beldor: el SMS de verificacion, el token cortado y los placeholders sin reemplazar en el .env. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-10-19 16:33:39 -03:00
parent 8fcd0fbf77
commit 95ccf695c1
1 changed files with 125 additions and 0 deletions
@@ -0,0 +1,125 @@
 # 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.