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:

• Global endpoint (Cloudflare): https://gw.messaging.cm.com/v1.0/message
• Alternative endpoint (Non-Cloudflare): https://gw.cmtelecom.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.

🔑

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)

❗️

Deprecation warning

Providing the product token in the request body is deprecated and not recommended. Use header authentication instead, because we might drop support for product tokens in the body soon.

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.