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.
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 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).
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 Messages for Business", "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 | FBM | GBM | Instagram Messaging | ||
|---|---|---|---|---|---|---|
| Text | √ | √ | √ | √ | √ | √ |
| Media | √ | x | √ | √ | √ | √ |
| - Image | √ | x | √ | √ | √ | √ |
| - Video | √ | x | √ | √ | x | x |
| - Audio | √ | x | x | √ | x | x |
| Location | √ | x | x | x | x | x |
| Contact | √ | x | x | x | x | x |
| Suggestions | √ * | x | √ | √ | √ | √ |
| - Reply | √ * | x | √ | √ | √ | √ |
| - OpenUrl | x | x | x | x | √ | x |
| - Dial | x | x | x | x | √ | x |
| - Interactive | √ | x | x | x | x | x |
* WhatsApp interactive template replies work somewhat differently from suggestion replies in Twitter, FBM, GBM and Instagram Messaging. Please refer to the documentation for details.
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:
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.
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.
"custom": {
"rawPayload": {
/* Raw payload received from the channel supplier. */
}
}| Channel | Section |
|---|---|
| Instagram Messaging | Story reply |
| Google Business Messages | Message context |
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"
}With WhatsApp we can send interactive messages not to be confused with interactive template messages. Please see following example on how to send interactive messages on the MT side: https://www.cm.com/en-en/app/docs/api/business-messaging-api/1.0/index#whatsapp-interactive-message
When an customer replies to an list message you will get an list_reply.
When an customer replies to an reply button you will get an button_reply.
The title of the button or list reply will also be available in the regular text field.
Example 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"
}
}
},
"groupings": ["", "", ""],
"timeUtc": "2019-11-05T08:32:33"
}Contains the following information about the rows selected by the customer: id, title, and description.
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"
}
}
},
"groupings": ["", "", ""],
"timeUtc": "2019-11-05T08:32:33"
}Contains the following information about the button clicked by the customer: id and title.
With WhatsApp we can send interactive product messages. Please see following example on how to send interactive messages on the MT side: https://www.cm.com/en-en/app/docs/api/business-messaging-api/1.0/index#whatsapp-product-message
When a customer is done with selecting articles in their shopping cart and sends a reply, you will receive a order MO, which may look like this:
{
"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
}
}
},
"groupings": ["", "", ""],
"time": "2021-11-08 13:19:49",
"timeUtc": "2021-11-08T12:19:49",
"channel": "WhatsApp"
}With this information, you can follow-up by sending a payment link to the customer.
For service requests, users initiate a conversation and will reach out to you. To link incoming messages to your outbound messages, the from/to field is used with an Apple Messages for Business-identifier value.
An Apple Messages for Business-identifier or the 'Opaque user identifier' as Apple calls it, is a string of alpha numerical characters that you have received as the from address in an incoming message. This is the only information you have about a user on the Apple platform. You do not receive the name, profile image, location or anything else the user has not shared themselves within conversation. It is possible, but not necessary, that you will receive a UUID as an end-user identifier. This identifier is mapped in the CM.com platform.
Apple Messages for Business supports receiving text messages and receiving media messages.
It is possible to define intent, group and body parameters in the link that is presented to end-users to start the conversation. These values will be forwarded to your webhook. Intent and group can be used to route traffic directly to the appropriate actions or persons. read more
Do note that the intent and group will only be sent in the first message of the conversation.
{
"reference": "515836577",
"messageContext": "",
"from": {
"number": "6f2de4d4cc6aa17da2e11c3bff5843aa",
"name": ""
},
"to": {
"number": "00iMsg20241c26-f863-4faf-8bb2-ad4213641caa"
},
"message": {
"text": "Hi",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"MESSAGETYPE": "Text",
"INTENT": "apidocs",
"GROUP": "techsupport"
}
},
"groupings": [
"",
"",
""
],
"time": "2021-05-19 15:42:28",
"timeUtc": "2021-05-19T13:42:28",
"channel": "Apple Messages for Business"
}When using a list or time picker, the label of the selected element will be sent as text in the response.
{
"reference": "515836578",
"messageContext": "",
"from": {
"number": "6f2de4d4cc6aa17da2e11c3bff5843aa",
"name": ""
},
"to": {
"number": "00iMsg20241c26-f863-4faf-8bb2-ad4213641caa"
},
"message": {
"text": "Ace of Spades",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"MESSAGETYPE": "Text"
}
},
"groupings": [
"",
"",
""
],
"time": "2021-05-19 16:04:45",
"timeUtc": "2021-05-19T14:04:45",
"channel": "Apple Messages for Business"
}Conversations in Apple Messages for Business remain active for use as long as the end user does not close the conversation. When that does happen you will receive a 'Close' message and are no longer allowed or able to send messages to this user.
{
"reference": "515836576",
"messageContext": "",
"from": {
"number": "6f2de4d4cc6aa17da2e11c3bff5843aa",
"name": ""
},
"to": {
"number": "00iMsg20241c26-f863-4faf-8bb2-ad4213641caa"
},
"message": {
"text": "CLOSE_CONVERSATION",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"MESSAGETYPE": "Close"
}
},
"groupings": [
"",
"",
""
],
"time": "2021-05-19 17:04:45",
"timeUtc": "2021-05-19T15:04:45",
"channel": "Apple Messages for Business"
}It is also possible to make a payment using Apple Pay. Setting this up requires some custom work and we therefor ask you to contact our support team.
If you have your own app and want to have your own Apple Messages for Business integrations than this is possible as well. Again, please contact our support team.
The main difference to other channels is the fact that Facebook Messenger 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.
See also receiving media messages
The support and restrictions for media files are the same as for sending Facebook Messenger messages.
Media files send by Facebook users will be hosted behind CM authentication as it may contain sensitive information of the user.
In order to download these media files, your request towards the provided media url should contain the X-CM-PRODUCTTOKEN header with your product token as its value.
As a registered user, you can find your product token on our platform in the Channels app or for older SMS accounts in the Gateway app.
NOTE: Your product token is private information and should never be incorporated into webpages and/or mobile applications where it can be exposed to 3rd parties.
When the customer clicks on an item in a quick reply suggestion list, the reply will have the original action and the original postbackData in the custom/suggestions item:
"custom: "{
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "John Doe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "Edit appointment",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Facebook Messenger"
}When the customer selects a product on a Facebook page or on a sent product template, the reply will have the original action and the original product id in the custom/suggestions item:
"custom: "{
"suggestions": [
{
"action": "ViewProduct",
"postbackData": "PRODUCT_ID"
}
]
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "John Doe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "Chosen product",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"suggestions": [
{
"action": "ViewProduct",
"postbackData": "PRODUCT_ID"
}
]
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Facebook Messenger"
}The main difference to other channels is the fact that Instagram uses numeric identifier for a sender and recipient. So called "Instagram Scoped User ID (IGSID)" for the sender and a "Instagram account ID" for the recipient of the MO message. A person is assigned a unique IGSID for each Instagram Business account they start a conversation with.
These identifiers are visible in the CM.com platform as the userid below channels...Instagram.
See also receiving media messages
Instagram leverages CDN URLs which allow you to retrieve rich media content shared by users. It is not allowed by Instagram to download, retain, or otherwise store the media content sent or made accessible by any user (or enable any third party to do so) and you, or any third party, must not do anything to circumvent expiration and/or removal of any link to such media content.
CM only provides the CDN URL so Instagram has full control of the content. This means, the CDN URL will not return the media when the content is deleted or expired at Instagram. If you want to make use of the media content, you are only allowed to store the privacy aware CDN URL in your system and use this link to render the media made accessible.
{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "John Doe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "",
"media": {
"mediaUri": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=1234&signature=AAAA",
"contentType": "",
"title": ""
},
"custom": {}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Instagram"
}When the customer clicks on an item in a quick reply suggestion list, the reply will have the original action, and the original postbackData in the custom/suggestions item:
"custom": {
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "John Doe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "Edit appointment",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Instagram"
}When an end-user replies to one of your Instagram stories, Instagram returns metadata in a "reply_to" item containing a reference of the story the user replied to. This metadata contains information such as the id and the media url of your Instagram story. This is Instagram specific data, and we return it in a "custom/rawPayload" item.
Keep in mind: the media url of the Instagram story follows the same CDN rules of an Instagram media messages.
In addition, its only available for 24 hours before Instagram will expire the media url.
Below is an example of the rawPayload containing "reply_to" data.
"custom": {
"rawPayload": {
"reply_to": {
"story": {
"id": string,
"url": string
}
}
}
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "John Doe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "Nice Instagram story",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"rawPayload": {
"reply_to": {
"story": {
"id": "1234",
"url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=1234&signature=AAAA"
}
}
}
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Instagram"
}An end-user can mention your Instagram business account in one of its Instagram stories. By doing so, an event will be triggered. Because it's an event, no MO message will be sent. Instead an event is sent out, as described in our events webhook documentation.
For receiving this event, please read on how to setup this seperate webhook.
Viber supports receiving text messages and receiving media 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 Twitter direct messages.
Media files send by Twitter users will be hosted behind CM authentication as it may contain sensitive information of the user.
In order to download these media files, your request towards the provided media url should contain the X-CM-PRODUCTTOKEN header with your product token as its value.
As a registered user, you can find your product token on our platform in the Channels app or for older SMS accounts in the Gateway app.
NOTE: Your product token is private information and should never be incorporated into webpages and/or mobile applications where it can be exposed to 3rd parties.
When the customer clicks on an item in a quick reply suggestion list, the reply will have the original action, and the original postbackData in the custom/suggestions item:
"custom: "{
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "87654321",
"name": "@JohnDoe"
},
"to": {
"number": "12345678"
},
"message": {
"text": "I want to edit my appointment",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 13:01:27",
"timeUtc": "2021-05-27T11:01:27",
"channel": "Twitter"
}Please note that Google Business Messages uses id's (more technically GUIDs) as a sender and recipient.
In the from: field, you will find the GUID of the sender. Due to technical limitations, when you receive an MO message, the id in the to: field will be formatted without the dashes (-).
See also receiving media messages
Media files send by Google users will be hosted behind CM authentication as it may contain sensitive information of the user.
In order to download these media files, your request towards the provided media url should contain the X-CM-PRODUCTTOKEN header with your product token as its value.
As a registered user, you can find your product token on our platform in the Channels app or for older SMS accounts in the Gateway app.
NOTE: Your product token is private information and should never be incorporated into webpages and/or mobile applications where it can be exposed to 3rd parties.
When the customer clicks on an item in a quick reply suggestion list, the reply will have the original action, and the original postbackData that was added to the suggestion when sending the message in the custom/suggestions item:
"custom: "{
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}Other types of suggestions return the same basic structure, but with a different "action". For example, a "dial" action, will look like this:
"custom": {
"suggestions": [
{
"action": "Dial",
"postbackData": "HQ_NUMBER"
}
]
}An "OpenUrl" action, will look like this:
"custom": {
"suggestions": [
{
"action": "OpenUrl",
"postbackData": "HQ_WEBSITE"
}
]
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "00000000-0000-0000-0000-000000000000",
"name": "John Doe"
},
"to": {
"number": "11111111111111111111111111111111"
},
"message": {
"text": "Edit appointment",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"suggestions": [
{
"action": "Reply",
"postbackData": "EDIT_APPOINTMENT"
}
]
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Google Business Messages"
}In addition, Google also returns metadata in a "context" item in messages from end-users. This metadata contains information such as the end-users locale, the entry point of the conversation and a Google specific place id. This is GBM specific data, and we return it in a "custom/rawPayload" item.
The contents of the "context" metadata can vary. An overview of possible data can be found here: https://developers.google.com/business-communications/business-messages/reference/rest/v1/Context Below is an example of the rawPayload containing "context" data.
"custom": {
"rawPayload": {
"context": {
"entryPoint": string,
"userInfo": {
"displayName": string,
"userDeviceLocale": string
},
"widget": {
"url": string,
"widgetContext": string
},
"resolvedLocale": string,
"customContext": string,
"placeId": string,
"nearPlaceId": string
}
}
}{
"reference": "my-reference",
"messageContext": "",
"from": {
"number": "00000000-0000-0000-0000-000000000000",
"name": "John Doe"
},
"to": {
"number": "11111111111111111111111111111111"
},
"message": {
"text": "Where is your company located",
"media": {
"mediaUri": "",
"contentType": "",
"title": ""
},
"custom": {
"rawPayload": {
"context": {
"entryPoint": "MAPS",
"userInfo": {
"displayName": "John Doe",
"userDeviceLocale": "en-NL"
},
"resolvedLocale": "en"
}
}
}
},
"groupings": ["", "", ""],
"time": "2021-05-27 15:47:52",
"timeUtc": "2021-05-27T13:47:52",
"channel": "Google Business Messages"
}RCS supports receiving text messages and receiving media messages.