From 95ccf695c1eb268d356ffacfeb0ce961105d5172 Mon Sep 17 00:00:00 2001 From: Beldor Date: Mon, 19 Oct 2026 16:33:39 -0300 Subject: [PATCH] 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 --- docs/alta-cliente.md | 125 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/alta-cliente.md diff --git a/docs/alta-cliente.md b/docs/alta-cliente.md new file mode 100644 index 0000000..6e3820f --- /dev/null +++ b/docs/alta-cliente.md @@ -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:///api/whatsapp/webhook?hub.mode=subscribe&hub.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/?fields=display_phone_number,verified_name" \ + -H "Authorization: Bearer " + ``` +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.