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 or the Gateway-app. After registering a HTTPS web address you will start receiving the incoming 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).
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") |
| messageContext | Field to indicate which MT or MO the consumer has replied to |
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
timewill be removed early 2020. Please usetimeUtcgoing 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. |
{
"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"
}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.
{
"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"
}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 | SMS | ||
|---|---|---|---|
| Text | √ | √ | √ |
| Media | √ | x | √ |
| - Image | √ | x | √ |
| - Video | √ | x | √ |
| - Audio | √ | x | x |
| Location | √ | x | x |
| Contact | √ | x | x |
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.
See also receiving media messages
The support and restrictions for media files is identical to sending.
image/webpIt 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 |
{
"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"
}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.
{
"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"
}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.
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.
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.
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"
}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.
See also receiving media messages
The support and restrictions for media files are the same as for sending Facebook Messenger messages.
The main difference to other channels is the fact that Facebook Messengers uses numeric identifier for a sender and recipient. So called "Page Scoped User ID (PSID)" for the sender and a "Page ID" for the recipient of the MO message. A person is assigned a unique PSID for each Facebook Page they start a conversation with.
These identifiers are visible in the CM.com platform as the userid below channels...Facebook Messenger.