Messaging Trials

Introduction

To test our Business Messaging API, it is possible to get a temporary trial key to test with. To get a temporary key, please visit our Messaging Trial Page.

A trial key is valid for 24 hours, if you want to continue testing after those 24 hours are up, or at a later point in time, you can simply request another key, using the same sign-up form.

🚧

Please note that, while the trial allows you to test the bulk of the functionality of the Business Messaging API, it also has limitations.

Getting started

To get started, go to the messaging trial page and apply for a trial key. You will need to fill out a form with some information, after which an e-mail will be sent to you. The e-mail contains the trial key and brief instructions on how to proceed. If you need more detailed information, you're in the right place. Read on to find out how to start testing;

Whitelisting recipients

In most of the channels we offer, it is not possible to just simply start sending messages to random people. Our suppliers prevent this, because it would encourage spammers to send out bulk messages to random users.

For that reason, most of our suppliers require an end-user to start the conversation. Simply stated; they require an incoming (we call this MO, or "Mobile Originated") message from an end-user to a company first. When the end-user has initiated the conversation by contacting a business, the business can respond, and the actual conversation has started.

After an incoming message is received, there is a time window within which you (as a business) can react to the user that sent that message. In general this time window is 24 hours.

This principle of an end-user having to initiate the conversation also holds true in our trial;

📘

Whitelisting in short

To send messages to your phone number or social media account, we require you to first send the trial key you received to the CM.COM trial company from that specific account or phone number. After we receive that message, we will whitelist the sending account or phone number. After that, the sending account is available for you to use as a recipient.

So, for example, if you want to test sending a message to your personal WhatsApp account, using our Trial API Gateway, you will first have to send the trial key using your personal WhatsApp account to the CM.COM trial company.

Whitelisting your WhatsApp account for receiving test messages

Send your trial key, using WhatsApp to the CM.COM trial company to +31850876714

Whitelisting your Facebook account for receiving test messages

Send your trial key, using Facebook Messenger to the CM.COM trial company

Whitelisting your Instagram account for receiving test messages

Send your trial key, using an Instagram DM to the CM.COM trial company

A note on SMS

At CM.com we enable you to send SMS messages to almost anyone with a mobile phone across the globe, that is what we are very good at. We call these messages MT (Mobile Terminated) messages, because they arrive on a mobile device of an end user.

The other way around however -receiving messages from end users sending text messages from their phone from anywhere in the world- is harder. The ability to do so depends for a large part on the mobile operator or provider of that user. In practice providers can deliver messages from end users to recipients in their own region pretty well, but outside of their region, delivery is not guaranteed.

In the trial flow, you will need to whitelist phone numbers by sending a message from these numbers containing the trial key. For SMS this is complicated, because as you now know, MO messages are not guaranteed to be delivered by providers if the recipient is not a domestic number.

❗️

Regional restrictions for whitelisting

We have a couple of numbers in place for you to send an SMS message to. But please keep in mind, that if you are not in the region of one of these numbers, it may be impossible to whitelist your phone number for testing SMS.

Of course, any of the other channels can be whitelisted without problems, so if you're just looking to check how our API works, you can do so using any of the other channels as well.

Whitelisting your phone for receiving test SMS messages

From the UK: Send your trial key, using SMS to the CM.COM trial company to +447860054666

From the US: Send your trial key, using SMS to the CM.COM trial company to +14232515465

From the Netherlands: Send your trial key, using SMS to the CM.COM trial company to +3197005159375

The Trial Dashboard

In the e-mail you received, you will also find a link to your personal trial dashboard. The URL of that page is unique, so please check the e-mail for the correct link.

Whitelist Tab

The dashboard allows you to check which recipients are whitelisted. There is a whitelist tab to show you just that:

Sending messages to whitelisted recipients

You can click on the document icon under Example code to get a curl example of sending a message to this specific whitelisted recipient.

The easiest way to start testing is to use the Postman API Client as a graphical interface. It is possible to import these curl examples directly using the File...Import menu in Postman, and selecting the Raw text tab:

Import the example, and you can directly start sending sample messages using Postman.

Of course, you are free to change the JSON code to try sending different/more advanced messages. There are many examples of different types of messages you can send over the channels we offer on our developer docs, like Facebook Rich Cards or Instagram Quick Replies. Feel free to try both plain messages or the more advanced features our channels have to offer.

You can also use any other restful API client, or your own code. Your programming language of choice will undoubtedly have the possibility to do API calls programmatically. If you decide to onboard, you can use even more advanced features like incoming events or status reports. These are not available in the trial flow.

You should see the messages come in in the official client software for that channel, i.e.; if you send a message to your whitelisted WhatsApp account, you should receive that message in your WhatsApp app. The same for Facebook or Instagram for example; sending a message via the API, will result in you receiving that message in the official Facebook or Instagram message client.

📘

Note

Sending messages in your trial is done by calling our Trial API Gateway. The endpoint you need to call is different from our production Business Messaging API endpoint. The endpoint you need to use for your trial is https://api.cm.com/messaging/messagingtrial/gw/

The trial API endpoint has much of the same features as the official, production gateway used when you have onboarded to our platform. Some limitations apply, they are listed below.

If you haven't used the curl example code from the Trial Dashboard, keep in mind to use a POST request and send raw JSON as the payload:

Messages Tab

After sending a few messages back and forth, you can check your messages on the Trial Dashboard, using the messages tab:

The messages tab will show you all messages, whether they were inbound or outbound, their timestamps, channel and the message content. The message content of inbound messages will show you exactly what the JSON of an incoming message would be if you set up a webhook on our platform.

Just click a Message Content item to get the complete JSON code in a popup:

📘

note

Please note that the Trial Dashboard doesn't auto-refresh currently. Please refresh the page manually in the browser to see new messages that you may have sent or received.

Limitations

• A trial token is valid for 24 hours. If you want to continue testing another day, you will have to request another trial token using the sign-up form, and whitelist your recipients again.
• The sender of the outbound messages will always be the CM.COM trial account, in the trial it is not possible to send on behalf of your own company. Of course, when you onboard to our platform you can send messages to your end-users using your own (social media) accounts or phone numbers.
• You can whitelist a maximum of 10 recipients.
• Your whitelist will expire when your trial key expires.
• You can only send to a single recipient, in the production API, you can have multiple recipients for the same message.
• Sending batch messages is not supported in the trial.
• Using the channel fallback functionality is not supported in the trial.
• The trial API uses a separate API gateway endpoint. The URL for the trial gateway is https://api.cm.com/messaging/messagingtrial/gw/. The production API gateway will be more performant. There is no guarantee that the trial gateway will respond in exactly the same way as the actual gateway, because of restrictions placed on the trial API, and because the trial API gateway is limited in its resources.
• The amount of messages you can send is limited, and varies per channel. Specifically SMS and WhatsApp are limited to 10 messages per trial/24 hours, to prevent spamming. Other channels are limited to 30 messages.
• For SMS, a message over 63 characters Unicode or 144 characters ASCII will result in a multi-part message. The trial restricts SMS multipart messages to two parts (so 288 characters ASCII or 126 characters Unicode).
• After onboarding you can enjoy all benefits of our platform, like
  • Message Log, which shows extended information about all of your messages
  • Being able to onboard all of your own channels and accounts
  • Advanced traffic insights
  • Status reports on delivery of each message
  • Incoming message events like a "read" event when an end-user has read your message.

A note on testing SMS messages

Sending SMS messages is often limited by country regulations. A fair amount of countries allow SMS messages to be sent freely, but a lot of countries also have restrictions in place. Not adhering to these restrictions can result in SMS messages being blocked, and in some cases in countries blocking the sender or even in fines.

For this reason, we don't support sending SMS messages to a number of specific countries in this trial. You will need to be onboarded if you want to send messages to these specific regions. CM can provide help in making sure that you adhere to local legislation and that you can reach your target audience wherever they are.

These are the kinds of regulations in place:

• Some countries will block messages containing URLs
• Some countries need you to register your sender id beforehand
• Some countries require an opt-in for end users before they can receive messages from companies
• Some countries will flag and/or block duplicate content (same sender, same content) within a number of minutes
• Some countries only accept Latin characters in messages
• Some countries will require you to provide opt-out functionality

Countries for which SMS is not supported in the trial, because of legislation

Countries for which SMS is restricted in the trial

Some countries have strict regulations, but we want you to be able to test, at least so you can see the messages arrive. In these cases, we will replace your message with a generic message, to make sure that no regulations are violated.

The generic message you will receive in these countries is:

Because of regulations in this destination, your message from the CM.COM trial gateway has been replaced. Onboard to our platform for full functionality.

Countries for which SMS messages might be blocked

In all cases, please make sure your test messages don't contain (references to) the following subjects. This might get your messages blocked by providers and your message will not arrive:

• adult/sexual content
• political content
• religious content
• advertisements/marketing/promotional content
• abusive or racist content
• spam, phishing
• (references to) Illegal substances

The list of countries below have legislation in place that will block messages if they contain restricted content.

❗️

TL;DR - testing SMS

When testing SMS in the trial, keep to trivial text as contents. Don't reference any potentially sensitive subjects or your message might be blocked.

Some countries are not supported in the Trial for SMS. You can still evaluate our API using other channels besides SMS.

After onboarding, we can help you set up your account in a way that allows you to send the content you want to the recipients you want.

Delivery time

SMS messages might take longer to arrive than messages on other channels, because they are routed between third parties until they can be delivered to your phone.

📘

SMS Routes

At CM we offer different priorities for sending SMS messages. If you are looking for fast, reliable delivery of SMS messages like OTP messages, please contact us. The purpose of this trial is for developers to test their code, so delivery is not always done via high priority routes.

Troubleshooting

There are a number of errors that might pop up when you are using the trials. Below you'll find the different errors you might encounter, the cause and the solution (if any).

Sending Messages

• Incoming request is not JSON. Check the content-type and content.
  The data you POSTed to the gateway was not recognized as (valid) JSON data.
• Invalid POST data. Please double check your JSON payload.
  The content of the JSON payload you are sending to the gateway is malformed. Check your JSON format, or use one of the examples as a starting point.
• The trial functionality is at capacity right now, please try again later.
  To prevent fraud, the gateway will block when the trial accounts are sending more messages than expected. We will need to investigate this and unblock the gateway manually, so when you get this message, you will need to retry the trial later.
• Invalid or expired trial token
  The token you used to send the message is incorrect or expired. Check if you are perhaps using an old key or if you have a typo in your key. Keys are valid for 24 hours. After 24 hours you will need to request a new key.
• Using multiple channels in allowedChannels (channel fallback) is not supported in the trial. Please onboard to our platform to get the full functionality.
  In the trial flow we don't support more advanced features like channel fallback. This is something that needs to be configured for you, and therefore you will need an account on our platform.
• Sending bulk messages in a single call is not supported in the trial. Please onboard to our platform to get the full functionality.
  The messages node in the JSON structure is an array, this allow you to send multiple messages in one call. This is an advanced feature currently not supported in the trial.
• Sending to multiple recipients in a single call is not supported in the trial. Please onboard to our platform to get the full functionality.
  The to field in the JSON is an array, which allows you to send the same message to multiple recipients in one go. This is an advanced feature currently not supported in the trial.
• You have reached the maximum amount of messages that can be sent via [channel] in this trial
  The trial has limits for each channel on the amount of messages you can send. Currently the limits are 10 messages for SMS/WhatsApp and 30 messages for other channels.
• The from: field for SMS is limited to 4-11 alphanumeric characters in the trial. Please onboard to our platform to get the full functionality.
  SMS messages have restrictions per country or operator. To make sure you can send to as many destinations as possible we consolidate the sender to comply with as many of these destinations` rules and regulations. Use an alphanumeric sender (4-11 characters) to solve this error.
• Because of rules and regulations, the destination for this message is not allowed in the trial. Please onboard to our platform to get the full functionality.
  This is also related to rules and regulations in different destinations. In some cases we can't comply with all rules and regulations for trial accounts. Some countries, for example, have restrictions on specific words or subjects you can use in a message. Other countries might need you (as a sender) to be registered first.
  If you onboard to the CM.com platform, we can arrange all of this for you and you can send to any desired destination. In this trial we are unfortunately restricted to destinations that allow any content and don't require registration.