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

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

   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:

  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.