Business Messaging Basics

SDKs

Get started quickly with our API integration using one of our SDKs:

• Node.js NPM package - GitHub
• PHP Composer package - GitHub
• Java SDK - GitHub
• .NET NuGet SDK - GitHub
• Python SDK - GitHub

API Endpoints

We recommend using our Global endpoint via Cloudflare for optimal performance and security:https://gw.messaging.cm.com/v1.0/message

These endpoints support HTTP POST requests with a JSON body. Messages can be sent via SMS, RCS, WhatsApp, and Viber. For SMS via SMPP, refer to our SMPP documentation.

⚠️

Cloudflare Sub-processing

Using the Global endpoint via Cloudflare means Cloudflare, Inc. located in the USA is engaged as a sub-processor. View the list of sub-processors here.

⚠️

Alternative endpoint.

For options, like our Non-Cloudflare endpoint, please reach out to our support or your account manager.

🔑

Certificate Renewals

• Cloudflare endpoint certificates are renewed every 90 days. More information: Cloudflare Developer Docs.
• Alternative endpoint certificates are renewed annually. Subscribe to our status page for updates.

Authentication

All API requests require a product token to authenticate your application. You can find your product token in the Channels app. The token must always include hyphens.

🔑

Keep your product token secure

Never expose your product token in client-side code or public repositories.

Header Authentication (Recommended)

Pass your product token in the X-CM-PRODUCTTOKEN header for secure communication.

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

Successful Response:

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

Unsuccessful Response:

If authentication fails (e.g., invalid product token), the following response will be returned:

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

📘

Sending messages

For more information about sending messages and possible responses, please read our Business Messaging Features documentation.

Request Body Authentication (Deprecated)

❗️

Not recommended

Providing the product token in the request body is not recommended. Use header authentication instead.

However, for legacy integrations, you can provide the product token like this:

{
  "messages": {
    "authentication": {
      "productToken": "00000000-0000-0000-0000-000000000000" 
    },
    "msg": [
      {
        "from": "Sender",
        "to": [
          {
            "number": "00447911123456"
          }
        ],
        "body": {
          "type": "auto",
          "content": "My first CM.com message"
        },
        "reference": "my_reference_123"
      }
    ]
  }
}

Receiving Messages

To receive incoming messages from channels like SMS or WhatsApp, configure a webhook to process incoming (MO) messages. Learn more in our Inbound Webhook API documentation.

Encryption & Encoding

All communication must use TLS 1.2 or higher. Older protocols like TLSv1.1, TLSv1.0, and SSLv3 are not supported. Messages must be UTF-8 encoded unless specified otherwise.