WhatsApp

WhatsApp media message

The support and restrictions for media files are identical to those for sending.

WhatsApp GIFs are received as MP4 video files
WhatsApp Stickers are received as media messages with the format image/webp

Media Delete Call

To delete media from the server, use the media delete call. Please note that this action is irreversible. The delete call must be made to the exact URL from which the media was originally retrieved.

The following servers are available:

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

It is important to understand that the media delete call will only be accepted by the server that hosts the file. For example, if the file is hosted on cdn-2, only a delete call directed to cdn-2 will be successful.

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

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

HTTP/1.1 204 No Content

📘
Information
A 204 status code indicates that the media file has been successfully deleted. Once a media file is deleted using the delete call, it cannot be recovered. Therefore, always double-check before issuing a delete call. The absence of a response body confirms that the deletion was successful, and no further action is required.

WhatsApp Location Message

It is possible to receive a location from a user. However, live location updates are not supported.

Field	Description	Required
latitude	Latitude of the location (can be negative)	Yes
longitude	Longitude of the location (can be negative)	Yes
label	Name or description of the location	No
searchQuery	Address or search query related to 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

You can receive messages containing contact information via WhatsApp. It is possible to receive one or more contact cards at once, which will be presented as an array in the custom.contacts attribute.

The key-value pairs in this array follow a format specific to WhatsApp. However, if you are familiar with the VCF contact card format or the address book formats used by Android or iOS, the structure should be recognizable.

The contact array may include the following fields:

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, you can reply to a specific message, a feature available for both MT (Mobile Terminated) and MO (Mobile Originated) messages.

Please ensure that the message context field is included in your MO webhook. Without this field, you will be unable to identify which message was replied to. If you are not receiving MO messages with the message context field, please contact support for assistance.

Replies for MT Messages

To track which MT message the consumer is replying to, you must include a reference to the MT message when sending it.

{
    "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"
        }
    }
}

When 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"
}

Note that the messageContext field will have the same value as the reference you provided in the <glossary:MT>.

Replies for MO

To identify which MO message the consumer is responding to, you must keep track of the 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"
}

If the consumer replies to their own MO, you will receive the 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 determine which MO was replied to by using the messageContext field. This field will have the same value as the reference of the original MO.

MT Replies MO

If the consumer responds or sends a message through your MO Webhook, you will receive the following information regarding that specific message:

{
    "reference": " wamid.HBgLMzQ2ODUxMjA0NzMVAgASGBYzRUIwOEU5NzhENEIzNkI5MDE2QkE3AA==",
    "messageContext": "",
    "to": {
        "number": "0031612345678"
    },
    "message": {
        "text": " I would like an invite to the Webinar",
        "custom": {},
        "error": ""
    },
    "groupings": [],
    "time": "2024-09-17 11:37:31",
    "timeUtc": "2024-09-17T09:37:31",
    "channel": "WhatsApp"
}

To reply to the previous MO with a MT, you need to include the reference of the message sent by the consumer in the context object of your message.

{
    "messages": {
        "authentication": {
            "productToken": "Your Product Token"
        },
        "msg": [
            {
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "to": [
                    {
                        "number": "0031612345678"
                    }
                ],
                "from": "CM.com",
                "allowedChannels": ["WhatsApp"],
                "reference": "referencereplytest",
                "richContent": {
                    "conversation": [
                        {
                            "text": "Great! We will send you the invitation soon. Thank your for your interest on our webminar.",
                            "context": {"message_id": " wamid.HBgLMzQ2ODUxMjA0NzMVAgASGBYzRUIwOEU5NzhENEIzNkI5MDE2QkE3AA=="}
                        }
                    ]
                }
            }
        ]
    }
}

WhatsApp Interactive Template Replies

When an end-user interacts with a button from an interactive template, additional button information is provided. This allows you to identify which button the end-user interacted with. If the button was a quick_reply, the text of the button will also appear in the standard text field.

The payload refers to the value you can set when sending the template. A unique payload can be assigned to each button when sending the template to the end-user. Once the user clicks the button, the payload for 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

Interactive messages can be sent via WhatsApp. This should not be confused with interactive template messages.
For guidance on sending interactive messages from the Mobile Terminated (MT) side, please refer to the following example.

Responses to interactive messages vary based on the type of interaction:

When a customer responds to a list message, the response is captured as a list_reply.
When a customer presses a reply button, the response is recorded as a button_reply.
In both cases, the title of the list or button that was interacted with will appear in the standard text field.

The list reply includes details such as the selected rows' id, title, and description.

The button reply includes the id and title of the button clicked by the customer.

Example of a 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"
}

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"
}

WhatsApp Interactive Flows Replies

When a customer responds to a Flows message, the system captures this as an nfm_reply. In the response_json field, the flow_token retains the value sent in the original message. Additionally, any data defined in the flow is incorporated as dynamic properties.

Example of a 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"
}

WhatsApp Product Message Replies

WhatsApp allows the sending of interactive product messages. For guidance on dispatching these messages from the MT (Mobile Terminated) side, refer to the following example.

When a customer completes their selection of articles in the shopping cart and sends a reply, you will receive an order response (MO),. Using this information, you can proceed to send a payment link to the customer.

Product message reply

{
    "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"
}

WhatsApp Deleted Message

When a customer opts to delete a message, the business is notified about which message was deleted.
You will receive a deletedMessage MO.

The content of deletedMessage, such as XXXXXXXYYYYY, corresponds to a reference from a previous webhook you've received, formatted as: "reference": "XXXXXXXYYYYY". Upon receiving this notification, you should ensure that the message is removed from your system.

WhatsApp Delete Request:

{
    "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"
}

WhatsApp Error Message

When Meta reports a (partially) failed incoming message, the business is promptly notified about the failure. This ensures that the business is aware that an end-user attempted to send a message. You will receive an error denoted by MO. The error content, such as Message type is not currently supported, is supplied by Meta to indicate a specific issue with the incoming message.

WhatsApp Error Message:

{
    "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"
}

WhatsApp Welcome Request Message

Whenever a user initiates a chat with your business for the first time, you will receive notifications. This functionality is particularly useful for crafting a custom welcome message that aligns with your specific preferences. Welcome messages are instrumental in various contexts, especially in service-oriented scenarios such as customer support or account management.

Upon activating this feature, when a user starts a chat with you for the first time, we check for an existing message thread linked to your business phone number. If no such thread exists, a message webhook classified as request_welcome is triggered. This allows you the opportunity to respond with a personalized welcome message tailored to the user.

{
    "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

Example Location Message

WhatsApp Contact Message

Example Contact Message

WhatsApp Replies

Replies for MT Messages

Replies for MO

MT Replies 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