Skip to main content

​
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

PlaceholderDescriptionExample Value
&lt;ACCESS_TOKEN&gt;
String		Required.
Access token.		EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD
&lt;API_VERSION&gt;
String		Optional.
API version. If omitted, defaults to the newest API version available to your app.		v23.0
&lt;CARD_BODY_TEXT&gt;
String		Required.
Card body text. Supports variables.
Maximum 160 characters.		Use code {{1}} to get {{2}} off our newest succulent!
&lt;CARD_FOOTER_TEXT&gt;
String		Optional.
Footer text.
Maximum 60 characters.		September 30, 2024
&lt;PARAMETER_NAME&gt;
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
&lt;PARAMETER_FORMAT&gt;
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!
&lt;TEMPLATE_LANGUAGE&gt;
String		Required.
Template language and locale code.		en_US
&lt;TEMPLATE_NAME&gt;
String		Required.
Template name.
Maximum 512 characters.		abandoned_cart_offer
&lt;WHATSAPP_BUSINESS_ACCOUNT_ID&gt;
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

PlaceholderDescriptionExample Value
&lt;ACCESS_TOKEN&gt;
String		Required.
Access token		EAAAN...
&lt;API_VERSION&gt;
String		Optional.
API version. If omitted, defaults to the newest API version available to your app.		v23.0
&lt;BUSINESS_PHONE_NUMBER_ID&gt;
String		Required.
WhatsApp business phone number ID.		106540352242922
&lt;CATALOG_ID&gt;
String		Required.
ID of connected ecommerce catalog containing the product.		194836987003835
&lt;PARAMETER_NAME&gt;
String		Required if template uses one or more named parameters.
Name of named parameter.		code
&lt;PARAMETER_VALUE&gt;
String		Required if template uses one or more named parameters.
Named parameter value.		10OFF
&lt;PRODUCT_ID&gt;
String		Required.
Product ID.		nqryix03ez
&lt;TEMPLATE_LANGUAGE&gt;
String		Required.
Template language and locale code.		en_US
&lt;TEMPLATE_NAME&gt;
String		Required.
Template name.
Maximum 512 characters.		spm_template_named_params
&lt;WHATSAPP_USER_PHONE_NUMBER&gt;
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 Thumbs down 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