Carritos del catálogo

¿Programás con IA? Conectala a tu cuenta por MCP: revisa tu configuración, crea webhooks y plantillas con tu confirmación y te escribe el código. Ver cómo →

Cuando un cliente arma un carrito con el catálogo de WhatsApp del negocio y lo envía, te llega un message.received con data.message.type: "order" y el objeto order de Meta tal cual, sin aplanar: catalog_id (el catálogo), text (el comentario que escribió con el carrito; viene "" si no escribió nada: el campo está, vacío) y product_items[], uno por producto, con product_retailer_id (el id del producto en el catálogo), quantity, item_price (precio unitario) y currency.

Un producto sin precio llega con item_price: 0 y currency: "USD", aunque el resto del catálogo esté en pesos o en otra moneda. No se distingue de un producto gratis: tratá el 0 como «a cotizar» e ignorá currency en ese caso.

Con convivencia los carritos llegan igual. El catálogo se maneja desde la app de WhatsApp Business: Meta no deja administrarlo por API para este tipo de negocio (su error dice «SMB business type»).

# Nothing to call: this is what WAIA Connect POSTs to your webhook for a cart.
# {
#   "id": "evt_7f3a1b2c9d4e5f6a7b8c9d0e1f2a3b4c",
#   "type": "message.received",
#   "version": "1",
#   "createdAt": "2026-10-13T01:43:06.000Z",
#   "connection": { "id": "conn_4eede070e5a84d1590bdce2ea1d837bc", "phoneNumber": "+5493510000000", "externalId": "almacen-sur" },
#   "sequence": 12346,
#   "data": {
#     "message": {
#       "from": "5493511234567",
#       "id": "wamid.HBgL…",
#       "timestamp": "1791855786",
#       "type": "order",
#       "order": {
#         "catalog_id": "100200300400500",
#         "text": "¿Me lo mandan el sábado?",
#         "product_items": [
#           { "product_retailer_id": "yerba-1kg", "quantity": 2, "item_price": 4500, "currency": "ARS" },
#           { "product_retailer_id": "mate-calabaza", "quantity": 1, "item_price": 0, "currency": "USD" }
#         ]
#       }
#     },
#     "contacts": [ { "wa_id": "5493511234567", "profile": { "name": "Ana" } } ]
#   }
# }

# List the items of a saved body (item_price 0 = no price in the catalog → to be quoted):
jq -r '.data.message.order.product_items[]
  | "\(.product_retailer_id) x\(.quantity) " + (if .item_price == 0 then "to be quoted" else "\(.item_price) \(.currency)" end)' body.json

// Inside your webhook handler, after verifying the signature.
const evt = req.body;
if (evt.type === "message.received" && evt.data.message.type === "order") {
  const order = evt.data.message.order;
  const items = order.product_items.map(i => ({
    sku: i.product_retailer_id,
    qty: i.quantity,
    // 0 = the product has no price in the catalog: to be quoted (ignore currency)
    unitPrice: i.item_price === 0 ? null : i.item_price,
    currency: i.item_price === 0 ? null : i.currency
  }));
  const comment = order.text || null; // "" when the customer wrote nothing
  await createOrder(evt.connection.externalId, evt.data.message.from, items, comment); // your code
}

<?php
// Inside your webhook handler, after verifying the signature.
$evt = json_decode(file_get_contents("php://input"), true);
$msg = $evt["data"]["message"] ?? [];
if ($evt["type"] === "message.received" && ($msg["type"] ?? "") === "order") {
  $items = [];
  foreach ($msg["order"]["product_items"] as $i) {
    $quote = $i["item_price"] == 0; // no price in the catalog: to be quoted (ignore currency)
    $items[] = [
      "sku" => $i["product_retailer_id"],
      "qty" => $i["quantity"],
      "unitPrice" => $quote ? null : $i["item_price"],
      "currency" => $quote ? null : $i["currency"],
    ];
  }
  $comment = $msg["order"]["text"] !== "" ? $msg["order"]["text"] : null; // "" = no comment
  create_order($evt["connection"]["externalId"], $msg["from"], $items, $comment); // your code
}

# Inside your webhook handler, after verifying the signature.
evt = request.get_json()
msg = evt["data"].get("message", {})
if evt["type"] == "message.received" and msg.get("type") == "order":
    order = msg["order"]
    items = [
        {
            "sku": i["product_retailer_id"],
            "qty": i["quantity"],
            # 0 = the product has no price in the catalog: to be quoted (ignore currency)
            "unit_price": None if i["item_price"] == 0 else i["item_price"],
            "currency": None if i["item_price"] == 0 else i["currency"],
        }
        for i in order["product_items"]
    ]
    comment = order["text"] or None  # "" when the customer wrote nothing
    create_order(evt["connection"]["externalId"], msg["from"], items, comment)  # your code

Mandar productos o el catálogo por /v1 no está disponible hoy: POST /v1/messages acepta texto, plantillas y media.

Un producto que el negocio manda desde la app del teléfono te llega como message.echo (origin: "device") con type: "interactive" e interactive.type: "product". El resto de interactive lo arma Meta: leelo sin dar nada por seguro.

Un mensaje que Meta no entrega por la API llega como message.received con type: "unsupported" y el errors[] de Meta (por ejemplo 131051), que dice por qué. No trae contenido para leer.

Deduplicá como cualquier mensaje: por el id del sobre (evt_…) o por data.message.id.