Multi-Product Message Templates

This document describes multi-product message (MPM) templates, their uses, and how to create them.

MPM templates can be used to open marketing conversations. They allow you to showcase up to 30 products from your ecommerce catalog, organized in up to 10 sections, in a single message.

Customers can browse products and sections within the message, view details for each product, add and remove products from their cart, and submit their cart to place an order. Orders are then sent to you via a webhook.

See our help center article About Multi-product message templates on WhatsApp for common use cases and tips on how to make the most of MPM templates.

Requirements

In order to create and use MPM templates you must have an ecommerce product catalog, with inventory, connected to your WhatsApp Business Account. See the Cloud API Commerce guide, or the On-Premises API Commerce guide.

Limitations

• Customers must be using WhatsApp v2.22.24 or greater.
• MPM templates cannot be forwarded to other customers.

Creating MPM Templates

You can create MPM templates using the WhatsApp Business Account > Message Templates endpoint or the WhatsApp Manager > Account tools > Message templates panel. Once your template is approved, you can use Cloud API or On-Premises API to send it in a template message.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Parameters

Components

The components value must be an array of objects that describes each component that makes up the template. MPM templates must have the following components:

• a single header component
• a single body component
• a single footer component (optional)
• a single MPM button component

[
  {
    "type": "HEADER",
    "format": "TEXT",
    "text": "<HEADER_TEXT>",
    
    /* Example required if header uses a variable */
    "example": {
      "header_text": [
        "<HEADER_EXAMPLE_TEXT>"
      ]
    }
  },
  {
    "type": "BODY",
    "text": "<BODY_TEXT>",

    /* Example required if body uses variables */
​​    "example": {
      "body_text": [
        [
          "<BODY_EXAMPLE_TEXT>"
        ]
      ]
    }
  },
  {
    "type": "FOOTER",
    "text": "<FOOTER_TEXT>"
  },
  {
    "type":"BUTTONS",
    "buttons": [
      {
        "type": "MPM",
        "text": "View items"
      }
    ]
  }
]

Properties

Response

Upon success, the API will respond with:

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "MARKETING"
}

Response Contents

Sample Request

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "abandoned_cart",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Forget something, {{1}}?",
      "example": {
        "header_text": [
          "Pablo"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Looks like you left these items in your cart, still interested? Use code {{1}} to get 10% off!",
      "example": {
        "body_text": [
          [
            "10OFF"
          ]
        ]
      }
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "MPM",
          "text": "View items"
        }
      ]
    }
  ]
}'

Sample Response

{
  "id": "546151681022936",
  "status": "PENDING",
  "category": "MARKETING"
}

Sending MPM Templates

Use Cloud API or On-Premises API to send an MPM template once it has been approved:

• Cloud API: Sending Multi-Product Message Templates
• On-Premises API: Sending Message Templates

Webhooks

When a customer adds one or more products to their cart and submits an order, we will send you a webhook that describes the order.

Webhook Syntax

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ENTRY.ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<NAME>"
                },
                "wa_id": "<WA_ID>"
              }
            ],
            "messages": [
              {
                "from": "<FROM>",
                "id": "<MESSAGES.ID>",
                "timestamp": "<TIMESTAMP>",
                "type": "order",
                "order": {
                  "catalog_id": "<CATALOG_ID>",
                  "product_items": [
                    {
                      "product_retailer_id": "<PRODUCT_RETAILER_ID>",
                      "quantity": <QUANTITY>,
                      "item_price": <ITEM_PRICE>,
                      "currency": "<CURRENCY>"
                    }
                  ]
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Webhook Contents

Sample Webhook

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTMxNzA1QzNENEI4ODY0OTY2MAA=",
                "timestamp": "1683223069",
                "type": "order",
                "order": {
                  "catalog_id": "1537566713439863",
                  "product_items": [
                    {
                      "product_retailer_id": "n6k6x0y7oe",
                      "quantity": 1,
                      "item_price": 99.99,
                      "currency": "USD"
                    }
                  ]
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}