Text messages

Sending WhatsApp messages

For service requests, users usually initiate a conversation and will reach out to you. To link incoming messages to your outbound messages, the phone number field is used (to --> number and from fields). When sending a WhatsApp message it is important to add WhatsApp as a value to the allowedChannels field.

If you have configured multiple WhatsApp-numbers in our platform, you can use the desired phone number by providing it in the from field. If this does not match to one of your phone numbers, your first onboarded number will be used.

The body's content attribute is also required. It is the content value that will be used when falling back to SMS as a delivery channel. The body.content attribute needs to be backwards compatible with SMS channel requirements. This means it is affected by maximum size limitations of SMS as described in the section on SMS multipart messaging.

🚧

Note

The WhatsApp protocol strives for, but does not guarantee, in-order delivery of your messages.

Message example

This example makes use of the Rich Content conversation array, with 3 conversation items (or speech bubbles), 2 text bubbles and one image. These will all be delivered at once.

{
    "messages": {
        "msg": [{
            "body": {
                "type": "auto",
                "content": "Fallback Text for SMS"
            },
            "to": [{
                "number": "00316012345678"
            }],
            "from": "00316098765432",
            "allowedChannels": ["WhatsApp"],
            "richContent": {
                "conversation": [{
                    "text": "A text message with *bold* formatting in a speech bubble."
                }, {
                    "text": "Another speech bubble"
                }, {
                    "media": {
                        "mediaName": "and an image",
                        "mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
                        "mimeType": "image/jpeg"
                    }
                }]
            }
        }]
    }
}

Text messages

Text messages are and should always be encoded in UTF-8 and do support characters like emojis 😀. This is true for both the body field and when using a text item inside a Rich Content conversation. Please remember that emoji rendering is device dependent and older devices therefore may not support the newest unicode emojis and depending on the font used by the device, an emoji may look slightly different on from one device to another 📱💻🖥.

The maximum length of a WhatsApp text message bubble is 4096 characters.

WhatsApp specifically allows a limited amount of formatting for text messages that you can make use of. These markup characters need to be prefixed with a space character in order for them to take effect.

The example below will send a simple text-only WhatsApp message.

{
    "messages": {
        "msg": [
            {
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "to": [
                    {
                        "number": "00316012345678"
                    }
                ],
                "from": "00316098765432",
                "allowedChannels": ["WhatsApp"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it."
                        }
                    ]
                }
            }
        ]
    }
}

URL preview messages

Any URLs present in the message text of a WhatsApp message will be automatically recognized by the clients as links. Additionally, the first URL encountered in a text message will generate a URL preview. For this it is required that the URL starts with http:// or https://

A URL preview can contain a title, a message and a small fragment of text. These elements are automatically retrieved from the destination website. To support this preview, the destination website needs to have implemented the Open Graph Protocol.

The URL preview is retrieved by the WhatsApp software running on the CM.com side, before being sent to the client. This is for privacy reasons.

The example below will send a simple text/URL WhatsApp message.

{
    "messages": {
        "msg": [
            {
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "to": [
                    {
                        "number": "00316012345678"
                    }
                ],
                "from": "00316098765432",
                "allowedChannels": ["WhatsApp"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "https://CM.com - Be part of it."
                        }
                    ]
                }
            }
        ]
    }
}