WhatsApp Interactive - Single & Multi-Product Messages

Read this FAQ in the Portuguese and Spanish languages.

What is a Product Message?

The Product Messages enable businesses to showcase their products and services to their customers without leaving the WhatsApp app. 

Let us understand the types of product messages in detail:

• Multi-Product Messages: Messages containing a selection of up to 30 items from a business’ inventory.
• Single Product Messages: Messages with a single product item from the business’ inventory. The product is displayed in a Product Detail Page (PDP) format.

Both Multi-Product Messages and Single Product Messages are types of session interactive messages meaning you are not required to get it approved from WhatsApp, unlike template messages - they cannot be sent as notifications but can only be sent as part of existing conversations.

Users that receive Multi and Single Product Messages can perform 3 main actions:

• View products: Customers can see a list of products or just one product. Whenever a user clicks on a specific item, WhatsApp fetches the product's latest info and displays the product in a Product Detail Page (PDP) format. Currently, PDPs only support product images —any videos and/or GIFs added to the product won’t be displayed in the PDP.
• Add products to a cart: Whenever a user adds a product to the shopping cart, WhatsApp fetches the item’s latest info. If there has been a state change on any of the items, WhatsApp displays a dialog saying “One or more items in your cart have been updated” — See Product Updates given below for more information. A cart persists in a chat thread between business and customer until the cart is sent to the business —See Shopping Cart Experience given below for details.
• Send a shopping cart to the business: After adding all needed items, customers can send their cart to the business they’re messaging with. After that, businesses can define the next steps, such as requesting delivery info or giving payment options.

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 the Shopping Cart Experience given below for details.

Currently, these types of messages can be received on the following platforms:

• iOS: 2.21.100 (Multi-Product Messages) and 2.21.210 (Single Product Messages).
• Android: 2.21.9.15 (Multi-Product Messages) and 2.21.19 (Single Product Messages).
• Web: The web client that supports these features has been launched.

If the recipient’s app version does not support Multi or Single Product Messages, the business receives a webhook notification throwing an error that describes why the message was unable to be sent.

Product Updates

Businesses may need to update the properties of items in their catalog. Depending on the updated property, this is how we handle any messages mentioning that product:

Shopping Cart Experience

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:
Is unique to a person/business chat thread in a specific device: Only one cart is created per chat thread between customer and business and carts do not persist across multiple devices. Once a cart is sent, the customer can open another cart with the business and start the process again.
Has no expiration date: The cart persists in the chat thread until it is sent to the business. Once sent, the cart is cleared. 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.

Prerequisites to send a product message

1. Create Catalog and add items to catalog

   1. Follow this guide if you have not created any catalog yet, else move to step 2

2. Assign a partner business to your catalog

   1. Since the WABA are created by the BSP, and Catalog by Merchants / ISV / Businesses - they have to assign BSP as partner business to their catalog, to do so follow the below steps:
      1. Go to your Business Settings and select your business.
      2. Select Data Sources.
      3. Select Catalogs and select the name of your catalog.
      4. Select Assign Partner.
      5. Once you choose to assign a partner at step 4, you will get 2 options for doing so; -> Select Business ID(Refer step 6) OR Generate a link(Refer step 7).
      6. If you select the option "Select Business ID" -

a. Enter Business ID as 1900820339959633 and under the Full control permission section select Manage catalogue option. Once done, select Next, and then Close.

b. Once the request is submitted, write to devsupport@gupshup.io with the Subject line: Approve Catalog request: <<App Name>> and the mail body should have the Catalogue Name and ID. We will approve the partner request and also connect the Catalog to the Live app mentioned in the subject line.

7. If you select the option "Generate a link" -

a. Select Get link to share to generate a link.

b. Select the Manage catalogue task.

c. You can then send the link to us at devsupport@gupshup.io along with the Subject line: Approve Catalog request: <<App Name>>. You can use each link only once and it expires in 30 days.

Note: Only 1 Catalogue can be associated with a WABA.

If the WABA is Indian (+91 phone number), business’s e-commerce compliance is necessary: Share the below details with Gupshup on the same email to register your WABA:

Entity/Business details:

Customer care details:

Grievance officer details: 

Note: For more info refer here i.e. How to comply with the laws for selling online in India using WhatsApp Business API.

API specification to send product messages

API Endpoint:

POST https://api.gupshup.io/sm/api/v1/msg

Headers

Common request payload

Message payload object

Sample single product message:

{
    "type": "product_details",
    "subType": "product",
    "catalogId": "558215241949699",
    "destination": "9184********",
    "productId": "2v3fh1axoq",
    "body": {
        "text": "body content!"
    },
    "footer": {
        "text": "footer content!"
    }
}

Sample Multi-product message:

CURL

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/msg' \
--header 'apikey: xxxxxxxxxxxx' \

--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=553598XXXX29' \
--data-urlencode 'destination=91996XXXX68' \
--data-urlencode 'message={
  "type": "product_details",
  "subType": "product_list",
  "catalogId": "1598140273855917",
  "productId": "",
  "destination": "919964XXX68",
  "body": {
    "text": "body content!"
  },
  "header": {
    "type": "text",
    "text": "header content!"
  },
  "footer": {
    "text": "footer content!"
  },
  "sections": [
    {
      "title": "",
      "productList": [
        {
          "productId": "559iac23i3"
        },
        {
          "productId": "c358j92ic3"
        }
      ]
    }
  ]
}' \
--data-urlencode 'src.name=Gersjdn'

Inbound message:

The query for a product:

{
    "app": "Extra9",
    "timestamp": 1637840344966,
    "version": 2,
    "type": "message",
    "payload": {
        "id": "ABEGkZlpNARoAgo-sKGeURk3EWXT",
        "source": "919969340468",
        "type": "text",
        "payload": {
            "text": "Hello"
        },
        "sender": {
            "phone": "919969340468",
            "name": "Omkar Mestry",
            "country_code": "91",
            "dial_code": "9969340468"
        }
    }
}

Order placed:

{
    "app": "DemoApp",
    "timestamp": 1590854464792,
    "version": 2,
    "type": "order",
    "payload": {
        "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
        "source": "918x98xx21x4",
        "type": "text",
        "payload": {
            "text": "hi"
        },
        "sender": {
            "phone": "918x98xx21x4",
            "name": "Smit",
            "country_code": "91",
            "dial_code": "8x98xx21x4"
        },
        "context": {
            "catalog": {
                "id": "",
                "order": {
                    "items": [
                        {
                            "id": "",
                            "currency": "",
                            "amount": "",
                            "quantity": ""
                        },
                        {
                            "id": "",
                            "currency": "",
                            "amount": "",
                            "quantity": ""
                        }
                    ]
                }
            }
        }
    }

Inbound message payload object: