The CM.com Business Messaging API enables you to send messages from your system to mobile phones all around the world. This RESTful API is the main interface between your application and the CM Platform and can be implemented to communicate via various communication channels - among others SMS, WhatsApp, RCS and Viber. We accept single messages, but also very high volumes. Core capability of this API is that it can cope with various communication channels and high throughput. The HTTP protocol is used, examples can be found in JSON and XML, though we advise to use JSON.
To make use of our API for SMS, you need to be registered at CM.com and have your billing details set in your CM Wallet. This can be recurring billing via credit card (self service), or via alternative payment methods (signed business contract required).
In order to make use of communication channels like WhatsApp, Viber, or RCS, you are required to have access to the programs. This can be requested via CM.com and we will help you with the verification and activation when your request meets the terms and conditions of these additional services. For this too a billing account is required.
During the implementation you might have questions and we kindly refer to our Help Center documents to get more background information.
We have built our API in such away that you can use it for various communication channels. Currently we support:
Please be aware when using channels other than SMS, CM needs to have configured the outgoing flows before you can use them. If you want to force the use of one channel or several specific channels, it is necessary to include which channel in the request.
Each channel comes with it's own rules and regulations from service providers and governments alike. You are responsible for following the rules and regulations for each channel that you use. Failure to do so might result in immediate termination of the service.
Several SDKs are available to get you started with your API integration.
Our global gateway is accessible via one end point which we are load balancing over 2 platform locations in The Netherlands. To reduce latency, and/or be compliant to local legislation we also have platforms in London, South Africa and Shanghai. More information can be found in our Help Center.
https://gw.cmtelecom.com/v1.0/messagehttps://gw.cmtelecom.co.za/v1.0/messagehttps://gw-cn.cmtelecom.com/v1.0/messagehttps://gw-hk.cmtelecom.com/v1.0/messagehttps://gw-uk.cmtelecom.com/v1.0/messageOur API supports sending messages via HTTP. You can send a POST request containing a JSON or XML body. We strongly advice that you use JSON. The newer communication channels like RCS, WhatsApp and Viber are only supported via JSON. Information and examples about XML, SMPP and GET can be found at the end of our API documentation.
All requests require your product token which, as a registered user, you can find 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.
Communication with the CM servers should be done using the TLS cryptographic protocol, version 1.1 or higher. Older security protocols such as TLSv1.0 and SSLv3 are not supported.
When making use of the WhatsApp Business API solution messages are encrypted on our platform. In our WhatsApp implementation guide we explain how this works. Encryption is a mandatory WhatsApp feature, implemented by CM.com. You don't have to do anything to enable this, it is part of the the WhatsApp account creation.
When implementing communication channels like WhatsApp, that allow conversations with for instance a Bot or Service employee, there will be data flows from your systems (outbound/outgoing) as well as data which needs to be sent to your systems (inbound/incoming/MO).
To receive incoming messages (MO), you need to set a webhook and map the incoming API in your system. More information can be found in the API documentation of the Inbound webhook
Below is an example of a Viber message:
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Message Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "TestSender",
"allowedChannels": ["Viber"]
}]
}
}| 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 Business Chat, 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 Business Chat and WhatsApp, or Twitter. The default is to allow any channel configured for your account. |
No |
Please note that the
msg,toandallowedChannelsobjects are arrays and can contain multiple values. Using multiplemsgortoelements 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.
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:
Not adhering to this convention might cause incorrect delivery!
The phone number of our office in The Netherlands is +31 (0)76 - 572 70 00
What we would enter via API: 0031765727000
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"
}
}
]
}
}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:
If you would like to make use of fallbacks, please contact CM.com to configure multi channel routing for your account.
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 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.
You should limit the number of unique custom groupings to 1000.
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"
}
]
}
}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 72 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:
If no time zone was specified, CE(S)T will be used. (CM local time)
Relative offset in hour (H) or minute (M)
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.
Supported by: WhatsApp, RCS, Viber, Twitter
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 |
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.
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/jpg"
}
}]
}
}]
}
}| 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 | ABC | Viber | RCS | SMS | ||
|---|---|---|---|---|---|---|
| Text | √ | √ | √ | √ | √ | √ |
| - Clickable URLs | √ | √ | √ | √ | x | √ |
| - Text formatting | √ | x | x | x | x | √ |
| - URL previews | √ | √ | x | x | x | √ |
| Media | √ | √ | √ | √ | x | √ |
| - Image | √ | √ | √ | √ | x | √ |
| - Video | √ | √ | x | √ | x | √ |
| - Audio | √ | √ | x | √ | x | x |
| - Rich card | x | x | √ | √ | x | x |
| - Rich card carousel | x | x | x | √ | x | x |
| Location | √ | x | x | √ | x | x |
| Contact | √ | x | x | x | x | x |
| Template | √ | x | x | x | x | x |
| List picker | x | √ | x | x | x | x |
| Time picker | x | √ | x | x | x | x |
| OAuth2 | x | √ | x | x | x | x |
| Custom app | x | √ | x | x | x | x |
| Payment | 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.
Supported by: RCS, Viber, ABC, Twitter
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 |
Depending on the action, certain additional fields are expected to complete the user flow.
Supported by: RCS, Viber, ABC
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"
},
{
"action": "OpenUrl",
"url": "https://docs.cmtelecom.com/en/api/business-messaging-api/1.0/index/",
"label": "SMS documentation"
}
]
}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"
}
}Supported by: RCS
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",
"dial": {
"PhoneNumber": "+310612345"
}
}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"
}Supported by: RCS, Twitter
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.
{
"action": "Reply",
"label": "Make an appointment",
"description": "Doctor"
}When you have sent out a notification and want to link that to incoming information you can connect those via REFERENCES.
When sending a request with an invalid msg part to the JSON gateway, it will continue to check the other to objects and msg objects available and send the correctly formatted values. In the JSON response, you can find details per message. With each message you receive the PhoneNumber of the failed message (if present), the accepted or rejected status, your reference for the message (if present), the amount of message parts we created for that message, and a description why the message was rejected (if present).
Acceptance by the gateway (aka receiving errors) is not the same as actual delivery of a message. Delivery is done asynchronously and as such you can only receive information about delivery status via the status report webhooks.
Examples of responses of failed JSON requests:
Entire request incorrect:
Status: 400 Bad Request
{
"details": "No account found for the given authentication",
"errorCode": 101, //See table "JSON POST Error codes" below
"messages": []
}Incorrect msg and a correct message:
Status: 200 OK
{
"details": "Created 1 message(s)",
"errorCode": 201, //See table "JSON POST Error codes" below
"messages": [
{
"to": "00447911123456",
"status": "Accepted",
"reference": "your_reference_A",
"parts": 1,
"messageDetails": null,
"messageErrorCode": 0 //See table "JSON POST Error codes" below
},
{
"to": "00447911123457",
"status": "Rejected",
"reference": "your_reference_B",
"parts": 0,
"messageDetails": "A body without content was found",
"messageErrorCode": 304 //See table "JSON POST Error codes" below
}
]
}All incorrect:
Status: 400 Bad Request
{
"details": "Created 0 message(s)",
"errorCode": 201,
"messages": [
{
"to": "0044791112345a",
"status": "Rejected",
"reference": "your_reference_A",
"parts": 0,
"messageDetails": "Gsm '0044791112345a' is not a number.",
"messageErrorCode": 303 //See table "JSON POST Error codes" below
},
{
"to": "00447911123456",
"status": "Rejected",
"reference": null,
"parts": 0,
"messageDetails": "A body without content was found",
"messageErrorCode": 304 //See table "JSON POST Error codes" below
}
]
}NOTE: The XML gateway and JSON gateway have different output, and respond differently based on the error. For XML responses, please see the section on XML communication.
| HTTP status | Error text | Remarks |
|---|---|---|
| 405 | (none) | No HTTP GET or POST was used to send your request |
| 500 | "details": "Unknown Error" | An unexpected error occurred. Check the provided values. Contact CM for support. |
| 400 | "details": "No account found for the given authentication" | No account found for the provided product token. |
| 400 | "details": "Insufficient balance." | Trial accounts only: You are out of trial messages. Order new messages via your dashboard. If you are a regular prepaid customer, you will be notified that you have run out of quota in a Status Report. |
| 400 | "details": "Message is unroutable." | Your request could not be routed. Contact CM for support. |
| 400 | "details": "Invalid product token." | Invalid or missing product token |
| 400 | "details": "A MESSAGES object requires at least one MSG object" | A MSG object within the MESSAGE object is required and is missing. |
| 400 | "details": "Invalid JSON" | The given JSON is malformed. Please validate your JSON syntax and try again. |
| 200 | "details": "Created [x] message(s)" | An [x] amount of messages have been accepted. See the messages objects for further details. |
| - | "messageDetails": "No FROM field found in a MSG object." | The ‘FROM’ element is missing within the ‘MSG’ element |
| - | "messageDetails": "Empty mobilenumber field, MT ignored" | The Phone Number value for the TO element is missing |
| - | "messageDetails": "Rejected: Gsm '[msisdn]' is not a number." | The value for the TO element is not a valid Phone Number |
| - | "messageDetails": "[Object] object is an invalid type, must be an array" | The stated [Object] should be an array. Even if this contains one element. |
| - | "messageDetails": "No body field was found" | The ‘BODY’ element is missing within the ‘MSG’ element |
| - | "messageDetails": "A body without content was found" | The ‘BODY’ element is missing ‘CONTENT’ |
| Error code | Description |
|---|---|
| 0 | Ok |
| 999 | Unknown error, please contact CM support |
| 101 | Authentication of the request failed |
| 102 | The account using this authentication has insufficient balance |
| 103 | The product token is incorrect |
| 201 | This request has one or more errors in its messages. Some or all messages have not been sent. See MSGs for details |
| 202 | This request is malformed, please confirm the JSON and that the correct data types are used |
| 203 | The request's MSG array is incorrect |
| 301 | This MSG has an invalid From field (per msg) |
| 302 | This MSG has an invalid To field (per msg) |
| 303 | This MSG has an invalid Phone Number in the To field (per msg,) |
| 304 | This MSG has an invalid Body field (per msg) |
| 305 | This MSG has an invalid field. Please confirm with the documentation (per msg) |
| 401 | Message has been spam filtered |
| 402 | Message has been blacklisted |
| 403 | Message has been rejected |
| 500 | An internal error has occurred |
Please note that there are a few limitations to using unicode encoded messages:
It is possible to let our gateway detect the encoding for you by including the type: auto setting. In case it detects characters that are not part of the GSM character set, the message will be delivered as Unicode. Any existing DCS value will be ignored. If the message contains more than 70 characters in Unicode format it will be split into a multipart message. You can limit the number of parts by setting the maximum number of message parts (see also the section on Multipart below).
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["SMS"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"minimumNumberOfMessageParts": 1,
"maximumNumberOfMessageParts": 8,
"body": {
"type": "auto",
"content": "Κείμενο διαθέσιμο σε όλες τις γλώσσες"
}
}
]
}
}By default our gateway interprets SMS messages as if sent with the standard 7 bit GSM encoding. You can use the DCS (data coding scheme) parameter to indicate the type of message you are sending. If you set DCS to '0' or do not include the parameter, the messages uses standard GSM encoding. If you want to send messages using e.g. Arabic, Cyrillic of Greek characters you will need to use the unicode UCS2 encoding. To set your message up for unicode messaging include <DCS>8</DCS> in your <MSG>-element, or if you're using JSON "dcs": 8 in a msg object. See the examples below.
View the Unicode paragraph for more information.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["SMS"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"dcs": 8,
"body": {
"content": "Κείμενο διαθέσιμο σε όλες τις γλώσσες"
}
}
]
}
}When your message is longer than 160 characters (or 70 when it contains unicode characters), we call such a message a multipart or concatenated message. The gateway will first check if an SMS is bigger than 160 (or 70) characters, and if so the message will be cut into multiple parts.
Please note that there are a few limitations to using multipart messages:
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": ["SMS"],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"minimumNumberOfMessageParts": 1,
"maximumNumberOfMessageParts": 8,
"body": {
"content": "Using these settings we can send SMS messages that contain more than 160 characters as if it is one message. Please do note that this limits the length of one message to 153 characters."
}
}
]
}
}This chapter of our API Documentation is designed for customers who have been granted access to WhatsApp Business API. It is important that you request access to this program via our Channels portal. Without this approval you can not make use of this part of the API.
WhatsApp also comes with a considerable set of 'business rules' that you might have to take into account when using WhatsApp. Be sure to read our Implementation guide and its Rules and Regulations
Note: since WhatsApp for Business is used for 2-way communication (chat) it is important to also implement the Inbound flow using our API documentation of the Inbound webhook.
When making use of the WhatsApp Business API solution, messages are encrypted on our platform. In our WhatsApp implementation guide we explain how this works. Encryption is a mandatory WhatsApp feature, implemented by CM.com. You don't have to do anything to enable this, it is part of the the WhatsApp account creation.
For service requests, users usually initiate a conversation and will reach out to you. To link incoming messages to your outbound messages, the phone number field is used.
An example of sending a message via WhatsApp by specifying allowedChannels with a WhatsApp value. This example makes use of the Rich Content conversation array, with 3 conversation items (or speech bubbles), 2 text bubbles and one image. These will all be deliverd at once.
The body's content attribute is also required. It is the content value that will be used when falling back to SMS as a delivery channel. The body.content attribute needs to be backwards compatible with SMS channel requirements. This means it is affected by maximum size limitations of SMS as described in the section on SMS multipart messaging.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Fallback Text for SMS"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"text": "A text message with *bold* formatting in a speech bubble."
}, {
"text": "Another speech bubble"
}, {
"media": {
"mediaName": "and an image",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
}]
}
}]
}
}**Note:*** The WhatsApp protocol strives for, but does not guarantee, in-order delivery of your messages.
If you have configured multiple WhatsApp-numbers in our platform, you can use the desired phone number by providing it in the from field.
If this does not match to one of your phone numbers, your first onboarded number will be used.
Example:
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Message Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"]
}]
}
}Text messages are and should always be encoded in UTF-8 and do support characters like emojis 😀. This is true for both the body field and when using a text item inside a Rich Content conversation. Please remember that emoji rendering is device dependent and older devices therefore may not support the newest unicode emojis and depending on the font used by the device, an emoji may look slightly different on from one device to another 📱💻🖥.
The maximum length of a WhatsApp text message bubble is 4096 characters.
WhatsApp specifically allows a limited amount of formatting for text messages that you can make use of. These markup characters need to be prefixed with a space character in order for them to take effect.
| Formatting | Symbol | Example |
|---|---|---|
| Bold | Asterisk (*) | Your total is *$10.50*. |
| Italics | Underscore (_) | Welcome to _WhatsApp_! |
| Tilde (~) | This is ~better~ best! | |
Code |
Three backticks (```) |
```print 'Hello World';``` |
A line break can be inserted by using: \n
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"text": "A text message with *bold* formatting in a speech bubble."
}, {
"text": "Another speech bubble"
}]
}
}]
}
}Any URLs present in the message text of a WhatsApp message will be automatically recognized by the clients as links. Additionally, the first URL encountered in a text message will generate a URL preview. For this it is required that the URL starts with http:// or https://
A URL preview can contain a title, a message and a small fragment of text. These elements are automatically retrieved from the destination website. To support this preview, the destination website needs to have implemented the Open Graph Protocol.
The URL preview is retrieved by the WhatsApp software running on the CM.com side, before being sent to the client. This is for privacy reasons.
To send a message to a user first a template must be used. These templates must be setup and approved before they can be used. You can request templates via the Channels portal. Once a template is approved you can use the template namespace and name to send a message (Use the details button in your template overview to find these values).
The template message must have the exact same number of variables as the template has. The same template can be set-up in multiple languages, hence you also need a language parameter.
Please remember that a user must have opted in for the type of communication as well. The opt-in must be an active opt-in. This means it must be triggered by a user action, such as entering a phone number in a WhatsApp field or checking a box to indicate consent.
See also Facebook's opt-in guide.
A template object contains a 'whatsapp' object, which corresponds to the template object in the WhatsApp for Business docs.
| Field | Description | Required |
|---|---|---|
| namespace | The namespace that will be used, will be provided to you after the template is approved | Yes |
| element_name | The element name of the template that will be used, will be provided to you after the template is approved | Yes |
| language | Specifies the language, see below for object definition | Yes |
| components | Array containing the content-components of the message, to personalize the templated message. See the WhatsApp documentation for advanced details. | Yes (only for media templates) |
| localizable_params | An array of parameters to personalize the templated message. Use components if your template needs media or has a header/footer. See the WhatsApp documentation for advanced details. |
Yes (only for regular templates) |
Media templates is a newer generation of WhatsApp templates, which in addition to the text body, can also feature a header with an additional image, video or document, as well as a footer.
The header can have three component types: image, document, video and text. The body and footer can only have the component type text. The parameters are similar to the localizable_params of the older template format, but NOT the same.
See the WhatsApp documentation for advanced details.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [{
"from": "00316098765432",
"to": [{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation":
[{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "replace-value-1"
},
{
"type": "currency",
"currency" : {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33, // OR
"timestamp": 1485470276
}
},
]
}
]
}
}
}]
}
}]
}
}
Interactive templates is a newer generation of WhatsApp templates, which in addition to the media template, can also support button-components.
The button-component can be either of sub_type: quick_reply or url.
quick_reply the end-user will see a suggestion to respond with. The button text itself has to be specified during creation of the template.url you are able to send a Call-to-action button. This can be a phone number to call, or an url to visit. This has to be specified during creation of the template as well.The payload on quick_reply buttons will be sent back when an end-user interacts with such a button. This will be explained in the MO documentation.
See the WhatsApp documentation for advanced details.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [{
"from": "00316098765432",
"to": [{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation":
[{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
}
]
},
{
"type": "button",
"sub_type" : "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
// Business Developer-defined payload
"payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "1",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "9rwnB8RbYmPF5t2Mn09x4h"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "2",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}]
}
}
}]
}
}]
}
}
This is the template message format without media. See also the WhatsApp documentation for advanced details.
The hsm-templates that use the localizable_params-structure, will be deprecated in a future version.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [{
"from": "00316098765432",
"to": [{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation":
[{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33
}
},
{
"type": "date_time",
"date_time" : {
"fallback_value": "February 25, 1977",
"timestamp": 1485470276
}
}
]
}]
}
}
}]
}
}]
}
}
| Field | Description | Required |
|---|---|---|
| policy | deterministic — Deliver the message template in exactly the language and locale asked for.fallback — deprecated Deliver the message template in the language that matches user's language/locale setting on device. If one can't be found, deliver using the specified fallback language. |
Yes |
| code | The code of the language or locale to use — Accepts both language and language_locale formats (e.g., en and en_US). | Yes |
WhatsApp maintains a list of valid language codes
Note: Please note that the fallback language policy will be deprecated by WhatsApp in January 2020 and the deterministic language policy will become the default policy.
In WhatsApp the following media types are supported:
| Type | Supported file types | to send |
|---|---|---|
| image | JPG, JPEG, PNG | image/jpeg, image/png |
| video | MP4 (see notes) | video/mp4 |
| audio | AAC, M4A, AMR, MP3, OGG OPUS | audio/aac, audio/m4a, audio/amr |
| audio/mpeg, audio/ogg; codecs=opus | ||
| document | PDF, DOC(X), PPT(X), XLS(X), etc | Any valid MIME-type |
Notes:
Media object contains the following fields:
| Term | Description |
|---|---|
| MediaName | The filename for a document, or the caption of the image or video (not supported for audio). |
| MediaUri | The location of the image, audio or video. The Uri should return a correct Content-Type header |
| MimeType | The mime type of the image, audio or video. |
{
"conversation": [
{
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
}
]
}As data usage costs might apply when the end user is not on Wifi, please be considerate when sending media messages. We strongly advise not to send files larger than 1 MB, and for a conversation not to exceed 20Mb.
To send a location to a user use the location object, which contains the following fields:
| Latitude | The latitude in degrees |
| Longitude | The longitude in degrees |
| SearchQuery | The address to display |
| Label | The label to display at the pin |
Example
{
"conversation": [
{
"location": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ",
"searchQuery": "Konijnenberg 30"
}
}
]
}To send one or more contacts to a user use the Contacts array, which contains the fields described in WhatsApp for Business docs.
Note that the name.formatted_name and at least one of: name.first_name, name.last_name, name.middle_name, name.suffix, name.prefix is required.
Example
{
"conversation": [
{
"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"
}
}
]
}
]
}This chapter of our API Documentation is designed for customers who have been granted access to Apple Business Chat (ABC). It is important that you request access to this program via our our Channels portal. Without this approval you can not make use of this part of the API.
Apple Business Chat has a considerable set of 'business rules' that you might have to take into account when using Apple Business Chat.)
Note: since Apple Business Chat is used for 2-way communication (chat) it is important to also implement the Inbound flow using our API documentation of the Inbound webhook.
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 ABC-identifier value.
An ABC-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.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "CM.com - Be part of it."
},
"to": [{
"number": "ABC-identifier"
}],
"from": "TestSender",
"allowedChannels": ["Apple Business Chat"]
}]
}
}Text messages are and should always be encoded in UTF-8 and do support characters like emojis. This is true for both the body field and when using a text item inside a Rich Content conversation.
There is no official maximum length of an Apple Business Chat message bubble, but up to 4096 characters is known to work. After 1024 characters, the user has to click the message to be able to read the full contents.
Any URLs present in the message text of a Apple Business Chat message will be automatically recognized by the clients as links. Additionally, if a message starts or ends with a URL (and begins with http:// or https://), the URL will be split off from the rest of the message and delivered as "preview url" bubble. A URL in the middle of a message will not generate a URL preview. The URL preview is retrieved by the software running on the device of the end user. For privacy reasons the preview is only generated after the consumer clicks "Tap to load Preview".
A URL preview can contain a title, a message and a small fragment of text. These elements are automatically retrieved from the destination website. To support this preview, the destination website needs to have implemented the Open Graph Protocol.
In order to have a preview image (or even preview video) without requiring the consumer to manually load it, make use of an OpenUrl suggestion instead.
Apple Business Chat supports all media types that the iPhone itself supports.
Notes:
Media object contains the following fields:
| Term | Description |
|---|---|
| MediaName | The filename of the file, including file extension |
| MediaUri | The location of the image, audio or video. |
| MimeType | The mime type of the image, audio or video. |
{
"conversation": [
{
"media": {
"mediaName": "conversational-commerce.jpg",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
}
]
}As data usage costs might apply when the end user is not on Wifi, please be considerate when sending media messages. We strongly advise not to send files larger than 1 MB, and for a conversation not to exceed 20Mb.
Suggestions allow you to request the end user to take an action and you will receive the result of that action via the MO webhook.
Suggestions currently supported for our Apple Business Chat Channel are: OpenUrl, Pick, Payment.
Suggestions for Apple Business Chat are specific per conversation part and thus included inside the conversation item, instead of at the richContent level as with RCS and Viber.
Sending a message with a Url action and a preview of the URL. With this method users do not have to click "Tap to preview". You can add text, a label, the url and media items to your conversation part.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [
{
"richContent": {
"conversation": [{
"text": "CM.com - Be part of it.",
"suggestions": [
{
"action": "OpenUrl",
"label": "CM.com - Be part of it.",
"url": "https://www.cm.com/products/talk/",
"media": {
"mediaName": "cm-com.png",
"mediaUri": "https://www.cm.com/cdn/cm/cm-com.png",
"mimeType": "image/png"
}
}
]
}]
},
"body": { "content": "CM.com - Be part of it." },
"from": "CM Test",
"to": [
{ "number": "ABC-identifier" }
]
}
]
}
}With a list picker you can present a button in the conversation that when clicked presents a list of options to the users. These lists can have labels and a media thumbnail.
NOTE: Don't send images that are exceptionally large as the download time, may influence the time it takes to present the options to the user.
When the user makes a choice the response will be sent back to you via the MO webhooks.
{
"conversation": [
{
"text": "Magic trick",
"listpicker": {
"label": "Please, pick a card",
"media": {
"mediaUri": "https://static.thenounproject.com/png/393234-200.png"
},
"options": [
{
"label": "Ace of Hearts",
"media": {
"mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.N7zZqoCvjxZZvwp2Zi1UVwHaH6%26pid%3D15.1&f=1"
}
},
{
"label": "Ace of Spades",
"media": {
"mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.pixabay.com%2Fphoto%2F2013%2F07%2F12%2F12%2F01%2Fsuit-of-spades-145116_960_720.png&f=1"
}
},
{
"label": "Ace of Diamonds",
"media": {
"mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.pixabay.com%2Fphoto%2F2012%2F05%2F07%2F18%2F37%2Fsuit-48941_960_720.png&f=1"
}
},
{
"label": "Ace of Clubs",
"media": {
"mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2Fthumb%2F8%2F8a%2FSuitClubs.svg%2F709px-SuitClubs.svg.png&f=1"
}
}
]
}
}
]
}The text element of the message will be shown in the message, the label element in the list picker will be shown in the list picker.
With a time and date picker you can present a button in the conversation that when clicked presents a list of time and dates to the user to pick from. This is a good method to plan meetings and/or delivery times.
When the user makes a choice the response will be sent back to you via the MO webhooks.
In order to setup a time picker, you submit a timePicker object with an options array containing the suggested date and time slots for the user to pick from. Optionally you can add a label and location which will be used when an end users add the appointment to the calendar.
"conversation": [
{
"text": "Click here to pick a time.",
{
"timePicker": {
"label": "Appointment at CM HQ",
"location": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ"
},
"options": [
{
"startTime": "2020-02-21T09:00",
"endTime": "2020-02-21T10:00"
},
{
"startTime": "2020-02-22T09:00",
"endTime": "2020-02-22T10:00"
},
{
"startTime": "2020-02-23T09:00",
"endTime": "2020-02-23T10:00"
}
]
}
}
}
]Note that the start time must always be in the future.
It is possible to do an OAuth 2 authentication within a conversation. Using the OAuth2 authentication prompt, you can ask a user to login via a 3th party website. Authentication results are received via the MO webhooks.
The 3th party must be configured in the Apple Business Chat account on the Apple Business Register.
"conversation": [
{
"oauth2": {
"responseType": "token",
"state": "3a77fc39-ac33-404f-896a-e0fad171a343",
"responseEncryptionKey": "SOME LONG ENCRYPTION KEY",
"clientSecret": "SOME CLIENT SECRET",
"scope": ["email","profile","openid"]
}
}
]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 Business Chat integrations than this is possible as well. Again, please contact our support team.
Our business messaging API supports sending and receiving Twitter direct messages.
Being able to send Twitter direct messages requires requesting access via the Channels portal. Without onboarding with Twitter via the portal, you can not make use of this part of the API.
| Feature | Support | Remarks |
|---|---|---|
| encryption | yes | There is no end-to-end encryption. However, messages are transmitted over the public Internet using https |
| delivery notification | yes | Occurs when your message is delivered to the Twitter platform. Delivery notifications are sent to the status report webhooks. |
| text messages | yes | The maximum length of a Twitter direct message is 10.000 characters. |
| urls in text | yes | |
| media | yes | Media name attribute should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own Twitter message. When the linked media doesn't exist/can't be found, the message will not be sent at all. |
| media: images | yes | Maximum file size for an uploaded image is 5 MB. Supported MIME types are image/jpg, image/jpeg, image/png, image/webp. |
| media: gifs | yes | Maximum file size for an uploaded GIF is 15 MB. Supported MIME types are image/gif. |
| media: video | yes | Maximum file size for an uploaded video is 512 MB. Supported MIME types are video/mp4, video/quicktime. |
| read receipts | yes | Read receipts are sent to the status report webhooks. |
| Reply suggestions | yes | Maximum label length: 36 characters. |
Onboarding is done via our Channels portal. Via our portal, you are redirected to the authorization page of Twitter. On this page you will need to authorize our Twitter app, called CM Business Messaging API to send and receive Direct Messages on behalf of your Twitter account.
Sending Twitter DMs using the CM Business Messaging API also requires you to adhere to the Twitter rules.
An extended set of rules and policies for Twitter messages can be found here.
It is allowed to have multiple Twitter accounts under one CM.com account.
Note that in case of Twitter, the Twitter account that is used for sending messages is also still available in the regular Twitter app, from the Twitter website and from other 3rd party Twitter apps. Our API only has permissions to send on behalf of the Twitter account, but it's not exclusively in control of that Twitter account.
This means that it will be possible to send messages using Twitter as well as using our API, and that might lead to situations where the API will relay replies to messages you sent via the Twitter app or website.
In those cases it will seem like messages are missing from a conversation when you use both ways of communicating with your end-users.
Our recommendation is to use the API exclusively for these Twitter accounts, and not switch between the Twitter app or website and the API, because the API won't "know" about the messages you sent using the app or website, but it will receive the replies to those messages.
In your Twitter account, make sure you have enabled "Receive messages from anyone", found under Settings...Privacy and safety...Receive messages from anyone. If you don't enable this, end-users won't be able to message you and start a conversation.
There are two ways you can start a conversation with a Twitter end-user yourself;
if the end-user follows your Twitter account.
In other cases the only way to start a Twitter conversation with end-users is when the end-user starts the conversation by sending you an initial message.
When a message is received from an end-user, you may send up to 5 messages in response within a 24 hour window. Each message received resets the 24 hour window and the 5 allotted messages. Sending a 6th message within a 24 hour window or sending a message outside of a 24 hour window will count towards rate-limiting.
Unlike other channels, Twitter does not use telephone numbers as identifiers for sender (from) and recipient (to.number), instead it uses so called "snowflakes", which are unique identifiers of the twitter accounts (e.g. the Twitter account @cmchanneldev has the snowflake 1263071591262494721).
The snowflake is a 64-bit unsigned integer, and is visible in the CM.com platform as the userid under channels...Twitter.
You can also find it in Twitter itself, under Settings... Privacy and safety... Personalization and data... See your Twitter data... Account. It should be listed behind "User ID".
If you send a message including both an image and some text, Twitter will display this as one entity, always placing the text below the image, and “joining” the two visually.
It is possible to have the text above the image by sending two seperate conversations in a single API call; Twitter will then display them in order, but the text is not visually joined with the image.
See the Direct message with text and image example.
Since Twitter Direct Messaging is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Twitter you need to set up your webhook API in the Channels app, not in the Gateway app.
Please note that currently we only support snowflakes when sending and receiving Twitter direct messages. An upcoming version of the API might also allow for using Twitter handles, but please note that a Twitter user may change their handle at any point in time, while the Twitter snowflake will remain the same for each individual account. Therefore, we would recommend using snowflakes as identifiers to prevent problems matching users to messages in your system.
The example below will send a simple text-only Twitter direct message.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your snowflake",
"to": [
{
"number": "Recipients Snowflake"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Twitter"],
"body": {
"type": "auto",
"content": "CM.com - Be part of it."
}
}
]
}
}In the example below we send a simple rich content message that contains both text and an image that Twitter will display as one entity. An explanation on how to send rich content messages in general can be found in the rich content description.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your snowflake",
"to": [
{
"number": "Recipients Snowflake"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Twitter"],
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaName": "conversational-commerce.jpg",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
}
]
}
}
]
}
}In the example below we send a rich content message that contains a text and some reply suggestions. An explanation on reply suggestions can be found under Suggestions/Features under Rich Content
NOTE: Twitter only supports suggestions with
"action": "Reply"
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your snowflake",
"to": [
{
"number": "Recipients Snowflake"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Twitter"],
"richContent": {
"conversation": [
{
"text": "Hi, what can I do for you?",
"suggestions": [
{
"action": "Reply",
"label": "Create an appointment"
},
{
"action": "Reply",
"label": "Change my appointment"
},
{
"action": "Reply",
"label": "Cancel my appointment"
}
]
}
]
}
}
]
}
}An alternative for SMS, is RCS. To deliver the message also telecom operators are being used, though now you can send rich content instead of pure text messages. Unfortunately RCS is not yet available in each country. When you would be interested to learn more, and get access to resources to assist with the set-up please contact us via our RCS Business Messaging product page.
We are working on updating our RCS documentation.
Viber is growing in popularity and besides transactional messaging also offers the possibility to send marketing messages. Our platform offers you several other tools and products that you can freely use, also with Viber as communication channel. Examples here are our Analytics, Customer Contact application and Campaign tooling. Viber is secure communication via end-to-end encryption. Please be aware that Viber needs verify the legitimacy of your business and your rational for use. You can request access via our website.
Viber supports the conversation items: text and media (images only) as well as the openUrl suggestion. If you would like to send locations or date indicators you can include these in the text message and the phone will interpret those.
When you use suggestions, the last conversation item in your conversations array should be a text conversation item. Without adhering to this restriction, your message will not be delivered.
Sending an image and text within a single conversation item is not supported, using multiple conversation items for each type is required.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Fallback text"
},
"richContent": {
"conversation": [
{
"media": {
"mediaName": "viber-example.png",
"mediaUri": "https://www.cm.com/cdn/web/viber-message-festival.png",
"mimeType": "image/png"
}
},
{
"text": "Viber message text"
}
],
"suggestions": [
{
"action": "Openurl",
"label": "Visit cm.com",
"url": "https://www.cm.com"
}
]
},
"to": [{
"number": "00316012345678"
}],
"from": "TestSender",
"allowedChannels": ["Viber"]
}]
}
}NOTE: For now, always use API endpoint gw.cmtelecom.com when using Viber.
Hybrid Messaging is an intelligent way to deliver phone number based messages via Push or SMS through the existing CM Messaging gateway when your preferred option did not work.
Prerequisites:
The example request below has the allowed channel "Push". This means the message will be restricted to only taking "Push" routes.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"body": {
"type": "auto",
"content": "This message defines allowed channels"
},
"allowedChannels": ["Push"],
"appKey": "00000000-0000-0000-0000-000000000000"
}
]
}
}This example request will first attempt to deliver a message using Push messaging but will fallback to SMS if the Push message cannot be delivered for any reason.
{
"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg": [ {
"allowedChannels": [
"Push",
"SMS"
],
"from": "SenderName",
"to": [{
"number": "00447911123456"
}],
"appKey": "00000000-0000-0000-0000-000000000000",
"body": {
"type": "auto",
"content": "This message will be delivered as a push message."
}
}
]
}
}NOTE: Status report webhooks are currently only available in XML format. JSON webhooks will be available later in 2020.
Once you have sent out messages via our Business Messaging API, you might want to receive status updates in return. These status updates can inform you about: how successful a campaign has been, who has received your message, or in case of failure, when a fallback has been applied. You can view the status updates on the CM-platform's messaging log or receive those statuses in your own system via a webhook.
There are no additional cost to use either one. The Messaging platform has the option to communicate with a web server whenever a message updates its status. The status reports will be communicated using an HTTP POST request.
Note: Status reports sent towards an API/Webhook will be considered as not delivered when a non-successful response code is returned. Our services will temporarily hold the information and retry the delivery periodically for a maximum of 7 days. Status information will remain available through the Messaging Log.
You can configure your status report webhook for SMS in the 'Messaging Gateway'-app. Please refer to this article in our Help center for more information. When configuring the webhook URL, you must ensure this URL returns HTTP status code 200(OK) on the test call we make. If our call to the webhook fails, we will not use the provided URL.
| Name | Format | Description |
|---|---|---|
| Created | Datetime | The moment when the status report was registered on CM.com's platform |
| Send | Datetime | The moment when the status report was sent to customer's/your endpoint |
| To | String | The recipient of the message, such as the telephone number of the message recipient or another identifier |
| Status | Integer | The code describing the current state of the message. 0 = accepted by the operator 1 = rejected by CM or operator 2 = delivered 3 = failed (message was not and will not be delivered) 4 = Read (Not for SMS, only other channels) |
| Standard Error | String | The description of the error if the message is in an error-state |
| Status Description | String | The description of the current state of the message |
| Channel | String | The used communication method via which the status report was received – ie. sms, whatsapp, viber. |
| Operator | String | The Mobile Operator of the recipient - if relevant |
| Reference | String | The message reference which can be provided by the customer in the outbound message (see business messaging API) |
| CustomGrouping CustomGrouping2 CustomGrouping3 |
String | The custom groupings set for this Outbound Message (MT) (see business messaging API) |
Note:
read implies it was delivered, even if you never received a report with status delivered. Similarly in some rare cases a status can become failed even after having received a previous status delivered. The reason for this is optimization by the various channel providers.Clients can use SMPP to deliver and receive mobile terminated (MT) messages, mobile originated (MO) messages and delivery reports (DLR messages) to and from the CM SMS gateway. CM supports SMPP protocol version 3.4. If you would like to get the South African SMPP settings, please reach out to your Account Manager.
Delivery receipts are sent in the short_message field of a deliver_sm or the message_payload TLV of a data_sm PDU, as per account configuration. In both cases, the message state is available as a message_state TLV attached to the PDU as well as in the actual receipt. Use whichever is more convenient.
The following format is used:
id:IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII submit date:yyyyMMddHHmmss done date:yyyyMMddHHmmss stat:SSSSSSS err:EEEThe number and order of fields is fixed, and they are separated by a single ASCII space. It is unwise to depend on this, however; for extendibility, you should not assume any number or ordering of fields and accept arbitrary whitespace as separator.
Similarly, though sizes are specified, strings not of fixed length may vary in size -- the specified size only reflects the maximum returned size as currently implemented. In no case will the total message length exceed 255 characters, however.
| Field | Size | Type | Description |
|---|---|---|---|
| id | 32 | string | The message ID allocated to the message by the SMSC when originally submitted. |
| stat | 7 | Fixed length string | The final status of the message as specified in Table Message state values or ENROUTE for receipts of pending messages. |
| submit date | 14 | Fixed length string | The time and date at which the short message was sent. Formatted: yyyyMMddHHmmss |
| done date | 14 | Fixed length string | The time and date at which the short message reached its final state. Formatted: yyyyMMddHHmmss |
| Message state | Final message states | Description (from SMPP standard) | CM specific description |
|---|---|---|---|
| DELIVERED | DELIVERD | Message is delivered to destination. | Message was delivered at the handset. |
| EXPIRED | EXPIRED | Message validity period has expired. | |
| DELETED | DELETED | Message has been deleted. | Not used. |
| UNDELIVERABLE | UNDELIV | Message is undeliverable. | Message was not delivered at the handset. |
| ACCEPTED | ACCEPTD | Message is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service). | Message has been buffered at the operator network. |
| UNKNOWN | UNKNOWN | Message is in an invalid state. | Not used. |
| REJECTED | REJECTD | Message is in a rejected state. | Message was not accepted by the server. |
Notable differences with the example format given in the standard:
In order to use a single connection to send messages for all operators and tariffs the following proprietary TLVs are supported for both the DELIVER_SM PDUs and the SUBMIT_SM PDUs (please note that the tariff TLV is not yet used for DELIVER_SM PDUs). The "basic unit" of the tariff field is presently cents for all accounts.
| Field | Size octets | Type | Description |
|---|---|---|---|
| Parameter tag | 2 | Integer | 0x1401 |
| Length | 2 | Integer | Length of Value part |
| Value | 1-7 | C-Octet string(Decimal) | MCC/MNC of operator |
| Field | Size octets | Type | Description |
|---|---|---|---|
| Parameter tag | 2 | Integer | 0x140A |
| Length | 2 | Integer | Length of Value part |
| Value | 1-6 | C-Octet string(Decimal) | Tariff in basic unit |
Error Codes:
XML is only available for our SMS services.
More information can be found in our Help Center.
https://gw.cmtelecom.com/gateway.ashxhttps://gw.cmtelecom.co.za/gateway.ashxValues should be XML encoded and XML element names are in capitals. The following characters must be escaped in the XML body:
| Character | Escape value |
|---|---|
| " | " |
| ' | ' |
| < | < |
| > | > |
| & | & |
POST requires a valid XML document, UTF-8 encoded. Values should be XML encoded and XML element names are in capitals. The following characters must be escaped in the XML body:
| Character | Escape value |
|---|---|
| " | " |
| ' | ' |
| < | < |
| > | > |
| & | & |
A POST containing JSON should be sent to a different URL. JSON keys are case insensitive.
<?xml version="1.0" encoding="utf-8"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<BODY>Test message</BODY>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<TO>00447911123457</TO>
<BODY>Test message</BODY>
</MSG>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>OtherSender</FROM>
<TO>00447911123458</TO>
<TO>00447911123459</TO>
<BODY>Other Test message</BODY>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<BODY>Test message</BODY>
<REFERENCE>your_reference</REFERENCE>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<DCS>8</DCS>
<BODY>Κείμενο διαθέσιμο σε όλες τις γλώσσες</BODY>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<MINIMUMNUMBEROFMESSAGEPARTS>1</MINIMUMNUMBEROFMESSAGEPARTS>
<MAXIMUMNUMBEROFMESSAGEPARTS>8</MAXIMUMNUMBEROFMESSAGEPARTS>
<BODY TYPE="AUTO">Κείμενο διαθέσιμο σε όλες τις γλώσσες</BODY>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<MINIMUMNUMBEROFMESSAGEPARTS>1</MINIMUMNUMBEROFMESSAGEPARTS>
<MAXIMUMNUMBEROFMESSAGEPARTS>8</MAXIMUMNUMBEROFMESSAGEPARTS>
<BODY>Using these settings we can send SMS messages that contain more than 160 characters as if it is one message. Please do note that this limits the length of one message to 153 characters.</BODY>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<BODY>This message uses custom groupings</BODY>
<CUSTOMGROUPING>Campaign ABC</CUSTOMGROUPING>
<CUSTOMGROUPING2>Department XYZ</CUSTOMGROUPING2>
<CUSTOMGROUPING3>Source 123</CUSTOMGROUPING3>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>SMS</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<BODY>This message defines allowed channels</BODY>
<ALLOWEDCHANNELS>Push</ALLOWEDCHANNELS>
<APPKEY>00000000-0000-0000-0000-000000000000</APPKEY>
</MSG>
</MSG>
</MESSAGES><?xml version="1.0"?>
<MESSAGES>
<AUTHENTICATION>
<PRODUCTTOKEN>00000000-0000-0000-0000-000000000000</PRODUCTTOKEN>
</AUTHENTICATION>
<MSG>
<CHANNEL>Push</CHANNEL>
<FROM>SenderName</FROM>
<TO>00447911123456</TO>
<APPKEY>00000000-0000-0000-0000-000000000000</APPKEY>
<BODY>This message will be delivered as a push message.</BODY>
</MSG>
</MESSAGES>When sending a request with an invalid part to the XML gateway, NO MESSAGES are created and the entire request is rejected. You will receive a plain text response with details why the request was rejected.
Example response of a failed XML request:
Status: 200 OK
Error: ERROR No account found for the given authentication| HTTP status | Error text | Remarks |
|---|---|---|
| 400 | (none) | No HTTP GET or POST was used to send your request |
| 200 | Error: ERROR | Unknown error An unexpected error occurred. Check the provided values. Contact CM for support. |
| 200 | (empty) | The request was accepted |
| 200 | Error: ERROR No account found for the given authentication | No account found for the provided product token. |
| 200 | Error: ERROR Insufficient balance. | Trial accounts only: You are out of trial messages. Order new messages via your dashboard. If you are a regular prepaid customer, you will be notified that you have run out of quota in a Status Report. |
| 200 | Error: ERROR Message is unrouteable. | Your request could not be routed. Contact CM for support. |
| 200 | Error: ERROR Invalid product token. | Invalid or missing product token |
| 200 | Error: ERROR No FROM field found in a MSG node. | The ‘FROM’ element is missing within the ‘MSG’ element |
| 200 | Error: ERROR A MESSAGES node requires at least one MSG node | A MSG node within the MESSAGE node is required and is missing. |
| 200 | Error: ERROR No phone numbers found. Message will not be sent. | The Phone Number value for the TO element is missing |
| 200 | Error: ERROR Rejected: Gsm '<msisdn>' is not a number. | The value for the TO element is not a valid Phone Number |
| Error code | Short description | Full description |
|---|---|---|
| 5 | Message not delivered at third party | The message has been confirmed as undelivered but no detailed information related to the failure is known. |
| 7 | Message not delivered at operator because recipient has insufficient credit | Temporary - Used to indicate to the client that the message has not yet been delivered due to insufficient subscriber credit but is being retried within the network. |
| 8 | Message expired at third party | Temporary - Used when a message expired (could not be delivered within the life time of the message) within the operator SMSC but is not associated with a reason for failure. |
| 20 | Message not delivered because of a malformed request | Used when a message in its current form is undeliverable. |
| 21 | Message expired at operator | Temporary - Only occurs where the operator accepts the message before performing the subscriber credit check. If there is insufficient credit then the operator will retry the message until the subscriber tops up or the message expires. If the message expires and the last failure reason is related to credit then this error code will be used. |
| 22 | Message not delivered at operator because recipient has insufficient credit | Temporary - Only occurs where the operator performs the subscriber credit check before accepting the message and rejects messages if there are insufficient funds available. |
| 23 | Message not delivered because of an incorrect recipient number (invalid/blacklisted/barred) | Used when the message is undeliverable due to an incorrect / invalid / blacklisted / permanently barred Phone Number for this operator. This Phone Number should not be used again for message submissions to this operator. |
| 24 | Message not delivered because the recipient was unreachable | Temporary - Used when a message is undeliverable because the subscriber is temporarily absent, e.g. his/her phone is switch off, he/she cannot be located on the network. |
| 25 | Message not delivered at third party | Temporary - Used when the message has failed due to a temporary condition in the operator network. This could be related to the SS7 layer, SMSC or gateway. |
| 26 | Message not delivered because of a temporary handset issue (sim card full/memory exceeded/SME busy) | Temporary - Used when a message has failed due to a temporary phone related error, e.g. SIM card full, SME busy, memory exceeded etc. This does not mean the phone is unable to receive this type of message/content (refer to error code 27). |
| 27 | Message not delivered because of a permanent handset issue (unable to receive SMS) | Permanent - Used when a handset is permanently incompatible or unable to receive this type of message. |
| 28 | Message not delivered because submission speed is too high (throttling errors) | Used if a message fails or is rejected due to suspicion of SPAM on the operator network. This could indicate in some geographies that the operator has no record of the mandatory MO required for an MT. |
| 29 | Message not delivered because content is not permitted | Permanent - Used when this specific content is not permitted on the network / shortcode. |
| 30 | Message not delivered because the set spend limit is reached | Temporary - Used when message fails or is rejected because the subscriber has reached the predetermined spend limit for the current billing period. |
| 31 | Message not delivered because the recipient was suspended from premium services | Used when the Phone Number is for a valid subscriber on the operator but the message fails or is rejected because the subscriber is unable to be billed, e.g. the subscriber account is suspended (either voluntarily or involuntarily), the subscriber is not enabled for bill-tophone services, the subscriber is not eligible for bill-to-phone services, etc. |
| 33 | Message not delivered because of parental lock | Used when the subscriber cannot receive adult content because of a parental lock. |
| 34 | Message not delivered because age check failure | Permanent - Used when the subscriber cannot receive adult content because they have previously failed the age verification process. |
| 35 | Message not delivered because age check missing | Temporary - Used when the subscriber cannot receive adult content because they have not previously completed age verification. |
| 36 | Message not delivered because age check unavailable | Temporary - Used when the subscriber cannot receive adult content because a temporary communication error prevents their status being verified on the age verification platform. |
| 37 | Message not delivered because recipient is in national Do-Not-Call Register (for example, the Dutch SMS DienstenFilter and Chinese DnD list) | The Phone Number is on the national blacklist |
| 38 | Message not delivered because maximum concatenation tariff exceeded | Used when the total tariff of a concatenated message exceeds the maximum tariff per message set by the operator |
| 39 | Message not delivered because quota is empty | Used when a customer is out of qouta. |
| 40 | Message not delivered because the conversation window is closed | Message failed to send, conversation window closed. The channel specific conversation window is no longer open to send messages towards this customer. |
| 41 | Message not delivered because too many messages were sent from this number | Too many messages send from this number, blocked notifications or marked as spam. |
| 42 | Message not delivered because recipient is not capable to receive a message from this channel | Used when a recipient is not capable to receive a message from this channel. (For example, the user did not install WhatsApp). |
| 43 | Message not delivered because a template related error occured | Template name does not exist for this language and namespace. |
We also maintain a gateway interface that can be addressed using a HTTP GET method. This call is limited in its features and only supports the basic parameters (FROM, TO, BODY and REFERENCE), options such as concatenation (multipart), unicode, and hybrid messaging are not supported. We advise to use our HTTP POST call if possible.
https://gw.cmtelecom.com/gateway.ashx?producttoken=00000000-0000-0000-0000-000000000000&body=Example+message+text&to=00447911123456&from=SenderName&reference=your_reference
| Parameter | Description |
|---|---|
| PRODUCTTOKEN | Required. This is the product token that was sent to you by email. Example: 00000000-0000-0000-0000-000000000000' |
| MSG | Required. The msg-tag signals the start of a message and should comprise of at least a from, to and body-tag. One HTTP-call can support up to 1000 msg elements. |
| FROM | Required. This is the sender name. The maximum length is 11 alphanumerical characters or 16 digits. Example: 'CM Telecom' |
| TO | Required. This is the destination mobile number. Restrictions: this value should be in international format. A single mobile number per request. Example: '00447911123456' |
| BODY | Required. This is the message text. Restrictions: the maximum length is 160 characters. |
| REFERENCE | Here you can include your message reference. This information will be returned in a status report so you can match the message and it's status. It should be included in the XML when posting. Restrictions: 1 - 32 alphanumeric characters and reference will not work for demo accounts. |
| APPKEY | Use an APPKEY for Hybrid Messaging purposes. If an APPKEY is added to the request, the gateway will deliver according to the settings defined in the App Manager. |
| HTTP status | Error text | Remarks |
|---|---|---|
| 400 | (none) | No HTTP GET or POST was used to send your request |
| 200 | Error: ERROR | Unknown error An unexpected error occurred. Check the provided values. Contact CM for support. |
| 200 | (empty) | The request was accepted |
| 200 | Error: ERROR No account found for the given authentication | No account found for the provided product token. |
| 200 | Error: ERROR Insufficient balance. | Trial accounts only: You are out of trial messages. Order new messages via your dashboard. If you are a regular prepaid customer, you will be notified that you have run out of quota in a Status Report. |
| 200 | Error: ERROR Message is unrouteable. | Your request could not be routed. Contact CM for support. |
| 200 | Error: ERROR Parameter 'producttoken' contains an invalid value: '<producttoken>' | Invalid or missing product token |
| 200 | Error: ERROR No sender name provided | ‘from’ parameter is missing or its value was empty |
| 200 | Error: ERROR Parameter 'to' contains an invalid value: '<msisdn>' | The value for the ‘to’ parameter is not a valid Phone Number |
| 200 | Error: ERROR Parameter 'body' is required | The value for the ‘body’ parameter is missing |
| Term | Description |
|---|---|
| MT | Mobile Terminated – term for a text message that is sent from your application to a handset. |
| MO | Mobile Originated – term for a text message that is sent from a handset to your application. |
| SMPP | Short Message Peer-to-Peer - standard telecom industry protocol for transferring short message data. |
| MSISDN | Mobile Station International Subscriber Directory Number - |
| RCS | Rich Communication Services - A telco level alternative to SMS featuring rich content chat options |
| WABA | WhatsApp Business Account - A WhatsApp verified account for businesses |
Adding conversion details for each message helps you to keep insight into conversions using Analytics and it helps CM to improve the quality of our service. We recommended looking into using the Conversion web API.
A conversion is a confirmation that an end-user has used the contents of the sms/voice/push message that was processed by CM.
If you wish to get started with the Conversion API, click here.