Shared Features

Sending messages

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"]
        }]
    }
}
FieldDescription
fromThis is the sender name. The maximum length is 16 digits for a phonenumber or 11 alphanumerical characters [a-zA-Z]. Example: 'CM Telecom'
toPhone number of the recipient [array]
bodyText 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.
allowedChannelsArray 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, Google Business Messages, Instagram. The default is to allow any channel configured for your account.

πŸ“˜

Some of the objects are arrays

Please note that the msg, to and allowedChannels objects are arrays and can contain multiple values. Using multiple msg or to 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

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:

  • WhatsApp
  • 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.

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"
            }
        ]
    }
}

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 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:

  • 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, Google Business Messages, 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.

FieldDescriptionRequired
conversationAn array of one or more conversation itemsYes
suggestionsAn array of zero or more suggestionsNo

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"
                    }
                }]
            }
        }]
    }
}
FieldDescriptionRequired
textA string with the textual content.No
mediaA media objectNo
locationA location objectNo
contactA contact object contains a description similar to a vCardNo
templateA 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 typeWhatsAppApple Messages for BusinessViberRCSSMSTwitterFacebook MessengerGoogle Business MessagesInstagram Messaging
Text√√√√√√√√√
- Text formatting√xxxx√√√√
- URL previews√√xxx√√√√
Media√√√√x√√√√
- Image√√√√x√√√√
- Video√√x√x√√x√
- Audio√√x√xx√xx
- Rich cardxx√√xx√√√
- Rich card carouselxxx√xx√√√
Location√xx√xxxxx
Contact√xxxxxxxx
Template√xxxxxxxx
List pickerx√xxxxxxx
Time pickerx√xxxxxxx
OAuth2x√xxxxxxx
Custom appx√xxxxxxx
Paymentx√xxxxxxx

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, Google Business Messages

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.

FieldDescription
LabelThe text the end user will see
ActionOpenUrl / 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, Google Business Messages 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.

  • The postbackdata field is required by Google Business Messages (1000 character limit).
URLThe 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.

CalendarA calendar object

The calendar object contains the following fields.

StartTimeThe start of the appointment. For example "2018-02-05T07:00:00
EndTimeThe end of the appointment, for example "2018-02-05T08:00:00"
DescriptionThe description which will appear in the calendar app
TitleThe 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, Google Business Messages

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.

  • The postbackdata field is required by Google Business Messages (1000 character limit).
DialA dial object
The dial object contains the following field.
PhoneNumberThe 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.

ViewLocationA 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, Google Business Messages, 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, Google Business Messages 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.

URLAuthentication 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.

ProductA marketable product object

The product object contains the following fields:

IdUnique 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

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.

JSON POST responses

HTTP statusError textRemarks
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’

JSON POST Error codes

Error codeDescription
0Ok
999Unknown error, please contact CM support
101Authentication of the request failed
102The account using this authentication has insufficient balance
103The product token is incorrect
201This request has one or more errors in its messages. Some or all messages have not been sent. See MSGs for details
202This request is malformed, please confirm the JSON and that the correct data types are used
203The request's MSG array is incorrect
301This MSG has an invalid From field (per msg)
302This MSG has an invalid To field (per msg)
303This MSG has an invalid Phone Number in the To field (per msg,)
304This MSG has an invalid Body field (per msg)
305This MSG has an invalid field. Please confirm with the documentation (per msg)
401Message has been spam filtered
402Message has been blacklisted
403Message has been rejected
500An internal error has occurred

Did this page help you?