# Catalog templates



This document explains how to create catalog templates. See [Sell Products and Services](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/catalogs-overview) to learn more about product catalogs and ways to showcase your products.

Catalog templates are marketing templates that allow you to showcase your product catalog entirely within WhatsApp. Catalog templates display a product thumbnail header image of your choice and custom body text, along with a fixed text header and fixed text sub-header.

When a customer taps the **View catalog** button in a catalog template message, your product catalog appears within WhatsApp.

## Creating catalog templates

### Requirements

You must have [inventory uploaded to Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/upload-inventory) in an e-commerce catalog [connected to your WhatsApp account hierarchy](https://www.facebook.com/business/help/158662536425974).

### Request syntax

Use the [Message Templates API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/message-template-api#post-version-waba-id-message-templates) to create a catalog template. Once your template is approved, you can use the [Messages API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages) to send it in a template message.

```html
curl -X POST "https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '
{
    "name": "<NAME>",
    "language": "<LANGUAGE>",
    "category": "MARKETING",
    "components": [
      {
        "type": "BODY",
        "text": "<BODY_TEXT>",
        "example": {
          "body_text": [
            [
              "<EXAMPLE_BODY_TEXT>"
            ]
          ]
        }
      },
      {
        "type": "FOOTER",
        "text": "<FOOTER_TEXT>"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "CATALOG",
            "text": "View catalog"
          }
        ]
      }
    ]
  }'
```

### Request parameters

| Placeholder | Description | Sample value |
| --- | --- | --- |
| `<BODY_TEXT>`<br><br>_String_ | **Required.**<br><br>Template body text. Variables are supported.<br><br>Maximum 1024 characters. | `Now shop for your favorite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp!` |
| `<EXAMPLE_BODY_TEXT>`<br><br>_String (of an array of strings)_ | **Required if body text uses variables.**<br><br>Sample strings to replace variable placeholders in `<BODY_TEXT>` string.<br><br>Maximum 1024 characters. | `100` |
| `<FOOTER_TEXT>`<br><br>_String_ | **Optional.**<br><br>Template footer text. Variables are supported.<br><br>Maximum 60 characters. | `Best grocery deals on WhatsApp!` |
| `<LANGUAGE>`<br><br>_String_ | **Required.**<br><br>Template [language and locale code](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages). | `en_US` |
| `<NAME>`<br><br>_String_ | **Required.**<br><br>Template name.<br><br>Maximum 512 characters. | `intro_catalog_offer` |

### Example request

```curl
curl 'https://graph.facebook.com/v17.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "intro_catalog_offer",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Now shop for your favorite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp!",
      "example": {
        "body_text": [
          [
            "100",
            "400",
            "3"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Best grocery deals on WhatsApp!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "CATALOG",
          "text": "View catalog"
        }
      ]
    }
  ]
}'
```

### Example response

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

## Sending catalog template messages

You can send approved [catalog templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/catalog-template-messages) in a template message. See [Sell Products and Services](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/catalogs-overview) to learn more about product catalogs and ways to showcase your products.

### Requirements

You must have [inventory uploaded to Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/upload-inventory) in an e-commerce catalog [connected to your WhatsApp account hierarchy](https://www.facebook.com/business/help/158662536425974).

### Request syntax

Use the [Messages API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api#post-version-phone-number-id-messages) to send a catalog template message using a catalog template with an `APPROVED` status.

```html
curl -X POST "https://graph.facebook.com/v19.0/<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<TO>",
    "type": "template",
    "template": {
      "name": "<NAME>",
      "language": {
        "code": "<CODE>"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "<TYPE>",
              "text": "<TEXT>"
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "CATALOG",
          "index": 0,
          "parameters": [
            {
              "type": "action",
              "action": {
                "thumbnail_product_retailer_id": "<THUMBNAIL_PRODUCT_RETAILER_ID>"
              }
            }
          ]
        }
      ]
    }
  }'
```

### Request parameters

| Placeholder | Description | Sample value |
| --- | --- | --- |
| `<CODE>`<br><br>_String_ | **Required.**<br><br>Template [language and locale code](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages). | `en_US` |
| `<NAME>`<br><br>_String_ | **Required.**<br><br>Template name. | `intro_catalog_offer` |
| `<THUMBNAIL_PRODUCT_RETAILER_ID>`<br><br>_String_ | **Optional.**<br><br>Item SKU number. Labeled as Content ID in the Commerce Manager.<br><br>The thumbnail of this item will be used as the message's header image.<br><br>If the `parameters` object is omitted, the product image of the first item in your catalog will be used. | `2lc20305pt` |
| `<TEXT>`<br><br>_String_ | **Required if template uses variables.**<br><br>Template variable. | `100` |
| `<TO>`<br><br>_String_ | **Required unless you use `recipient`.**<br><br>Customer phone number. | `+16505551234` |
| `<BSUID>`<br><br>_String_ | **Optional.**<br><br>WhatsApp user's [business-scoped user ID (BSUID)](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) or parent BSUID. To send to a BSUID instead of a phone number, replace the `to` property with `recipient` and set it to this value. If you include both `to` and `recipient`, `to` is used. See [Send to a BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#send-to-a-bsuid). | `US.13491208655302741918` |
| `<TYPE>`<br><br>_String_ | **Required if template uses variables.**<br><br>Template variable type. | `text` |

### Example request

```curl
curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "intro_catalog_offer",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "100"
          },
          {
            "type": "text",
            "text": "400"
          },
          {
            "type": "text",
            "text": "3"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "CATALOG",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "thumbnail_product_retailer_id": "2lc20305pt"
            }
          }
        ]
      }
    ]
  }
}'
```

### Example response

```json
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+16505551234",
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI5RkEwM0EyODFEQzQ2NDYzQTMA"
    }
  ]
}
```

If you send the message using `recipient`, the `contacts` object returns the BSUID in `input` and `user_id`, and omits `wa_id`. If `recipient` is a parent BSUID, `contacts` contains only `input`. See [Send to a BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#send-to-a-bsuid).

## See also

* [Sell Products and Services](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/catalogs-overview)
* [Catalog Messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/share-products#catalog-messages)