WhatsApp

WhatsApp media message

The support and restrictions for media files is identical to sending.

WhatsApp GIFs will be received as MP4 videos
WhatsApp Stickers are received as media messages of the type image/webp

Media Delete Call

When you want to delete media from the server, you can use the media delete call. This action cannot be undone. The delete call must be made to the exact URL from which the media was fetched.

The following servers are available for use:

cdn-1.messaging.cm.com
cdn-2.messaging.cm.com
cdn-3.messaging.cm.com

It's important to note that the media delete call will only be accepted by the server hosting the file. If the file is hosted on cdn-2, for instance, only a delete call to cdn-2 will be accepted.

Here is an example URL for the delete call:
https://cdn-2.messaging.cm.com/fileproxy/files/db1c9ba779aa4f6da061c4d8e3601cf3

Upon making a delete call, you will receive a response with status code 204. This status code indicates that the request has been successfully processed and there is no additional content to send in the response payload body.

HTTP/1.1 204 No Content

📘
Information
A 204 status code means that the media file was successfully deleted. Once a media file is deleted using the delete call, it can't be recovered. Always double-check before making a delete call. The lack of a response body means that the deletion was successful and no further action is needed.

WhatsApp location message

It is possible to receive a location from a user. Live location updates are not supported.

Field	Description	Required
latitude	Latitude of the location (can be negative)	Yes
longtitude	Longitude of the location (can be negative)	Yes
label	Name of the location	No
searchQuery	Address or search query of the location	No

Example location message

{
    "reference": "2f2d42ac-3809-40fb-bce5-dc720e400000",
    "from": {
        "number": "+316012345678",
        "name": "Demo"
    },
    "to": {
        "number": "+316012345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "location": {
                "latitude": 51.603802,
                "longitude": 4.770821,
                "label": "CM HQ",
                "searchQuery": "Konijnenberg 30"
            },
          "meta_received_time": "2024-02-21T11:01:34",
          "message_type": "location"
        }
    },
    "groupings": [
        "39373ce0-f4aa-4918-8ff1-3cef7f77b112",
        "messagesApi",
        ""
    ],
    "timeUtc": "2019-11-05T08:32:33",
    "channel": "WhatsApp"
}

WhatsApp contact message

It is possible to receive a message with contact information. You can receive 1 or more contacts cards at once, and they will be an array in the custom.contacts attribute.

The format of the keys and values are specific to WhatsApp. The overall design of this should look familiar if you have experience with the VCF contact card format, or the address book formats of Android and/or iOS.

The contacts array can contain the following informative objects:

Field	Required
name	Yes
emails	No
addresses	No
org	No
phones	No
urls	No
birthday	No

Example contact message

{
    "reference": "2f2d42ac-3809-40fb-bce5-dc720e400000",
    "from": {
        "number": "+316012345678",
        "name": "Demo"
    },
    "to": {
        "number": "+316012345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "contacts": [
                {
                    "addresses": [
                        {
                            "city": "Breda",
                            "country": "Netherlands",
                            "country_code": "NL",
                            "street": "Konijnenberg 30",
                            "type": "WORK",
                            "zip": "4825 BD"
                        }
                    ],
                    "name": {
                        "formatted_name": "CM Developer",
                        "last_name": "Your last name"
                    }
                }
            ],
          "meta_received_time": "2024-02-21T11:01:34",
          "message_type": "contacts"
        }
    },
    "groupings": [
        "39373ce0-f4aa-4918-8ff1-3cef7f77b112",
        "messagesApi",
        ""
    ],
    "timeUtc": "2019-11-05T08:32:33",
    "channel": "WhatsApp"
}

WhatsApp replies

In WhatsApp, it is possible to refer to a specific message. This is also known as a reply and can be done on both MT as MO messages.

Please note that you need to include the message context field in your MO Webhook. If you currently do not receive MO with a message context, you are unable to see which message was replied to. Please contact support if you don't have the message context field included.

Replies for MT

To be able to see to which MT message the consumer is replying to, you will have to include a reference to the MT message you are sending:

{
    "messages": {
        "msg": [{
            "body": {
                "TYPE": "AUTO",
                "content": "Reply to this message if you want to receive an invitation to our next webinar"
            },
            "allowedChannels": ["WhatsApp"],
            "reference": "referencereplytest",
            "to": [{
                "number": "0031612345678"
            }],
            "from": "CM.com"
        }],
        "authentication": {
            "productToken": "YourProductToken"
        }
    }
}

If the consumer replies, you will receive the following MO :

{
    "reference": "ABGGMWNhcIFfAhBa1rc5B-fkdkERREvkk",
    "messageContext": "referencereplytest",
    "name": "John Doe",
    "to": {
        "number": "003197008101015"
    },
    "message": {
        "text": "I would like an invite to the Webinar",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {}
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

As you can see, the messageContext field will have the same value as the reference you have passed through in the MT.

Replies for MO

To be able to see to which MO message the consumer is replying to, you will have to keep track of references received in the MO payload.
For example:

{
    "reference": "ADFGDFHNhcIcksdfSDFVSF0oEzwYDFDFClksdDF",
    "messageContext": "",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "I would like to reserve a table for four please.",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {}
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

5 minutes later, the consumer has replied to his own MO, you will receive following MO :

{
    "reference": "SDFSDFNhcDFlcsdUSbGTGKTaLKokdVw0GVL",
    "messageContext": "ADFGDFHNhcIcksdfSDFVSF0oEzwYDFDFClksdDF",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "Scratch that, a friend can't make it, can you make it a table for three please.",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {}
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

You can check to which MO was replied to by using the messageContext field, this field will have the same value as the reference of the original MO.

WhatsApp interactive template replies

When an end-user interacts with a button of an interactive template, there is also extra button-information available. This will make it possible to identify which button has been interacted with by the end-user. The text of the button will also be available in the regular text field if the button was a quick_reply.

payload is the value that can be provided when you send the template. A payload can be assigned to each button when sending the template to the end-user. When the user clicks the button, the payload of that specific button will be available in the body.

{
    "reference": "my-reference",
    "messageContext": "",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "Yes, this is OK",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "referenceTicket": ""
        },
        "custom": {
            "button": {
                "label": "Yes, this is OK",
                // Business Developer-defined payload
                "payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
            },
          "meta_received_time": "2024-02-21T11:01:34"
        }
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

WhatsApp interactive message replies

With WhatsApp, we can send interactive messages, not to be confused with interactive template messages.
Please see following example on how to send interactive messages on the MT side.

When a customer replies to a list message, you will get a list_reply. When a customer replies to a reply button, you will get a button_reply. The title of the button or list reply will also be available in the regular text field.

Example List-Reply

{
    "reference": "my-reference",
    "messageContext": "",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "list-row-title",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "referenceTicket": ""
        },
        "custom": {
            "interactive": {
                "list_reply": {
                    "description": "list-row-description",
                    "id": "your-unique-postbackid",
                    "title": "list-row-title"
                },
                "button_reply": null,
                "type": "list_reply"
            },
          "meta_received_time": "2024-02-21T11:01:34"
        }
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

Contains the following information about the rows selected by the customer: id, title, and description.

Example Button-Reply

{
    "reference": "my-reference",
    "messageContext": "",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "referenceTicket": ""
        },
        "custom": {
            "interactive": {
                "list_reply": null,
                "button_reply": {
                    "id": "your-unique-postbackid",
                    "title": "button-title"
                },
                "type": "button_reply"
            },
          "meta_received_time": "2024-02-21T11:01:34"
        }
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

Contains the following information about the button clicked by the customer: id and title.

WhatsApp interactive Flows replies

When a customer replies to a Flows message, you will get an nfm_reply.

Example Flows Reply

{
    "reference": "my-reference",
    "messageContext": "",
    "name": "John Doe",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "interactive": {
                "type": "nfm_reply",
                "list_reply": null,
                "button_reply": null,
                "nfm_reply": {
                    "name": "flow",
                    "response_json": {
                        "flow_token": "your-flow-token",
                        "entered-field-1": "entered-value-1",
                        ...
                    }
                }
            },
            "meta_received_time": "2024-02-21T11:01:34"
        },
        "error": ""
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "timeUtc": "2019-11-05T08:32:33"
}

In the response_json field, the flow_token is set to the value as sent in the original message. Additional data as defined in the flow is added as dynamic properties.

WhatsApp product message replies

With WhatsApp, we can send interactive product messages.
Please see following example on how to send interactive messages on the MT side.

When a customer is done with selecting articles in their shopping cart and sends a reply,
you will receive an order MO, which may look like this:

{
    "reference": "XXXXXXX",
    "messageContext": "",
    "from": {
        "number": "0031612345678",
        "name": "John Doe"
    },
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "order": {
                "catalog_id": "XXXXXXXXXXXX",
                "product_items": [{
                    "product_retailer_id": "cmcomdevelop-frisbee",
                    "quantity": "99",
                    "item_price": "15",
                    "currency": "EUR"
                }, {
                    "product_retailer_id": "cmcomdevelop-coaster",
                    "quantity": "99",
                    "item_price": "7",
                    "currency": "EUR"
                }, {
                    "product_retailer_id": "cmcomdevelop-mousepad",
                    "quantity": "99",
                    "item_price": "9.99",
                    "currency": "EUR"
                }],
                "text": null
            },
            "meta_received_time": "2024-02-21T11:01:34"
        }
    },
    "groupings": ["", "", ""],
    "time": "2021-11-08 13:19:49",
    "timeUtc": "2021-11-08T12:19:49",
    "channel": "WhatsApp"
}

With this information, you can follow up by sending a payment link to the customer.

WhatsApp deleted message

When a customer wants to delete a message, the business gets informed about which message was deleted.
You will receive a deletedMessage MO, which may look like this:

{
    "reference": "XXXXXXX",
    "messageContext": "",
    "from": {
        "number": "0031612345678",
        "name": "John Doe"
    },
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "deletedMessage":"XXXXXXXYYYYY",
            "meta_received_time": "2024-02-21T11:01:34"
        }
    },
    "groupings": ["", "", ""],
    "time": "2021-11-08 13:19:49",
    "timeUtc": "2021-11-08T12:19:49",
    "channel": "WhatsApp"
}

The content of deletedMessage, which in the example is XXXXXXXYYYYY, refers to an earlier webhook you've received, where the reference is: "reference": "XXXXXXXYYYYY". Upon receiving this notification, you should ensure that the message is deleted from your system.

WhatsApp error message

When Meta informs us about a (partially) failed incoming message, the business will be informed about this message failure. This makes sure the business knows the end-user tried to send a message. You will receive an error MO, which may look like this:

{
    "reference": "XXXXXXX",
    "messageContext": "",
    "from": {
        "number": "0031612345678",
        "name": "John Doe"
    },
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "meta_received_time": "2024-02-21T11:01:34"
        },
        "error": "Message type is not currently supported"
    },
    "groupings": ["", "", ""],
    "time": "2022-11-08 13:19:49",
    "timeUtc": "2022-11-08T12:19:49",
    "channel": "WhatsApp"
}

The content of error, which in the example is Message type is not currently supported, is provided by Meta, when they report an error in the incoming message.

WhatsApp welcome request message

Whenever a user initiates a chat with you for the first time, you are able to receive notifications for this. This feature is valuable for customizing a special welcome message tailored to your preferences. Welcome Messages serve various purposes, particularly in service-oriented interactions like customer support or account management.

When you enable this feature and a user opens the chat with you for the first time, we verify whether there's an existing message thread with your business phone number. If there isn't one, a message webhook with the type set as request_welcome will be initiated. Subsequently, you have the opportunity to reply to the user with your personalized welcome message.

{
    "reference": "XXXXXXX",
    "messageContext": "",
    "from": {
        "number": "0031612345678",
        "name": "John Doe"
    },
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": "User request welcome message",
        "custom": {
            "meta_received_time": "2024-02-21T11:01:34",
            "message_type": "request_welcome"
        }
    },
    "groupings": ["", "", ""],
    "time": "2022-11-08 13:19:49",
    "timeUtc": "2022-11-08T12:19:49",
    "channel": "WhatsApp"
}

WhatsApp media message

Media Delete Call

📘Information

WhatsApp location message

WhatsApp contact message

WhatsApp replies

Replies for MT

Replies for MO

WhatsApp interactive template replies

WhatsApp interactive message replies

WhatsApp interactive Flows replies

WhatsApp product message replies

WhatsApp deleted message

WhatsApp error message

WhatsApp welcome request message

📘
Information