Integration

Integrating the Business Messaging API with your system

Suggest Edits

SDKs

Several SDKs are available to get you started with your API integration.

API endpoints

We recommend that all our customers utilize our global endpoint, which is globally load-balanced across all our platform locations. Geo-based routing allows us to select the optimal platform based on your location, ensuring high availability and security through our partner, Cloudflare.

🚧

Sub-processing by Cloudflare, Inc.

If you use the Global endpoint via Cloudflare, you agree that Cloudflare, Inc. located in the USA is engaged as a Sub-processor under the Agreement, for an overview of our Sub-processors please see: https://www.cm.com/cdn/web/en/file/subprocessors.pdf.

More information can be found in our Help Center.

Our API endpoints support HTTP POST requests, using a JSON body containing the message information. Our JSON API enables you to send messages via SMS, and also newer communication channels like RCS, WhatsApp and Viber.

Alternatively, we also support sending SMS via SMPP, which we have documented with examples here.

Authentication / Authorization

All requests towards our Business Messaging API require a product token. You can find your product token as a registered user on our platform in the Channels app.

❗️

Keep your product token secret

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.

You can provide your product token within the HTTP request body, along with the messages that you want to send out:

{
  "messages": {
    "authentication": {
      "productToken": "<YOUR PRODUCT TOKEN>" 
    },
    "msg": [
      {
        "from": "Sender",
        "to": [
          {
            "number": "00447911123456"
          }
        ],
        "body": {
          "type": "auto",
          "content": "My first CM.com message"
        },
        "reference": "my_reference_123"
      }
    ]
  }
}

If all goes well, then our API will accept your messages and send them towards your target audience via your account:

{
  "details": "Created 1 message(s)",
  "errorCode": 0,
  "messages": [
    {
      "to": "00447911123456",
      "status": "Accepted",
      "reference": "my_reference_123",
      "parts": 1,
      "messageDetails": null,
      "messageErrorCode": 0
    }
  ]
}

Otherwise, if we do not recognize your product token, then you will receive an HTTP 400 response:

{
  "details": "No account found for the given authentication/credentials",
  "errorCode": 101,
  "messages": []
}

For more information about sending messages and possible responses, please continue to our Shared Features documentation,

Header authentication (new)

We now also partially allow customers to provide their product token via an X-CM-PRODUCTTOKEN header instead of the body. This allows you to keep your credentials and your request content separated. This feature currently only works in Europe, using our Cloudflare endpoint: https://gw.messaging.cm.com/v1.0/message. Other endpoints will receive this feature later.

When using the X-CM-PRODUCTTOKEN header, you can leave out the authentication section from your request body:

curl -X POST https://gw.messaging.cm.com/v1.0/message \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'X-CM-PRODUCTTOKEN: <YOUR PRODUCT TOKEN>' \
     --data-raw '
     {
       "messages": {
        "msg": [
          {
            "from": "Sender",
            "to": [
              {
              	"number": "00447911123456"
              }
            ],
            "body": {
              "type": "auto",
              "content": "My first CM.com message"
            },
            "reference": "my_reference_123"
          }
        ]
      }
    }'

Encryption

🚧

Security protocols

Older security protocols such as TLSv1.1, TLSv1.0 and SSLv3 are not supported.

Communication with the CM.com servers should be done using the TLS cryptographic protocol, version 1.2 or higher.

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 manually enable this, as it is part of the the WhatsApp account creation process.

Receiving messages

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

Updated 27 days ago