Incoming Messages

Introduction

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

Receiving messages

In order to receive the incoming messages, you need to build a web service 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 status code. You do not need to send any content back in the reply. You can receive incoming messages from SMS channels, WhatsApp, Apple Messages for Business, 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:

🚧

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:

To:

Message:

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:

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.

🚧

Note

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.

📘

Info

WhatsApp interactive template replies work somewhat differently from suggestion replies in Twitter, FBM, GBM and Instagram Messaging. Please refer to the documentation for details.

Whitelisting

If you want your systems to be certain that requests are sent from CM.com's systems and are not intiated by a spoofing third party, you can limit reception of MO messages to those originating from our IP ranges.

The IP ranges of the services that send MO messages and could be used for our outbound traffic are:

• 31.169.56.0/21
• 85.119.48.0/21
• 188.94.184.0/22

🚧

Note

You should whitelist all these IP ranges. We cannot guarantee an exact IP addresses of specific services within these ranges as the servers can change IP within this range at any time.

Raw payload

Several suppliers return very specific data, that can't be mapped directly into one of our generic models. We still want you to be able to use this data, so for this type of data we have a separate node in our "custom" section, called "rawPayload". Within the rawPayload node, you can find the exact payload the supplier of the channel has sent us.

Example

"custom": {
  "rawPayload": {
    /* Raw payload received from the channel supplier. */
  }
}

Supporting channels