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

📘

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 48 hours.

This feature is supported in all communication channels, the behavior is the same.

{
    "messages": {
        "authentication": {
            "producttoken": "00000000-0000-0000-0000-000000000000"
        },
        "msg": [ {
                "allowedChannels": ["SMS"],
                "from": "SenderName",
                "to": [{
                    "number": "00447911123456"
                }],
                "body": {
                    "type": "auto",
                    "content": "Test message"
                },
                "validity": "2017-04-20 11:50 GMT"
            }
        ]
    }
}

You can supply the time zone for the validity period using either of the following formats:

Absolute date and time:

• 2017-04-20 11:50:05 GMT
• 2017-04-20 11:50:05+8
• 2017-04-20 11:55:05-07:00

If no time zone was specified, CE(S)T will be used. (CM local time)

Relative offset in hour (H) or minute (M)

• 2h
• 30m

You can set the validity in either hours or minutes. A combination of both is not supported. Any value less than 30 minutes cannot be guaranteed to work.

Rich Content

Supported by: WhatsApp, RCS, Viber, Twitter, Facebook Messenger, 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.

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

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.

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.

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

{
    "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.

The calendar object contains the following fields.

{
    "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).

{
    "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.

View location objects contains the following fields:

{
    "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.

{
    "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.

The product object contains the following fields:

{
    "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

JSON POST Error codes