WhatsApp Catalog API: diseñe el flujo tras tocar el producto

WhatsApp Catalog API puede presentar un producto dentro de una conversación, pero no crea por sí sola una operación de pedido fiable. La pregunta útil empieza después del toque sobre el producto: ¿qué identificador acompaña al cliente, quién se hace cargo de la consulta, cuándo se comprueba el stock, qué convierte un pedido entrante en trabajo de fulfillment y cómo se recupera el equipo cuando la realidad no coincide con el catálogo?

Esta guía responde a esa cuestión operativa. Toma los objetos actuales de mensajes de catálogo y webhook de Meta como límite técnico y los convierte en un flujo que un equipo de comercio puede probar. La regla central es sencilla: trate el catálogo como una superficie para descubrir productos y cada webhook como evidencia de intención, no como prueba de que el stock está reservado, el pago ha finalizado o el fulfillment ha comenzado.

Qué proporciona realmente WhatsApp Catalog API

La colección oficial de Meta documenta dos formatos interactivos útiles. Un mensaje de un solo producto utiliza type: interactive, el subtipo product, un catalog_id y un product_retailer_id. Un mensaje multiproducto emplea el subtipo product_list, un catalog_id y secciones con artículos identificados mediante product_retailer_id (solicitud de un producto, solicitud multiproducto).

Meta también documenta plantillas de catálogo con un botón CATALOG. Estas plantillas abren el catálogo de la empresa en WhatsApp, pero no sustituyen los sistemas de producto, inventario, pedidos o pagos (solicitud de plantilla de catálogo). Elija el formato según la tarea del cliente, no según cuál resulte más llamativo.

La entrada es igual de importante. Una consulta puede llegar cuando alguien responde a un mensaje de producto o elige “Message Business” desde su página de detalle. El contexto del webhook puede incluir referred_product.catalog_id y referred_product.product_retailer_id (webhook de consulta de producto). Un objeto de pedido puede contener catalog_id, product_items, cantidad, precio, moneda y el product_retailer_id de cada artículo (referencia del objeto messages). Esos campos identifican la selección; sus sistemas todavía deben decidir qué prometer y qué hacer después.

Cree un contrato operativo desde catálogo hasta pedido

Un flujo fiable empieza con un único contrato escrito entre marketing, atención al cliente, operaciones comerciales e ingeniería. Debe definir el significado y responsable de cinco registros:

• Cliente — wa_id, teléfono o contact_uuid interno: Mantener unidas identidad e historia de conversación
• Catálogo — catalog_id: Identificar la fuente del producto enviado
• Producto — product_retailer_id: Vincular el artículo de WhatsApp con una SKU estable
• Interacción — ID del mensaje saliente y del webhook entrante: Reconstruir la secuencia y eliminar duplicados
• Trabajo — ID de consulta o pedido, estado y responsable: Mover la intención por validación, recuperación y cierre

No haga que un estado signifique varias cosas. “Pedido recibido” no debe equivaler a “pagado”, “reservado” o “enviado”. Un modelo mínimo útil es received → validating → reserved → confirmed → fulfilled, con salidas explícitas como needs_customer, out_of_stock, cancelled y failed. Si otro sistema posee el pago o fulfillment, guarde su referencia junto al registro de mensajería en lugar de fingir que WhatsApp es el sistema de registro.

Use siete etapas después del toque sobre el producto

1. Compruebe la elegibilidad antes de enviar. El contacto debe poder recibir el mensaje previsto, el producto debe estar activo, el retailer ID debe resolver una única SKU actual y el formato debe encajar con la tarea. Un mensaje de un producto suele ser más claro cuando la conversación ya identifica el artículo. Una lista pequeña sirve para comparar opciones relacionadas. Una plantilla de catálogo solo encaja para reabrir el descubrimiento cuando plantilla y destinatario son elegibles.

2. Registre lo enviado. Guarde cliente, catalog_id, todos los product_retailer_id, ID de mensaje, idioma, una instantánea del precio cuando sea relevante y la campaña o flujo de origen. Ese rastro permite responder después qué precio vio el cliente y por qué se ofreció ese artículo.

3. Clasifique la respuesta sin perder contexto. La consulta debe entrar en una cola con catálogo y producto referidos ya adjuntos. Incluso el texto libre necesita el mensaje padre cuando esté disponible. No obligue al agente a preguntar qué producto quería el cliente si el webhook ya lo identificó.

4. Valide antes de prometer. Resuelva el retailer ID contra el sistema de producto actual. Compruebe si se vende, precio, moneda, stock o capacidad, reglas de entrega o recogida y cualquier variante que el mensaje no capturó. Así un catálogo desactualizado se convierte en una excepción controlada, no en una promesa rota.

5. Reserve y confirme de forma deliberada. Si la empresa reserva stock, cree la reserva en el sistema que lo controla y asígnele vencimiento. Solo entonces indique qué se guarda, durante cuánto tiempo y qué acción completa la compra. Si no se puede reservar, dígalo claramente y no utilice lenguaje que implique certeza.

6. Trate el webhook de pedido como solicitud de procesamiento. Valide artículo, cantidad, moneda y total actual, deduplique el webhook y cree o actualice el pedido en el sistema comercial. Envíe los descuadres a una cola de excepciones con responsable humano. El payload del pedido no prueba por sí solo que el pago se liquidó o el fulfillment físico ocurrió.

7. Cierre el ciclo. Escriba el resultado final en la cronología: confirmado, sustituido, cancelado, recogido, enviado o fallido. Notifique al cliente por una ruta de mensajería elegible, mantenga al responsable y registre por qué hubo sustitución o cancelación.

Un ejemplo realista: recogida en un vivero

Un cliente pregunta por una planta de romero en maceta de dos litros. El equipo envía un mensaje de un producto cuyo product_retailer_id corresponde a herb-rosemary-2l. Cuando responde, el webhook identifica el mismo producto. El flujo vincula la conversación al contacto correcto y la dirige a la cola de recogida.

Antes de prometer nada, el servicio de inventario comprueba la SKU exacta en la tienda solicitada. Si existe, el sistema crea una reserva de 90 minutos y el agente confirma tienda, cantidad, precio y vencimiento. Si el cliente envía un carrito de catálogo, el manejador vuelve a validar el artículo, deduplica el webhook y abre una tarea de recogida. La entrega solo termina cuando el sistema operativo de la tienda registra el traspaso.

Si el catálogo está desactualizado y no queda la maceta de dos litros, el flujo no la sustituye en silencio por otra pequeña. Marca out_of_stock, propone una alternativa concreta solo después de comprobarla y mantiene visible la selección original. El valor no es automatizar más, sino crear una promesa clara y recuperable.

Elija el formato según el coste de decisión

Use un mensaje de un producto cuando el cliente ya lo ha nombrado, un agente continúa una consulta precisa o un artículo recomendado necesita un siguiente paso claro. Reduce el esfuerzo de comparación y facilita interpretar el contexto del producto referido.

Use un mensaje multiproducto cuando el cliente deba comparar una selección pequeña con una restricción significativa: repuestos compatibles, tres tallas disponibles o una colección breve para un presupuesto conocido. No convierta cada sección en un volcado de la tienda. Más opciones aumentan la posibilidad de que precio, stock o responsabilidad cambien antes de responder.

Use una plantilla de catálogo cuando una plantilla conforme a políticas sea la forma correcta de reabrir el descubrimiento. Tras el toque siguen haciendo falta el mismo mapeo de identificadores, control de elegibilidad, responsable, validación de inventario y ruta de excepción. La plantilla cambia la entrada, no el contrato operativo.

Diseñe controles de fallo antes del lanzamiento

El mayor riesgo es un product_retailer_id inestable. Trátelo como clave de integración duradera, no como etiqueta visible. Si el comercio cambia sus SKU internas, utilice un mapeo o migración explícitos; nunca reutilice un identificador antiguo para otro producto.

Haga idempotente el procesamiento de webhooks. Guarde el identificador del evento o mensaje y permita una entrega repetida segura. Productos irresolubles, cantidades no válidas, monedas discordantes, contactos ausentes y tiempos de espera en sistemas posteriores deben tener estados de excepción con nombre. Cada estado necesita cola, responsable, objetivo de respuesta y mensaje permitido al cliente.

Diseñe también para los límites de la ventana de conversación. La página actual para desarrolladores de DripTell indica que un envío de producto puede devolver 422 cuando la ventana de atención de 24 horas está cerrada (API para desarrolladores). El flujo de producción necesita una plantilla elegible o una decisión humana, no reintentos ciegos.

Por último, separe éxito de transporte y éxito de negocio. Un mensaje entregado puede no generar consulta. Un pedido puede fallar la validación de inventario. Un pedido confirmado puede no recogerse. Paneles y alertas deben conservar esas diferencias.

Mida el recorrido, no solo el volumen de mensajes

Las métricas útiles siguen la transición: mensaje a consulta, tiempo hasta un responsable nominal, porcentaje con retailer ID resoluble, éxito de validación, reservas creadas y vencidas, excepciones por motivo, tiempo desde pedido hasta confirmación y recogida o fulfillment completados. Segmente por formato, catálogo, familia de producto, idioma y origen del flujo.

No fije un benchmark arbitrario antes de observar una línea base limpia. Demuestre primero que los eventos están completos y deduplicados; después busque dónde se pierde intención cualificada. Una tasa de consulta menor puede ser válida si un mensaje preciso genera menos solicitudes, pero mejor ajustadas. Un gran número de pedidos no es saludable si crecen sustituciones, cancelaciones o reservas no recogidas.

Lleve el flujo a DripTell

Las capacidades publicadas de DripTell para WhatsApp incluyen catálogos comerciales, mensajes de producto, bandeja compartida, enrutamiento, contexto del cliente, notas y seguimiento (canal de WhatsApp). Su documentación muestra /api/v1/send/product para uno o varios productos con catalog_id, product_retailer_id o products y phone o contact_uuid; también documenta pedidos de carritos en el historial de comercio de WhatsApp (API para desarrolladores).

El recorrido práctico es: conservar la clave estable en el sistema comercial de origen, enviar el mensaje adecuado, guardar su contexto con el contacto, dirigir la respuesta a la bandeja compartida y usar automatización solo donde entradas y fallos sean explícitos. Coincidencias ambiguas, conflictos de stock, cambios de precio, sustituciones y excepciones de fulfillment deben tener responsable humano.

Lance con un conjunto probatorio de diez casos

Antes de ampliar, pruebe: un producto válido; una sección multiproducto válida; una consulta; un carrito con cantidad dos; un webhook duplicado; un retailer ID desconocido; precio o moneda obsoletos; falta de stock después de seleccionar; ventana de servicio cerrada; y timeout del sistema de pedidos. En cada caso confirme mensaje al cliente, identificadores almacenados, responsable, transición, reintentos y evidencia final de cierre.

La decisión de lanzar depende de que el equipo pueda explicar y recuperar cada caso, no de que el happy path parezca pulido. Si desea contrastar un recorrido real con los límites de mensajería, bandeja y automatización de DripTell, reserve una demostración del flujo con el mapa de SKU, responsables de excepciones y sistema de fulfillment a la vista.