Quickstarts

WhatsApp product messages enable you to share products with your customers, allow your customers to ask questions about specific products and order. Currently, the following product messages are supported:

Single Product Message: an interactive message with a single product item from your business inventory. The product is displayed in a Product Detail Page (PDP) format
Multi-Product Message: an interactive message with up to 30 product items from your business inventory.
Inbound Text Message: an inbound text message associated to a specific product. It can be used by your customers to ask questions about your products.
Order Message: represents an order placed by your customer after receiving a single or multi-product message

Before sending Single or Multi-Product Messages, it's necessary:

To know the catalog ID and the product IDs you want to use to send messages. If you don't know either the catalog ID or product IDs, please refer to the section How to find my catalog and products?.
Make sure your catalog is connected to your WhatsApp Business Account. At the moment, only one catalog can be connected per WhatsApp Business Account.

Sending a Single Product Message

In order to send a Single Product message, you must perform the following HTTP request to Conversations API. The following example uses the endpoint POST /v1/send, however, you can also use the other endpoints for sending messages, please check the Conversations API reference for details about the request.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey {your-access-key}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "content": {
    "interactive": {
      "type": "product",
      "action": {
        "catalog_id": "1004272927097129",
        "product_retailer_id": "e86qq6z9hx"
      },
      "body": {
        "text": "Would you like to buy the MessageBird Pro Plan?"
      }
    }
  },
  "to": "+31600000000",
  "type": "interactive",
  "from": "0181d0bf46c5444aae0309f822b35ba6"
}'

type must be interactive
content.interactive.type must be product
content.interactive.action.catalog_id must be set to your Facebook product catalog ID
content.interactive.action.product_retailer_id must be the product ID in the Facebook product catalog
content.interactive.body.text is optional and may contain a text message
to must contain a valid WhatsApp phone number of the recipient
from must contain a valid and active WhatsApp channel

The message in your customer's WhatsApp app will look like the following:

When clicking in "View", this is what your customer will see:

Sending a Multi-Product Message

In order to send a Multi-Product message, you must perform the following HTTP request to Conversations API. The following example uses the endpoint POST /v1/send, however, you can also use the other endpoints for sending messages, please check the Conversations API reference for details about the request.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey {your-access-key}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "content": {
    "interactive": {
      "body": {
        "text": "Would you like to know more about Plans & Pricing?"
      },
      "type": "product_list",
      "header": {
        "type": "text",
        "text": "MessageBird Pricing"
      },
      "action": {
        "catalog_id": "1004272927097129",
        "sections": [
          {
            "title": "For small companies",
            "product_items": [
              {
                "product_retailer_id": "e86qq6z9hx"
              }
            ]
          },
          {
            "title": "For medium companies",
            "product_items": [
              {
                "product_retailer_id": "0srfued6bt"
              }
            ]
          }
        ]
      }
    }
  },
  "to": "+31600000000",
  "type": "interactive",
  "from": "0181d0bf46c5444aae0309f822b35ba6"
}'

type must be interactive
content.interactive.type must be product_list
content.interactive.action.catalog_id must be set to your Facebook product catalog ID
content.interactive.header is required for multi-product messages
content.interactive.header.type must be text for multi-product messages
content.interactive.header.text must be set for multi-product messages
content.interactive.action.sections contains an array of WhatsAppInteractiveSection, every section has a title and the products within
content.interactive.action.sections[].title sets the section title
content.interactive.action.sections[].product_items contains an array of WhatsAppInteractiveProduct
content.interactive.action.sections[].product_items[].product_retailer_id must have the product ID

The message in your customer's WhatsApp app will look like the following:

When clicking in "View items", this is what your customer will see:

Handling customer questions

Your customers will be able to ask questions about specific products by replying product messages.

The message above will be available in Conversations API as a received message with type whatsappText as illustrated below.

{
  "id": "f4195680a362416b9b3a721cb68d86cc",
  "conversationId": "01b6a227e1ba48bf976d70eb24d0dd58",
  "platform": "whatsapp",
  "to": "+31600000000",
  "from": "+31600000000",
  "channelId": "0181d0bb46c5449aae0309f822b35ba5",
  "type": "whatsappText",
  "content": {
    "whatsappText": {
      "text": {
        "body": "Looks amazing! What are the available payment methods?"
      },
      "context": {
        "from": "+31600000000",
        "referred_product": {
          "catalog_id": "1004272927097129",
          "product_retailer_id": "e86qq6z9hx"
        }
      }
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-01-18T15:08:36.646299029Z",
  "updatedDatetime": "2022-01-18T15:08:35Z"
}

The field content.whatsappText.text.body contains the customer question
The field content.whatsappText.context.referred_product.catalog_id contains the Facebook Catalog ID of the product which the customer is referring to
The field content.whatsappText.context.referred_product.product_retailer_id contains the Facebook Product ID of the product which the customer is referring to

Handling customer orders

Like any shopping app, your customers will be able to add products to their shopping cart, and, once they are done, they can send an order message with an optional text message.

Once they've ordered, the order message is displayed like the following in their WhatsApp app.

And the order message is available through Conversations API as a received message with type whatsappOrder.

{
  "id": "d1803742ff474ffbb9ee3aa8e14c69ab",
  "conversationId": "01b6a227e1ba48bf976d70eb24d0dd58",
  "platform": "whatsapp",
  "to": "+31600000000",
  "from": "+31600000000",
  "channelId": "0181d0bb46c5449aae0309f822b35ba5",
  "type": "whatsappOrder",
  "content": {
    "whatsappOrder": {
      "catalog_id": "1004272927097129",
      "text": "Ok, I would like to order this one",
      "product_items": [
        {
          "product_retailer_id": "e86qq6z9hx",
          "quantity": 1,
          "item_price": 45,
          "currency": "EUR"
        }
      ]
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-01-18T15:22:41.884661867Z",
  "updatedDatetime": "2022-01-18T15:22:41Z"
}

The field content.whatsappOrder.catalog_id contains the Facebook Catalog ID of the product the customer is ordering
The field content.whatsappOrder.text contains an optional text message
The field content.whatsappOrder.product_items contains an array with the ordered products
The field content.whatsappOrder.product_items[].product_retailer_id contains the Facebook Product ID which the customer is ordering
The field content.whatsappOrder.product_items[].quantity contains the quantity of a particular product
The field content.whatsappOrder.product_items[].item_price contains the unit price of the product
The field content.whatsappOrder.product_items[].currency contains the currency

How to find my catalog and products?

Before start sending WhatsApp Single or Multi-Product Messages, it's important to know how to find the catalog ID and the product ID in Facebook Commerce Manager, as this information will be necessary when sending messages to your customers.

In case your Facebook Business Account doesn't have a product catalog, please refer to the links below to learn how to create the catalog, add products to it and the best practices managing it.

Finding the Catalog ID

Step 1 - Go to your Facebook Business Settings

Step 2 - Select your business

Step 3 - On the left side menu, click on the Data Sources section, and then, click on Catalogs

Step 4 - Select the catalog in the list

Step 5 - The catalog ID is visible on the top, in blue, below the catalog title

Step 6 - Click to copy the catalog ID

Finding the product ID

Step 1 - In the Product Catalogs page, click on the button "Open Commerce Manager" in the top right corner. Or, if you know the catalog ID and your business ID, you can use the following URL and replace the placeholders: https://business.facebook.com/commerce/catalogs/{catalog-id}/products?business_id={business-id}

Step 2 - On the left side menu, click on the Catalog section, and then, click on Items

Step 3 - The Items page displays every product in the catalog. The ID of every product is visible in the field "Content ID" below the product name.

Is this page useful?

Next upSms Overview

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings