WhatsApp Commerce Suite — Guía de instalación y configuración

Presentación

DataFirefly WhatsApp Commerce Suite convierte WhatsApp en un canal de ventas completo para WooCommerce mediante la Cloud API oficial de Meta. El plugin incluye 4 módulos activables de forma independiente: sincronización del catálogo Meta Commerce, toma de pedido conversacional, recuperación de carrito abandonado y enlace de pago firmado.

Instalación

1. Descarga dfwhatsappcommerce-1.0.0.zip desde tu cuenta de cliente DataFirefly.
2. En wp-admin, ve a Plugins → Añadir nuevo → Subir plugin, selecciona el ZIP y haz clic en Instalar ahora.
3. Activa el plugin. Aparece un nuevo menú WhatsApp en la barra lateral de administración.

En la activación, el plugin crea 5 tablas SQL con prefijo dfwc_ (conversaciones, mensajes, carritos abandonados, log de catálogo, registros) y programa 3 eventos cron: procesamiento de carritos cada 15 minutos, limpieza diaria de registros, y sincronización de catálogo por lotes cada hora.

Requisitos del lado de Meta

Antes de configurar el plugin, reúne estos 5 valores desde Meta Business Suite:

• Phone Number ID — WhatsApp → Configuración de API → tu número
• WhatsApp Business Account ID — visible en la configuración de tu cuenta WhatsApp Business
• Catalog ID — Commerce Manager → tu catálogo → Configuración
• Access Token permanente — crea un usuario del sistema en Business Settings → Users → System Users, otórgale los permisos whatsapp_business_messaging, whatsapp_business_management y catalog_management, luego genera un token sin caducidad
• App Secret — Meta for Developers → tu aplicación → Configuración → Básica

Configuración del plugin

1. Ve a WhatsApp → Ajustes.
2. En la sección Credenciales de la Meta Cloud API, pega los 5 valores obtenidos antes. El campo Webhook Verify Token está pregenerado automáticamente — modifícalo solo si es necesario.
3. Indica el Número de WhatsApp mostrado en formato E.164 sin el signo + (ejemplo: 34612345678). Este número alimenta el botón flotante y los CTA.
4. Activa los módulos deseados en la sección Módulos. Puedes empezar solo con la sincronización del catálogo y activar el resto progresivamente.
5. Guarda.

Configuración del webhook de Meta

El webhook permite que Meta entregue los mensajes entrantes y los estados de entrega a tu sitio.

1. Abre WhatsApp → Panel de control en wp-admin: la Callback URL y el Verify Token se muestran ahí con botones Copiar.
2. En Meta for Developers, abre tu aplicación → WhatsApp → Configuración → Webhook.
3. Pega la Callback URL y el Verify Token, luego haz clic en Verificar y guardar.
4. En la lista de campos, suscríbete a messages.

La Callback URL tiene la forma https://tu-sitio.com/wp-json/dfwc/v1/webhook. Cada petición entrante se valida con firma HMAC SHA-256 contra tu App Secret: las peticiones no firmadas o mal firmadas se rechazan.

Prueba de la conexión

Desde WhatsApp → Panel de control:

• Probar la conexión API — verifica tus credenciales consultando tu Phone Number ID y muestra el número verificado.
• Enviar un mensaje de prueba — introduce un número en formato E.164 sin + y envía un mensaje de texto de prueba.

Módulo 1 — Sincronización del catálogo

Tres modos disponibles en Ajustes:

• Tiempo real — cada creación, modificación, cambio de stock o eliminación de producto se refleja inmediatamente en el catálogo Meta.
• Por lotes — los cambios se acumulan y se envían cada hora en lotes de 50.
• Manual — nada se envía automáticamente; usas el botón de resincronización.

Reglas de mapeo:

• Cada producto recibe un retailer_id de la forma wc_{ID}.
• Los productos variables no se envían tal cual: cada variación se envía individualmente con su propio precio, stock e imagen.
• Los productos sin imagen se omiten (requisito de Meta).
• El filtro dfwc_catalog_product_eligible permite excluir productos por código, y dfwc_catalog_product_data modificar los datos enviados.

La página WhatsApp → Catálogo muestra los contadores de éxito y error, el registro de los últimos 50 eventos, y el botón Iniciar resincronización que reenvía todos los productos elegibles en lotes de 100.

Módulo 2 — Pedido conversacional

El módulo de conversación responde automáticamente a los mensajes entrantes según una máquina de estados: idle → browsing → selecting_qty → reviewing → awaiting_payment, más un estado human_handoff.

Palabras clave reconocidas (francés e inglés en la misma conversación):

• menu o catalogue — muestra la lista interactiva de productos (hasta 30 elementos, conectados al catálogo Meta)
• cart o panier — muestra el contenido del carrito con los botones Pagar / Continuar / Vaciar
• checkout, pay o payer — genera el enlace de pago
• human, humain o aide — transfiere a un asesor (e-mail enviado a la dirección configurada)
• reset o annuler — reinicia la conversación

Cualquier otro texto lanza una búsqueda libre en tus productos. El carrito del cliente se conserva en la conversación y se vincula a su cuenta WooCommerce si su número coincide con un billing_phone existente.

Los mensajes de bienvenida y de respaldo son personalizables en Ajustes. La página WhatsApp → Conversaciones lista todas las conversaciones y permite consultar cada hilo en una vista de tipo WhatsApp Web.

Módulo 3 — Recuperación de carrito abandonado

Funcionamiento:

1. El plugin captura el carrito de los visitantes (sesión WooCommerce + cookie de respaldo de 7 días) y hace obligatorio el campo teléfono en el checkout.
2. Tras el umbral de abandono (60 minutos por defecto), sale el primer recordatorio. Los recordatorios 2 y 3 siguen sus propios retrasos (24h y 72h por defecto, expresados en minutos en Ajustes).
3. Cada recordatorio usa un template HSM de Meta configurado por etapa. Si el template falla, se intenta un mensaje de texto simple como respaldo.
4. El tercer recordatorio puede adjuntar un cupón WooCommerce existente, aplicado automáticamente en el checkout mediante el enlace de recuperación.
5. Cuando el cliente completa su pedido, el carrito se marca como recuperado y los recordatorios se detienen.

Creación de los templates HSM

En Meta Business Suite → WhatsApp Manager → Plantillas de mensaje, crea 3 templates (por ejemplo dfwc_abandoned_cart_1, _2, _3) con:

• Un cuerpo con dos variables: {{1}} = nombre del cliente, {{2}} = importe del carrito
• Un botón de acción de tipo URL con una variable {{1}} al final de la URL, apuntando a https://tu-sitio.com/wp-json/dfwc/v1/recover/{{1}}

Crea cada template en los idiomas de tus clientes: el plugin detecta la locale y envía la versión correcta. Una vez aprobados por Meta, introduce sus nombres en los Ajustes del plugin.

La página WhatsApp → Carritos abandonados muestra el total, los carritos en recordatorio, los recuperados y la tasa de recuperación.

Módulo 4 — Pago y notificaciones

El enlace de pago generado en la conversación es un token firmado HMAC (SHA-256, salt de WordPress + secreto del plugin) que contiene el carrito, la caducidad y el identificador de conversación. Cuando el cliente hace clic:

1. El token se valida y decodifica.
2. El carrito WooCommerce se reconstruye en el servidor.
3. El teléfono del cliente se rellena en el checkout.
4. La URL se limpia con una redirección.

La validez del enlace es configurable (Ajustes → Pago). Un enlace caducado muestra un mensaje de error invitando a pedir uno nuevo por WhatsApp.

Notificaciones automáticas (activables individualmente):

• Pedido confirmado — enviada al pasar a Processing, con número y total.
• Pedido enviado — enviada al pasar a Completed, con el número de seguimiento detectado desde Shipment Tracking, AfterShip o la meta _tracking_number, y un botón CTA de seguimiento.
• Pago fallido — enviada al pasar a Failed, con un botón para reintentar el pago.

Botón flotante y CTA

• Botón flotante — activable en Ajustes, posición en cualquiera de las 4 esquinas, etiqueta personalizable, ocultable. El template templates/frontend/whatsapp-button.php puede sobreescribirse copiándolo en tu-tema/dfwhatsappcommerce/whatsapp-button.php.
• CTA de ficha de producto — botón «Pedir por WhatsApp» bajo el botón de añadir al carrito, con mensaje prerrellenado con el nombre y enlace del producto.
• CTA de carrito — botón «Finalizar por WhatsApp» con el total del carrito.
• CTA de checkout — enlace de ayuda discreto.
• Shortcode — [dfwc_whatsapp_button text="..." message="..."] para colocación manual en cualquier parte.

Los clics en todos estos elementos se envían al dataLayer (prefijo dfwc_) para GA4 / Google Tag Manager.

Registros y solución de problemas

La página WhatsApp → Registros muestra todos los eventos con filtros por nivel (debug → critical) y por canal (api, webhook, catalog, conversation, cart, payment). El nivel de registro y la retención son configurables. Los registros también son visibles en WooCommerce → Estado → Registros bajo las fuentes dfwhatsappcommerce-*.

Problemas frecuentes:

• El webhook no se verifica — comprueba que tu sitio esté en HTTPS con certificado válido, que los enlaces permanentes no estén en modo «Simple», y que el Verify Token pegado en Meta sea idéntico al de los Ajustes.
• Los mensajes entrantes no llegan — comprueba que el campo messages esté suscrito en la configuración del webhook Meta, y que el App Secret sea correcto (una firma inválida rechaza silenciosamente las peticiones — visible en los Registros, canal webhook).
• La sincronización del catálogo falla — comprueba que el token del sistema tenga el permiso catalog_management y que el Catalog ID corresponda al catálogo vinculado a tu cuenta WhatsApp Business.
• Los recordatorios no salen — comprueba que el cron de WordPress funcione (WP Crontrol permite visualizar dfwc_process_abandoned_carts), y que los templates HSM estén aprobados por Meta.

Desinstalación

Desactivar el plugin conserva todos los datos. La eliminación definitiva desde la página Plugins ejecuta uninstall.php: las 5 tablas se eliminan, las opciones y los eventos cron se borran. Los pedidos WooCommerce creados vía WhatsApp nunca se tocan.