Single-product message templates

Updated: Nov 4, 2025 This document describes single-product message (SPM) templates, their uses, and how to use them. SPM templates are marketing templates that allow you to present a single product from your ecommerce catalog, accompanied by a product image, product title, and product price (all pulled from your product within your catalog), along with customizable body text, optional footer text, and an interactive View button.

WhatsApp users can tap the button to see details about the product, and can add or remove the product from the WhatsApp shopping cart:

If the WhatsApp user adds the product to the carts and submits an order, you will be notified via webhook and the user will see that an order has been placed:

Users who place an order are also able to use the View details button to see information about the order:

Limitations

Customers must be using WhatsApp v2.22.24 or greater. Message forwarding is disabled for SPM templates.

Catalogs

You must have an ecommerce product catalog, with inventory, connected to your WhatsApp Business Account. See the Cloud API Commerce guide to learn more about connecting a catalog to your account.

Webhooks

When a customer adds one or more products to their cart and submits an order, an order messages webhook is triggered, describing the order.

Creating SPM templates

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to create an SPM template.

Request syntax

curl 'https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;WHATSAPP_BUSINESS_ACCOUNT_ID&gt;/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer &lt;ACCESS_TOKEN&gt;' \
-d '
\{
  "name": "&lt;TEMPLATE_NAME&gt;",
  "language": "&lt;TEMPLATE_LANGUAGE&gt;",
  "category": "marketing",
  "parameter_format": "&lt;PARAMETER_FORMAT&gt;",
  "components": [\
    {\
      "type": "header",\
      "format": "product"\
    },\
    {\
      "type": "body",\
      "text": "&lt;CARD_BODY_TEXT&gt;",\
\
      <!-- Example parameter values required, if body text contains parameters -->\
      "example": {\
        "body_text_named_params": [\
          {\
            "param_name": "&lt;PARAMETER_NAME&gt;",\
            "example": "&lt;PARAMETER_EXAMPLE&gt;"\
          },\
          <!-- Additional parameters would follow -->\
        ]\
      }\
\
    },\
    {\
      "type": "footer",\
      "text": "&lt;CARD_FOOTER_TEXT&gt;"\
    },\
    {\
      "type": "buttons",\
      "buttons": [\
        {\
          "type": "spm",\
          "text": "View"\
        }\
      ]\
    }\
  ]
}'

Request parameters

Placeholder	Description	Example Value
`<ACCESS_TOKEN>` String	Required. Access token.	`EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD`
`<API_VERSION>` String	Optional. API version. If omitted, defaults to the newest API version available to your app.	`v23.0`
`<CARD_BODY_TEXT>` String	Required. Card body text. Supports variables. Maximum 160 characters.	`Use code {{1}} to get {{2}} off our newest succulent!`
`<CARD_FOOTER_TEXT>` String	Optional. Footer text. Maximum 60 characters.	`September 30, 2024`
`<PARAMETER_NAME>` String	Required if body text uses parameters. Example parameter value string(s). You must include a parameter example for each parameter in your body text.	`25OFF`
`<PARAMETER_FORMAT>` String	Optional. Parameter format. Value can be: `named` `positional` If the `parameter_format` property is omitted, the template will use positional formatting.	`Lucky Shrub: Your gateway to succulents!`
`<TEMPLATE_LANGUAGE>` String	Required. Template language and locale code.	`en_US`
`<TEMPLATE_NAME>` String	Required. Template name. Maximum 512 characters.	`abandoned_cart_offer`
`<WHATSAPP_BUSINESS_ACCOUNT_ID>` String	Required. WhatsApp Business Account ID.	`546151681022936`

Example request

curl 'https://graph.facebook.com/v24.0/161311403722088/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
\{
  "name": "spm_template_named_params",
  "language": "en_US",
  "category": "marketing",
  "parameter_format": "named",
  "components": [\
    {\
      "type": "header",\
      "format": "product"\
    },\
    {\
      "type": "body",\
      "text": "Use code {{code}} to get {{percent}} off our newest succulent!",\
      "example": {\
        "body_text_named_params": [\
          {\
            "param_name": "code",\
            "example": "15OFF"\
          },\
          {\
            "param_name": "percent",\
            "example": "15%"\
          }\
        ]\
      }\
    },\
    {\
      "type": "footer",\
      "text": "Offer ends September 22, 2024"\
    },\
    {\
      "type": "buttons",\
      "buttons": [\
        {\
          "type": "spm",\
          "text": "View"\
        }\
      ]\
    }\
  ]
}'

Sending single-product template messages

Request syntax

Use the POST /<BUSINESS_PHONE_NUMBER_ID>/messages endpoint to send an SPM template message.

curl 'https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;BUSINESS_PHONE_NUMBER_ID&gt;/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer &lt;ACCESS_TOKEN&gt;' \
-d '
\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "&lt;WHATSAPP_USER_PHONE_NUMBER&gt;",
  "type": "template",
  "template": {
    "name": "&lt;TEMPLATE_NAME&gt;",
    "language": {
      "code": "&lt;TEMPLATE_LANGUAGE&gt;"
    },
    "components": [\
      {\
        "type": "header",\
        "parameters": [\
          {\
            "type": "product",\
            "product": {\
              "product_retailer_id": "&lt;PRODUCT_ID&gt;",\
              "catalog_id": "&lt;CATALOG_ID&gt;"\
            }\
          }\
        ]\
      },\
      {\
        "type": "body",\
        "parameters": [\
          {\
            "type": "text",\
            "parameter_name": "&lt;PARAMETER_NAME&gt;",\
            "text": "&lt;PARAMETER_VALUE&gt;"\
          },\
          <!-- Additional parameter values would follow, if required by template -->\
        ]\
      }\
    ]
  }
}'

Request parameters

Placeholder	Description	Example Value
`<ACCESS_TOKEN>` String	Required. Access token	`EAAAN...`
`<API_VERSION>` String	Optional. API version. If omitted, defaults to the newest API version available to your app.	`v23.0`
`<BUSINESS_PHONE_NUMBER_ID>` String	Required. WhatsApp business phone number ID.	`106540352242922`
`<CATALOG_ID>` String	Required. ID of connected ecommerce catalog containing the product.	`194836987003835`
`<PARAMETER_NAME>` String	Required if template uses one or more named parameters. Name of named parameter.	`code`
`<PARAMETER_VALUE>` String	Required if template uses one or more named parameters. Named parameter value.	`10OFF`
`<PRODUCT_ID>` String	Required. Product ID.	`nqryix03ez`
`<TEMPLATE_LANGUAGE>` String	Required. Template language and locale code.	`en_US`
`<TEMPLATE_NAME>` String	Required. Template name. Maximum 512 characters.	`spm_template_named_params`
`<WHATSAPP_USER_PHONE_NUMBER>` String	Required. WhatsApp user phone number.	`+16505551234`

Example request

This example sends an approved template named “spm_template_named_params” which injects parameters (a discount code and the percentage discounted) into the template body, and which includes a footer. The product image is pulled from the catalog and displayed in the message header.

curl 'https://graph.facebook.com/v24.0/179776755229976/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505551234",
  "type": "template",
  "template": {
    "name": "spm_template_named_params",
    "language": {
      "code": "en_US"
    },
    "components": [\
      {\
        "type": "header",\
        "parameters": [\
          {\
            "type": "product",\
            "product": {\
              "product_retailer_id": "nqryix03ez",\
              "catalog_id": "194836987003835"\
            }\
          }\
        ]\
      },\
      {\
        "type": "body",\
        "parameters": [\
          {\
            "type": "text",\
            "parameter_name": "code",\
            "text": "25OFF"\
          },\
          {\
            "type": "text",\
            "parameter_name": "percent",\
            "text": "25%"\
          }\
        ]\
      }\
    ]
  }
}'

Did you find this page helpful? Thumbs up icon

ON THIS PAGE Limitations Catalogs Webhooks Creating SPM templates Request syntax Request parameters Example request Sending single-product template messages Request syntax Request parameters Example request

Overview

Getting started

Business setup

Messages

Templates

Embedded signup

Flows

Calling

Groups

Payments

Catalogs

Marketing messages

Click to WhatsApp ads

Solution providers

API reference

Pricing

Policies

Other

Support

Spm templates

Single-product message templates

Limitations

Catalogs

Webhooks

Creating SPM templates

Request syntax

Request parameters

Example request

Sending single-product template messages

Request syntax

Request parameters

Example request

​Single-product message templates

​Limitations

​Catalogs

​Webhooks

​Creating SPM templates

​Request syntax

​Request parameters

​Example request

​Sending single-product template messages

​Request syntax

​Request parameters

​Example request

Single-product message templates

Limitations

Catalogs

Webhooks

Creating SPM templates

Request syntax

Request parameters

Example request

Sending single-product template messages

Request syntax

Request parameters

Example request