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

WhatsApp location message

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

FieldDescriptionRequired
latitudeLatitude of the location (can be negative)Yes
longtitudeLongitude of the location (can be negative)Yes
labelName of the locationNo
searchQueryAddress or search query of the locationNo

Example 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"
            }
        }
    },
    "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 have experience with the VCF contact card format, or the address book formats of Android and/or iOS.

An expansive example of the keys and values can be found in the documentation of WhatsApp.

Example 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"
                    }
                }
            ]
        }
    },
    "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 an can be done on both MT as MO messages.

Please note that you need include the message context field in your MOWebhook. 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"
            }
        }
    },
    "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"
            }
        }
    },
    "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"
            }
        }
    },
    "groupings": ["", "", ""],
    "timeUtc": "2019-11-05T08:32:33"
}

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

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 a 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
            }
        }
    },
    "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.


Did this page help you?