twilio/catalog

Twilio/catalog is used to send products or services to your customers. WhatsApp offers 3 ways to send advertise, recommend, and facilitate checkout for items or services you may have for sale. These messages can be sent in and out of session in 3 variations: single product, multi product, and whole catalog messages. Twilio has simplified all of this into 1 content template. Depending on the number of items you send, Twilio will automatically select the appropriate type of WhatsApp Product Message to deliver your message. This removes the need to build and understand WhatsApp's custom logic to choose the type of product message to send.

• View a list of products (multi-product message, catalog)
• View one product (single product message).
• Ask questions about specific products.
• Add products to a cart.
• Send a shopping cart to the business.

WhatsApp

Sends 1 product and information about that product to your customers.

Only available within a 24 hour WA session. 1 product can be sent out of session as part of a multiproduct catalog template but the end user experience will be different. In MPM clicking the message button redirects to a list of products whereas SPM redirects directly to the item.

Single Product Message	Multi-Product Message	Full Catalog
Expand image	Expand image	Expand image
Sends 1 product and information about that product to your customers. Only available within a 24 hour WA session. 1 product can be sent out of session as part of a multiproduct catalog template but the end user experience will be different. In MPM clicking the message button redirects to a list of products whereas SPM redirects directly to the item.	Sends 1 to 30 products and information about those products to your customers. Available in session and as an out of session approve template. 1 product can be sent out of session as part of a multiproduct catalog template but the end user experience will be different. In MPM clicking the message button redirects to a list of products whereas SPM redirects directly to the item.	Sends all product and information about that product to your customers. This functionality must be enabled for your sender

1. Create a Catalog in the Meta Commerce Manager
2. Link the Catalog to your WhatsApp Business Manager
3. Create a content template with Twilio
4. Send the content template This guide will cover the steps required to create a catalog and add items to it in Meta's Commerce Manager if you don't already have one. It will also cover how to create and send your catalog messages for sharing all variations of those templates. Let's dive into how each step works.

1. Navigate to your WhatsApp Business Account (WABA).
   Expand image
2. In your WhatsApp Business Account, click the 3 horizontal lines in the left navigation bar and go to your Commerce Manager.
   Expand image
3. In the Catalogs section, click Add catalog and select the relevant catalog type. You will then be asked to give the catalog a name. Select the catalog use case and once the catalog is created, click "view catalog". * Do not edit the Catalog owner .
   Expand image

1. Next we will add items to the catalog. Click into the catalog.
   Expand image
2. Meta offers multiple ways to upload items. The easiest way to get started is to manually add items in the UI. In addition Meta allows you to add items in more advanced scalable ways. You can upload a sheet using data feeds where you can provide a template to fill out. Partner platforms connect your catalog directly to your Shopify/BigCommerce site. If you choose to do manual upload or data feed, you will be can add a SKU number item ID called content id in the UI. These must be unique values in each catalog. Additionally you will need to add a title, description, availability status, condition of item, price, link to item, link to image of item, and brand of item for each item in the catalog.
3. You will need to take note of the item id in Meta. In Meta's UI it is called 'content id' and in their developer docs and in other locations it is referred to as item id and product retailer id. At Twilio we call it item id. In our webhook it is exposed as product retailer id but we will soon change this to standardize the field.
   Expand image

1. Next go to the WhatsApp Manager. One way to get back here is to navigate back to the Console and click into your WABA ID like in the first step of "Creating your catalog in WABA".
2. Under account tools, go to Catalog to connect your Catalog.
   Expand image
3. The same catalog cannot be used by multiple WhatsApp Business Accounts.

During a 24-hour user-initiated session, template approval is not required by WhatsApp for twilio/catalog templates.

For out of session (business-initiated) catalog templates, you will need to submit the template for approval.

Now let's create your content template, so you can send product messages to your end users. First, find the Catalog ID in your Meta Commerce Manager in the "Catalogs" section. You will need this ID to create your content template with Twilio.

Expand image

We will now cover the various parameters you can use to create your catalog message. To create the actual body of the message you will need to specify body, subtitle, and header to define what the message actually looks like. Thumbnail id which is an item id from the list of items you specify will be needed for multi and full catalog messages to define the cover photo of the message. You will also need to define the items you will send. You can either do this by denoting that you will send the items later, you can define a static list now, or do a combination of the 2. When you define items you will need to use the item id found as content id in the catalog in the Meta Commerce Manager. And if you are defining multiple items you will need to add section titles to organize your items into sections.

Expand image

Expand image

id:

• Type: string
• Required: Yes
• Variable Support: Yes (for in-session) | No (for WA approved templates)
• Description: ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager.

title:

• Type: string
• Required: no (only required for WA MPM)
• Variable Support: yes
• Description: Required for WA MPM. Max 60 characters. Controls the bolded title text above the body of the message.

body:

• Type: string
• Required: no (only required to get template approved by WA)
• Variable Support: yes
• Description: The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.

subtitle:

• Type: string
• Required: no (only required to get template approved by WA)
• Variable Support: yes
• Description: The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.

items:

• Type: array
• Required: no - if dynamic_items is defined, yes - if dynamic_items is not defined
• Variable Support: no
• Description: Array of static items to be sent

dynamic_items:

• Type: array
• Required: no - if items is defined, yes - if items is not defined
• Variable Support: yes
• Description: Rule: It should only have a placeholder. Required for dynamic catalog items. At the time of content creation customers can mention a placeholder eg {{products}}. At the time of sending a message, customers can pass products as variables.

id:

• Type: string
• Required: no
• Variable Support: yes
• Description: Required for Single-Product Messages and Multi-Product Messages. Must be defined in either CatalogItem during create or in the variable for dynamic items at time of send. Unique identifier of the product in a catalog. Maximum 100 characters for both Single-Product and Multi-Product messages.

section_title:

• Type: string
• Required: no
• Variable Support: yes
• Description: Title of the section. Maximum length: 24 characters.

This creates a template that will send a fixed list. Using "thumbnail_item_id", you can define what product's picture is shown on the message. You can also have some items can be fixed for a message and others can be dynamic if you add "dynamic\_items": "{{products}}" in the twilio/catalog definition. If dynamic items is defined in creation, at least 1 additional dynamic item must be added to send. If dynamic items are added, the item with id 48rme2i4po will always be sent first and all items defined in {{products}} at send will follow.

1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
   "friendly_name": "fixedproducts",
6
   "language": "en",
7
   "variables": {"1": "menu_ad", "2": "menu_name"},
8
   "types": {
9
   "twilio/catalog": {
10
     "id": "1017234312776586",
11
     "body": "Hi, check out this menu {{1}}",
12
     "subtitle": "Great deals",
13
     "title": "The Menu: {{2}}",
14
     "thumbnail_item_id": "48rme2i4po",
15
     "items": [ {"id": "48rme2i4po", "section_title": "veggies"}]
16
 }
17
}
18
}'

1
{
2
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
    "date_created": "2024-06-10T22:16:39Z",
4
    "date_updated": "2024-06-10T22:16:39Z",
5
    "friendly_name": "fixedproducts",
6
    "language": "en",
7
    "links": {
8
        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
    },
11
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
    "types": {
13
        "twilio/catalog": {
14
            "body": "Hi, check out this menu {{1}}",
15
            "dynamic_items": null,
16
            "id": "1017234312776586",
17
            "items": [
18
                {
19
                    "description": null,
20
                    "id": "48rme2i4po",
21
                    "media_url": null,
22
                    "name": null,
23
                    "price": null,
24
                    "section_title": "veggies"
25
                }
26
            ],
27
            "subtitle": "Great deals",
28
            "thumbnail_item_id": "48rme2i4po",
29
            "title": "The Menu: {{2}}"
30
        }
31
    },
32
    "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
33
    "variables": {
34
        "1": "menu_ad",
35
        "2": "menu_name"
36
    }
37
}

This will send an end user your entire catalog. Title is prefixed by Meta as: "View {Business's name} Catalog on WhatsApp". No items need to be defined.

1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
   "friendly_name": "Catalog - all products",
6
   "language": "en",
7
   "variables": {"1": "menu_title", "2": "menu_name"},
8
   "types": {
9
    "twilio/catalog": {
10
      "id": "1017234312776586",
11
      "title": "The Menu: {{1}}",
12
      "body": "Hi, check out this menu {{2}}",
13
      "subtitle": "Great deals",
14
      "thumbnail_item_id": "48rme2i4po"
15
      }
16
    }
17
  }'

1
{
2
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
    "date_created": "2024-06-10T22:02:53Z",
4
    "date_updated": "2024-06-10T22:02:53Z",
5
    "friendly_name": "Catalog - all products",
6
    "language": "en",
7
    "links": {
8
        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
    },
11
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
    "types": {
13
        "twilio/catalog": {
14
            "body": "Hi, check out this menu {{2}}",
15
            "dynamic_items": null,
16
            "id": "1017234312776586",
17
            "items": null,
18
            "subtitle": "Great deals",
19
            "thumbnail_item_id": "48rme2i4po",
20
            "title": "The Menu: {{1}}"
21
        }
22
    },
23
    "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
24
    "variables": {
25
        "1": "menu_title",
26
        "2": "menu_name"
27
    }
28
}

If you plan to send a variable number of items, we recommend you send a template

If you are only sending one item, Meta considers this a "single-product message" and only supports it in-session. When sending 1 product out of session, the message the end user receives will be slightly different. If you are sending within a 24 hour session, we recommend creating one template with all fields set as variables. You can then dynamically define each field at send time so you can minimize the number of templates you need to create.

1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
   "friendly_name": "dynamicproducts",
6
   "language": "en",
7
   "variables": {"1": "Hi, check out this menu menu_name", "2": "footer text"},
8
   "types": {
9
   "twilio/catalog": {
10
     "id": "1017234312776586",
11
     "title": "The Menu: {{1}}",
12
     "body": "{{2}}",
13
     "subtitle": "{{3}}",
14
     "dynamic_items": "{{products}}"
15
 }
16
}
17
}'

1
{
2
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
    "date_created": "2024-06-10T22:25:37Z",
4
    "date_updated": "2024-06-10T22:25:37Z",
5
    "friendly_name": "dynamicproducts",
6
    "language": "en",
7
    "links": {
8
        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
    },
11
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
    "types": {
13
        "twilio/catalog": {
14
            "body": "{{2}}",
15
            "dynamic_items": "{{products}}",
16
            "id": "1017234312776586",
17
            "items": null,
18
            "subtitle": "{{3}}",
19
            "thumbnail_item_id": null,
20
            "title": "The Menu: {{1}}"
21
        }
22
    },
23
    "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
24
    "variables": {
25
        "1": "Hi, check out this menu menu_name",
26
        "2": "footer text"
27
    }
28
}

You can also approve your product messages as approved WA templates to initiate a session if you want. Approval is the same as all other templates.

You are able to prefix items by specifying product id's at time of creation if you want. If you choose to send dynamic items, you will need the item's SKU item ID, known in the WABA as the Content ID. You will not need to set this product id at time of template creation but will need it at time of send.

The following code sample sends the Product Message with dynamically set items defined above.

Expand image