taller_automotriz/docs/alta-cliente.md

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; 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:

   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:

   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.