{
  1. Introduction
  2. Receiving messages
    1. Contents format
    2. Media messages
    3. Channel feature support
  3. SMS
  4. WhatsApp
    1. Contact message
    2. Location message
  5. Twitter direct messages
  6. Apple Business Chat
  7. RCS
  8. Viber

MO Webhooks

Introduction

You can receive your incoming messages (MO messages) for channels supported by the CM.com Business Messaging API in your own systems, by registering a webhook in the Channels-app or the Gateway-app. After registering a HTTPS web address you will start receiving the incoming messages.

Receiving messages

In order to receive the incoming messages, you need to build a webservice where our systems can deliver the messages. This is called a webhook. Via the webhook you will be notified by CM.com of the new message content and metadata using a POST call to your registered web service in the JSON content format. To indicate you have received the message you need to reply with an HTTP 200 OK statuscode. You do not need to send any content back in the reply. You can receive incoming messages from SMS channels, WhatsApp, Apple Business Chat, Viber and RCS. using these webhooks.

If your web service returns anything else other than response code 200 OK, we will consider the message as not having been delivered. Our services will temporarily hold the information and retry delivery every 5 minutes (for a maximum of one month).

Contents format

Webhook calls are made using HTTP POST with the Content-Type application/json and are in the UTF-8 character set. You will receive a JSON object like this on the registered URLs:

Field Description
from Information about the sender. (See below)
to Information about the recipient of the message. (See below)
message The content of the message. (See below)
reference A reference to an outgoing message that this message is a response to. (See below)
groupings Array of exactly three strings with the grouping information. (See below)
timeUtc The time (yyyy-MM-ddTHH:mm:ss) of the message in UTC.
channel The channel that the message was sent with. (e.g. "WhatsApp", "SMS", "Apple Business Chat", "RCS", "Viber", "Twitter")

Note: For replies, both 'reference' and 'groupings' return information sent with the original message that was responded on. This value is only supplied when the message was received as a reply and not when it was received as a message on a distinct keyword or phone-number match. This is currently only supported on SMS.

Note: The field time will be removed early 2020. Please use timeUtc going forward.

From:

Field Description
name For some channels, such as WhatsApp, this will contain the profile name of the user (if set)
number Phone number or identifier of the device from where the message originated.

To:

Field Description
number Phone number or identifier (MSISDN/shortcode/Twitter snowflake ID) to which the message was sent.

Message:

Field Description
text The text content of the message, when the message contains text.
media A media item can be an image, audio, movie or document file. If no media item was sent all fields will be empty
custom Custom object, can be anything a specific channel supports such as a location or a list of contact items.

Example text message

{
    "from": {
        "number": "+316012345678",
        "name": ""
    },
    "to": {
        "number": "3669"
    },
    "message": {
        "text": "This is an example message",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {}
    },
    "reference": "2f2d42ac-3809-40fb-bce5-dc720e400000",
    "groupings": [
        "39373ce0-f4aa-4918-8ff1-3cef7f77b112",
        "messagesApi",
        ""
    ],
    "timeUtc": "2019-11-05T08:32:33",
    "channel": "WhatsApp"
}

Media messages

Most channels support some sort of media capability for receiving images, audio, video and/or attachments. Please see channel specific information for details on capabilities.

Media:

Field Description
mediaUri A unique download URL for the file
contentType The mime type of the file as indicated by the channel
title A caption or title belonging to the media file

You should expect to receive media files of almost any type that the channel you are using supports. Images, videos and documents are all possible. You need to download the specific media item from the unique link specified in the mediaUri attribute. All files are deleted after a maximum of 30 days, downloaded or not.

We are not a media host for your audience. If you want to expose the media file you receive to a user, you are responsible for 'republishing' the file within your system and disclosing this file to the correct audience. You should never pass the mediaUri directly to your own audience.

Example message with media item

{
    "reference": "2f2d42ac-3809-40fb-bce5-dc720e400000",
    "from": {
        "number": "+316012345678",
        "name": "Demo"
    },
    "to": {
        "number": "00316012345678"
    },
    "message": {
        "text": "",
        "media": {
            "mediaUri": "https://temp.com/adsadsa",
            "contentType": "image/png",
            "title": "Media items can be empty"
        },
        "custom": {}
    },
    "groupings": [
        "39373ce0-f4aa-4918-8ff1-3cef7f77b112",
        "messagesApi",
        ""
    ],
    "timeUtc": "2019-11-05T08:32:33",
    "channel": "WhatsApp"
}

Channel feature support

Not all channels support the same (combinations of) item types. For details and documentation on a conversation item type, we ask you to refer to documentation of the specific channel.

Conversation item type WhatsApp SMS Twitter
Text
Media x
- Image x
- Video x
- Audio x x
Location x x
Contact x x

SMS messages

Replies are defined as messages that are returned on an outgoing message, within a certain period. This period can vary; it is at least 5 days. To receive replies to SMS messages, you are required to send out the original message with a SenderID that is reply-enabled. Messages to that number need to be delivered at CM's messaging platform and the number must have been configured to process reply messages.

CM has a set of shared numbers available that are free to use to receive your replies on. The downside of using one of these numbers, is that traffic from other customers using the same number could interfere with your traffic, making replies unreliable. For reliant and confidential communication, we advise you to obtain a dedicated phone number. Contact support for more information about choosing and acquiring a suitable SenderID.

This feature is free of charge, and can be configured via the CM-Gateway app. (For the reception of inbound messages, costs may apply, depending on contract and country of destination.) Click the 'Reply settings' button in the top right to set up your incoming messages. Enable replies for your account using the checkmark at the top and at the bottom, add your URL to send your message to. The default 'Json' format is the preferred choice, as the other formats (Xml and Get) are subject to change and might be deprecated in the near future.

WhatsApp

WhatsApp media message

See also receiving media messages

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

  • WhatsApp GIFs will be received as MP4 videos
  • Receiving WhatsApp stickers is not supported

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

Twitter direct messages

See also receiving media messages

The support and restrictions for media files are the same as for sending Twitter direct messages.

The main difference to other channels is the fact that Twitter uses the so-called Twitter snowflake as an identifier for a sender and a recipient.

  • Twitter GIFs will be received as MP4 videos

Apple Business Chat (ABC)

Rich Communication Services (RCS)

Viber