Receive Responses From Customers

After receiving single- or multi-product messages, WhatsApp users can ask for more information about a product or place an order. These actions are communicated via messages webhook.

Message Status

Message status (sent, delivered, read) webhooks have the following format:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "statuses": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "recipient_id": "<WHATSAPP_USER_ID>",
                "status": "<MESSAGE_STATUS>",
                "timestamp": "<WEBHOOK_TIMESTAMP>",
                "conversation": {
                  "id": "<CONVERSATION_ID>",
                  "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",
                  "origin": {
                    "type": "<CONVERSATION_ORIGIN>"
                  }
                },
                "pricing": {
                  "pricing_model": "CBP",
                  "billable": <IS_BILLABLE>,
                  "category": "<CONVERSATION_CATEGORY>"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Asking For Information

Whenever a WhatsApp user receives a single- or multi-product message, they can ask for more information by sending you a text message (type is text) as a standard message in an existing WhatsApp thread, or by first tapping a Message Business or Message button when viewing a specific product.

The only difference between these messages webhook payloads is that if the message originated via a button on a product details page, a context property will be included, whose value is an object describing the product the user was viewing.

Text Messages Inquiry

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {

                /* The `context` property is only included if the user tapped a button
                   on the product details page to send you the message */
                "context": {
                  "from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                  "id": "<CONTEXT_ID>",
                  "referred_product": {
                    "catalog_id": "<CATALOG_ID>",
                    "product_retailer_id": "<PRODUCT_ID>"
                  }
                },

                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TIMESTAMP>",
                "text": {
                  "body": "<MESSAGE_TEXT>"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Placing an Order

When a WhatsApp user adds one or more products to their WhatsApp shopping cart and places an order, a messages webhook with type set to order will be triggered, describing the contents of the order. Use the order contents to fulfill the order.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TIMESTAMP>",
                "type": "order",
                "order": {
                  "catalog_id": "<CATALOG_ID>",
                  "text": "<MESSAGE_TEXT>",
                  "product_items": [
                    {
                      "product_retailer_id": "<PRODUCT_ID>",
                      "quantity": <PRODUCT_QUANTITY>,
                      "item_price": <PRODUCT_PRICE>,
                      "currency": "<PRODUCT_CURRENCY>"
                    }

                   /* Additional items would follow, if order contains multiple items */

                  ]
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}