Shared Features
Sending messages
Below is an example of an SMS message:
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Message Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "TestSender"
}]
}
}
Field | Description | Required |
---|---|---|
from | This is the sender name. The maximum length is 16 digits for a phonenumber or 11 alphanumerical characters [a-zA-Z]. Example: 'CM Telecom' | Yes |
to | Phone number of the recipient [array] | Yes |
body | Text content of the message you want to send. SMS restrictions apply to this field allowing for maximum fallback capabilities. For more modern channels like RCS, WhatsApp and Apple Messages for Business, use rich content conversation items conversation items to make use of all capabilities of the channel. | Yes |
allowedChannels | Array of communication channels via which you want to reach the user. Can be any combination of: SMS , Viber , RCS , Apple Messages for Business and WhatsApp , or other channels: Twitter , Facebook Messenger , Instagram . The default is to allow any channel configured for your account. | No |
Some of the objects are arrays
Please note that the
msg
,to
andallowedChannels
objects are arrays and can contain multiple values. Using multiplemsg
orto
elements will produce multiple messages.
Note
When sending a message, all messages are delivered asynchronously. The server response of the API only indicates if it was accepted for a delivery attempt and not if the delivery was successful.
Phone numbers
Please use the following format to specify your phone numbers. Using this format is the best way for us to guarantee the correct delivery of your messages:
- Start with 00
- Country code
- Phone number
- No + sign
- No spaces
- No -
Not adhering to this convention might cause incorrect delivery!
CM.com example
The phone number of our office in The Netherlands is +31 (0)76 - 572 70 00
What we would enter via API: 0031765727000
Batch messages
It is possible to send multiple messages with one request, as described in the examples below. You can either declare multiple phone numbers to send the same message to each of the given phone numbers, or declare multiple different messages in one request.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["Viber"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
},{
"number": "00447911123457"
}],
"body": {
"type": "auto",
"content": "Test message"
}
},
{
"allowedChannels": ["SMS"],
"from": "OtherSender",
"to": [{
"number": "00447911123458"
},{
"number": "00447911123459"
}],
"body": {
"type": "auto",
"content": "Other Test message"
}
}
]
}
}
Channel fallback
Important note
Please note that the order in which channels are specified in the allowedChannels field does not determine the order in which channels are used. The order in which channels are tried is configured per account, where each channel has a prioritized order. If you wish to change this order please reach out to your CM.com representative.
For example:
"allowedChannels": [ "WhatsApp", "SMS" ]
might still result in a message first via SMS and if delivery is not successful via WhatsApp if SMS has a higher priority.
Not all people have installed the popular communication applications in your geographic region. Neither are they always online or are the operator networks always available to deliver messages. To overcome this issue we have developed a fallback solution. By specifying multiple channels in the allowedChannels
parameter, you can use another channel to deliver your messages when your first channel is not available or returning errors.
Example: specifying "allowedChannels": [ "WhatsApp", "SMS" ]
acts as a filter on your configured channel routing. If WhatsApp returns a failure or a rejection for any reason, we will use SMS and the content in the body
attribute to deliver an SMS instead. When a fallback is configured a channel will not retry delivery, but immediately fallback to the next channel.
Fallback is available for the channels:
- Push
- RCS
- Viber
- SMS
References and replies
For each batch of messages you send you can set a reference. To do so, add "reference": "your_reference"
to any "msg"
object in a request body. The given reference will apply to the messages sent to the numbers in the matching message.
- The given reference will be used in the status reports and inbound replies for the message, so you can link the messages to the sent batch. For more information on status reports, see status report webhooks.
- The given reference must be between 1 - 32 alphanumeric characters, and will not work using demo accounts.
- References can be used to measure things like Conversion using the Conversion API.
Custom groupings
The custom grouping fields are optional fields that can be used to tag messages. These tags can be used by other products, like the Transactions API.
Applying custom grouping names to messages helps filter your messages. With up to three levels of custom grouping fields that can be set, subsets of messages can be further broken down. The custom grouping name can be up to 100 characters of your choosing.
This field is used for a wide variety of cases, it helps you to group/tag your messages which helps you with analysis purposes.
The following example demonstrates how to implement a reference and custom groupings in your JSON.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["SMS"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"body": {
"type": "auto",
"content": "Test message"
},
"reference": "your_reference",
"customGrouping": "Campaign ABC",
"customGrouping2": "Department XYZ",
"customGrouping3": "Source 123"
}
]
}
}
Validity period
At all times we strive to deliver messages to the end-user as fast as possible. There can be several situations in which we cannot succeed in this goal. Someone might have switched off his/her phone, or might be in a remote location and does not have access to a network. When you have sent them a message it might be received later than you anticipated.
If you wish to specify a time at which a delayed message can be considered irrelevant, you can supply an absolute date & time or a relative offset in the validity
field. Our system will consider the message as failed if it was not successfully delivered before that time. And via a Status Report we inform you this was the case.
The validity period is treated as a best-effort feature. Operators that are already processing the message, might not adhere to the validity period.
Our default validity time is 24 hours, and the maximum validity period is 48 hours.
This feature is supported in all communication channels, the behavior is the same.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["SMS"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"body": {
"type": "auto",
"content": "Test message"
},
"validity": "2017-04-20 11:50 GMT"
}
]
}
}
You can supply the time zone for the validity period using either of the following formats:
Absolute date and time:
- 2017-04-20 11:50:05 GMT
- 2017-04-20 11:50:05+8
- 2017-04-20 11:55:05-07:00
If no time zone was specified, CE(S)T will be used. (CM local time)
Relative offset in hour (H) or minute (M)
- 2h
- 30m
You can set the validity in either hours or minutes. A combination of both is not supported. Any value less than 30 minutes cannot be guaranteed to work.
Rich Content
Supported by: WhatsApp, RCS, Viber, Twitter, Facebook Messenger, Instagram Messaging
Channels like WhatsApp, RCS and Viber support messages with Rich Content. Rich Content is content that is more complex than a simple text message.
Rich content is sent using the richContent
json attribute. This attribute in turns contains a conversation
and optionally suggestions
.
Field | Description | Required |
---|---|---|
conversation | An array of one or more conversation items | Yes |
suggestions | An array of zero or more suggestions | No |
Conversations
A conversation is an array of several conversation item objects. The best way to think of a conversation item is as a single 'speech' bubble in a chat and you can send one or more in a single request. There are currently 5 conversation item types supported: text
, media
, location
, contact
and template
.
Example message
This example sends two conversation items, one with text and one with an image, via WhatsApp.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [{
"from": "CM.com",
"to": [{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "fallback content"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"text": "A rich content text message"
},
{
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}]
}
}]
}
}
Field | Description | Required |
---|---|---|
text | A string with the textual content. | No |
media | A media object | No |
location | A location object | No |
contact | A contact object contains a description similar to a vCard | No |
template | A communication channel specific template. | No |
At least one of these five is required in a conversation item. 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 that channel's documentation.
Conversation item type | Apple Messages for Business | Viber | RCS | SMS | Facebook Messenger | Instagram Messaging | ||
---|---|---|---|---|---|---|---|---|
Text | √ | √ | √ | √ | √ | √ | √ | √ |
- Text formatting | √ | x | x | x | x | √ | √ | √ |
- URL previews | √ | √ | x | x | x | √ | √ | √ |
Media | √ | √ | √ | √ | x | √ | √ | √ |
- Image | √ | √ | √ | √ | x | √ | √ | √ |
- Video | √ | √ | x | √ | x | √ | √ | √ |
- Audio | √ | √ | x | √ | x | x | √ | x |
- Rich card | x | x | √ | √ | x | x | √ | √ |
- Rich card carousel | x | x | x | √ | x | x | √ | √ |
Location | √ | x | x | √ | x | x | x | x |
Contact | √ | x | x | x | x | x | x | x |
Template | √ | x | x | x | x | x | x | x |
List picker | x | √ | x | x | x | x | x | x |
Time picker | x | √ | x | x | x | x | x | x |
OAuth2 | x | √ | x | x | x | x | x | x |
Custom app | x | √ | x | x | x | x | x | x |
Payment | x | √ | x | x | x | x | x | x |
Please note that not all communication channels offer the exact same features and that the UI might vary per phone. To make use of rich content you need to do some investigation work to ensure that all mobile devices can read what you are sending. Be sure to check the Channel specific sections of this document for further details. And we can help you in defining and identifying this, please contact our support teams when you need a consult.
Suggestions/Features
Supported by: RCS, Viber, Apple Messages for Business, Twitter, Facebook Messenger
Suggestions is an array of suggestion items. A suggestion or feature is usually presented to an end user as a button, and allows the end user to quickly take or pick an action, instead of sending a textual reply. One message can contain up to 11 suggestions to a user. How they are used depends on the scenario you want to built. Usually only 2 or 3 are seen by the end-user when opening the message.
Each suggestion
item contains at least the fields action
and label
.
Field | Description |
---|---|
Label | The text the end user will see |
Action | OpenUrl / CreateCalendarEvent / Dial / ViewLocation / Reply / Login / Logout / ViewProduct |
Depending on the action, certain additional fields are expected to complete the user flow.
OpenUrl
Supported by: RCS, Viber, Apple Messages for Business, Facebook Messenger, and Instagram.
This is used to give the user an option to open a link. This can be an in-app link, which will only be shown when the app is installed.
URL | The url the end user can open |
{
"suggestions": [
{
"action": "OpenUrl",
"url": "market://details?id=cm.com",
"label": "Install app",
"postbackdata": "Data sent back in an MO"
},
{
"action": "OpenUrl",
"url": "https://docs.cmtelecom.com/en/api/business-messaging-api/1.0/index/",
"label": "SMS documentation",
"postbackdata": "Data sent back in an MO"
}
]
}
Create Calendar Event
Supported by: RCS
When the user clicks on this icon, it opens the calendar app of the user to add the new appointment.
Calendar | A calendar object |
The calendar object contains the following fields.
StartTime | The start of the appointment. For example "2018-02-05T07:00:00 |
EndTime | The end of the appointment, for example "2018-02-05T08:00:00" |
Description | The description which will appear in the calendar app |
Title | The title of the appointment which will appear in the calendar app |
{
"action": "CreateCalendarEvent",
"label": "Add to calendar",
"calendar":
{
"startTime": "2018-02-05T00:00:00",
"endTime": "2018-02-08T00:00:00",
"description": "Calendar demo",
"title": "Demo"
}
}
Dial
Supported by: RCS, Facebook Messenger
RCS also provides options to make a phone call straight from the conversation.
When you want to present the user with the option to call you or another team, or listen to a spoken recorded message, this suggestion can be applied. When pressed, starts a new call to the number you have inserted.
Dial | A dial object |
The dial object contains the following field. |
PhoneNumber | The number to call (in international format) |
{
"action": "Dial",
"label": "Call us",
"postbackdata": "Data sent back in an MO",
"dial": {
"PhoneNumber": "+310612345"
}
}
ViewLocation
Supported by: RCS
When you want to share a location, you can send this message. When the user receives it it opens the navigation app of the user with a pin at the specified location.
ViewLocation | A view location object |
View location objects contains the following fields:
Latitude (optional) | The latitude in degrees |
Longitude (optional *1) | The longitude in degrees |
SearchQuery (optional *1) | Search for this location instead of using the latitude/longitude |
Label (optional) | The label to display at the pin |
1. Either the search query or the latitude & longitude are required! |
{
"action": "viewLocation",
"viewLocation": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ"
},
"label": "Open in maps"
}
Reply
Supported by: RCS, Twitter, Facebook Messenger, Instagram
Use this suggestion if you want to suggest responses to the user. When the user clicks on a Reply
suggestion, the label text is automatically sent back as a response.
- The
description
field is only supported by Twitter. - The
postbackdata
field is required by Facebook Messenger, and Instagram (1000 character limit). - The
media
object is only supported by Facebook Messenger (thumbnail image).
{
"action": "Reply",
"label": "Make an appointment",
"description": "Doctor",
"postbackdata": "Data sent back in an MO",
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}
Login
Supported by: Facebook Messenger
Use this suggestion if you may want to identify the user as a customer who already has an account with your business.
This will suggest a login button that let you link the recipients identity on the channel, like Facebook Messenger, with your site by directing them to you web-based login flow for authentication.
URL | Authentication callback url the end user can use for login |
{
"action": "Login",
"url": "https://www.example.com/authorize"
}
Logout
Supported by: Facebook Messenger
Use this suggestion if you want to provide an unlink account option, can only be used if Login action has been used by the user before.
The recipient identity on the channel, like Facebook Messengger, will remove the link with your website provided during the Login suggestion.
{
"action": "Logout"
}
ViewProduct
Supported by: Facebook Messenger
Use this suggestion if you want to render a marketable product that's linked to your product catalog.
Product | A marketable product object |
The product object contains the following fields:
Id | Unique catalog ID provided by channel |
{
"action": "ViewProduct",
"product": {
"id": "FB_tshirt_001"
}
}
References
When you have sent out a notification and want to link that to incoming information you can connect those via REFERENCES.
Responses & Errors - JSON
The responses and errors for JSON can be found on https://developers.cm.com/messaging/docs/responses-errors-json.
Updated 30 days ago