We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.
Businesses have multiple ways to share products with customers:
Catalog messages are free-form messages that allow you to showcase your product catalog entirely within WhatsApp.
Catalog messages display a product thumbnail header image of your choice, custom body text, a fixed text header, a fixed text sub-header, and a View catalog button.
When a customer taps the View catalog button, your product catalog appears within WhatsApp.
You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account.
Use the WhatsApp Business Phone Number > Messages endpoint to send a catalog message.
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<TO>", "type": "interactive", "interactive" : { "type" : "catalog_message", "body" : { "text": "<BODY_TEXT>" }, "action": { "name": "catalog_message", "parameters": { "thumbnail_product_retailer_id": "<THUMBNAIL_PRODUCT_RETAILER_ID>" } }, /* Footer object is optional */ "footer": { "text": "<FOOTER_TEXT>" } }
Placeholder | Description | Sample Value |
---|---|---|
String | Required. Text to appear in the message body. Maximum 1024 characters. |
|
String | Optional. Text to appear in the message footer. Maximum 60 characters. |
|
String | Required. Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message's header image. If the |
|
String | Customer phone number. |
|
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "16505551234", "type": "interactive", "interactive": { "type": "catalog_message", "body": { "text": "Hello! Thanks for your interest. Ordering is easy. Just visit our catalog and add items to purchase." }, "action": { "name": "catalog_message", "parameters": { "thumbnail_product_retailer_id": "2lc20305pt" } }, "footer": { "text": "Best grocery deals on WhatsApp!" } } }'
{ "messaging_product": "whatsapp", "contacts": [ { "input": "16505551234", "wa_id": "16505551234" } ], "messages": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0ODVEREUwQzEzQkVBRjQ1RUUA" } ] }
Catalog template messages are template messages containing a button that, when tapped, displays your product catalog within WhatsApp.
To send a catalog template message you need a catalog template. See our Catalog Templates document to learn how to create these templates and how to send them in a template message.
Businesses can send a link to their entire product catalog by assembling a wa.me link and including it in a standard text message. When sending a text message, businesses can use the optional preview_url
set to true
to have the message render a set of product catalog thumbnails of any URL in the message body
string.
Note that if businesses disable the catalog, wa.me links and the View Catalog button in catalog link messages will display a Invalid catalog link message when tapped.
To assemble wa.me link, append the business's business phone number, including country code, to the end of the following string:
https://wa.me/c/
For example:
https://wa.me/c/15555455657
Both Multi-Product Messages and Single Product Messages are types of interactive
messages.
Multi-Product message example: | Single Product message example: |
Menu triggered when user clicks on Start Shopping: | Product Detail Page example: |
Users that receive Multi and Single Product Messages can perform 3 main actions:
If a customer has Multiple devices linked to the same WhatsApp account, the Multi-Product and Single Product Messages will be synced between devices. However, the shopping cart is local to each specific device. See Shopping Cart Experience for details.
Currently, these types of messages can be received in the following platforms:
2.21.100
(Multi-Product Messages) and 2.21.210
(Single Product Messages).2.21.9.15
(Multi-Product Messages) and 2.21.19
(Single Product Messages).If the recipient's app version does not support Multi or Single Product Messages, they will instead receive a message explaining that they were unable to receive a message because they are using an outdated version of WhatsApp. The business will also receive a webhook notification indicating the message was unable to be delivered due to the recipient using an outdated version of WhatsApp.
Multi-Product Messages and Single Product Messages can be:
Catalog Messages, Multi-Product Messages and Single Product Messages cannot be:
Businesses may need to update properties of items in their catalog. Depending on the updated property, this is how we handle any messages mentioning that product:
Updated Property | Update Process |
---|---|
Product’s price, title, description, and image. |
|
Availability change |
|
After viewing products, a customer can add them to their shopping cart and send that cart to a business. For the purposes of commerce on WhatsApp, a shopping cart:
Customers can add up to 99 units of each single catalog item to a shopping cart, but there is no limit on the number of distinct items that can be added to a cart.
Once a cart has been sent, no edits can be made. Customers can send a new cart if they need new items, or would like to change their order. Businesses cannot send carts to customers.
Both Multi and Single Product Messages lend themselves best to user experiences that are simple and personalised, where it’s a better experience to guide the customer to a subset of items most relevant to them, rather than browsing a business’ full inventory.
Combining the features with navigation tools like NLP, text search or List Messages and Reply Buttons to get to what the customer is looking for fast.
Populated dynamically so can be personalised to the customer or situation. For example, you can show a Multi-Product Message of a customer’s most frequently ordered items.
A performant channel for driving orders, during testing businesses had an average 7% conversion of Multi-Product Messages sent to carts received.
Interactive messages do not require templates or pre-approvals. They are generated in real-time and will always reflect the latest item details, pricing and stock levels from your inventory.
Multi-Product Messages are best for guiding customers to a specific subset of a business’ inventory, such as:
Single Product Messages are best for guiding customers to one specific item from a business’ inventory, offering quick responses from a limited set of options, such as:
Both features can also be used as part of a human agent flow, however you need to build the tooling to allow the human agent to generate a Multi-Product Message or Single Product Message in thread.
Before sending each message, you need to get your receiver’s WhatsApp ID with a call to the /contacts
node.
We recommend setting up webhooks to receive message status and inbound message notifications. This way, you can track if a message was sent and the answers from customers.
To send a Single Product Message, assemble an interactive
object of type product
with the following components:
Object | Description |
---|---|
| Optional. A body object. See all options for the |
| Optional. A footer object. See all options for the |
| Required. The action field must include:
|
By the end, the interactive object should look something like this:
"interactive": { "type": "product", "body": { "text": "text-body-content" }, "footer": { "text": "text-footer-content" }, "action": { "catalog_id": "catalog-id", "product_retailer_id": "product-SKU-in-catalog" } }
To send a Multi-Product Message, assemble an interactive
object of type product_list
with the following components:
Object | Description |
---|---|
| Required. The header’s |
| Required. A |
| Optional. A |
| Required. The action field must include:
Inside each section, you can include the following:
Each product object contains a |
By the end, the interactive
object should look something like this:
"interactive": { "type": "product_list", "header":{ "type": "text", "text": "text-header-content" }, "body":{ "text": "text-body-content" }, "footer":{ "text":"text-footer-content" }, "action":{ "catalog_id":"catalog-id", "sections": [ { "title": "the-section-title", "product_items": [ { "product_retailer_id": "product-SKU-in-catalog" }, { "product_retailer_id": "product-SKU-in-catalog" }, ... ]}, { "title": "the-section-title", "product_items": [ { "product_retailer_id": "product-SKU-in-catalog" } ... ]}, ... ] }, }
If none of the items provided in the API calls above matches a product from the business’ Facebook catalog, an error message is sent and the Multi or Single Product Message is not sent to the user.
For Multi-Product Message, at least one item from the products list must match an item from the business’ Facebook Catalog. In this case:
Once the interactive object is complete, append the other parameters that make a message: recipient_type
, to
, and type
. Remember to set the type
to interactive
.
{ "recipient_type": "individual", "to" : "whatsapp-id", // WhatsApp ID of the recipient "type": "interactive", "interactive":{ // The interactive object } }
See parameters common to all message types here.
POST
Call to /messages
Make a POST
call to the /messages
endpoint with the JSON
object you have assembled in steps 1 and 2. If your message is sent successfully, you get the following response:
{ "messages": [{ "id": "{message-id}" }] }
To send a multi-product template message you need a multi-product message template. See our Multi-Product Message Templates document to learn how to create these templates and how to send them in a template message.