Messaging API allows you to send and receive text messages to users around the globe via multiple channels: SMS, Viber, Whatsapp.

If you use Postman, you can quickly test all of the API calls by importing this Postman collection:

The SMS Connexion™ Messaging API is RESTful and is served only over HTTPS. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.

You can use your favorite HTTP/REST library for your programming language to consume our API, or you can use one of our SDKs.

• Requests are sent over HTTPS.
• Request and response bodies are JSON formatted.
• Query parameters naming is snake_case (eg. short_response, start_date, end_date)
• Request/response bodies parameters (from JSON objects) are camelCase (eg. phoneNumbers, allowInvalid)

All dates are in UTC and the datetime format used is YYYY-MM-DD HH:MM:SS
e.g. 2021-07-12 14:54:13

All phone numbers should match the international format E.164, wich define that numbers are formatted with "+" sign, followed by the country code and the subscriber number and can have a maximum length of 15 digits.
e.g. +4915123xxxxxx for Germany, +3361231xxxx for France, +39312311xxxx for Italy

All country names an country codes in this API are represented as two-letter country codes defined in ISO-3166 alpha 2 standard.
e.g. DE for Germany, FR for France, IT for Italy

The currency code is in ISO-4217 format. e.g. eur for Euro, usd for US Dollar

All requests made to the API must be authenticated.

The API offers two methods of authentication: Oauth2 and API Key

The SMS.CX Messaging API supports the Oauth2 client credentials flow (RFC 6749).

The Oauth2 uses scopes to provide a certain rights management for specific endpoints. Please check the full list of available scopes.

Authenticating via Oauth2 method requires the following steps:

1. Create a Client (or reffered as an Application) - you will get client_id and client_secret
2. Generate an Access Token
3. Make Authenticated Requests

1. Create a Client (or Application)

First go to the Admin Dashboard > HTTP API > Oauth2 and create a new Application (or Client).

*Admin Dashoard*

You will have to select the token expiration (1 day, 1 week or never) for all the access tokens issued by this Application, and to select the scopes allowed (sms, viber, whatsapp, groups, reports, etc.).

From the Admin Dashboard you will get the Application ID and Application Secret that will be used as parameters client_id and client_secret on the next step.

2. Generate an access token

To generate an access token your app makes a POST request to the Authorization endpoint /oauth/token, with the following parameters:

The POST request needs to use the HTTP Basic authentication scheme, by encoding client_id:client_secret string to Base64 string and use it in the header:

Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 

Alternatively, the authorization server supports including the client authentication in the request-body.

Including the client credentials in the request-body using the two parameters client_id and client_secret is not recommended and should be limited to apps/clients that are unable to directly utilize the HTTP Basic authentication scheme.

Example with client authentication as Basic Auth header [RECOMMENDED]

POST /oauth/token HTTP/1.1
Authorization: Basic client_id:client_secret (base64 encoded value)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example with client authentication in request body

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=client_credentials

The Authorization endpoint will validate the request and if successfull will respond with an access token:

An example successful response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "1d0d303679dba1135e372a9eccda02b0601eb4f9",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "sms viber whatsapp multichannel conversations reports groups originators templates shortlinks attachments optouts account applications numbers"
}

Note: Each scope represents a resource, an endpoint.

For example, if your access token does not have groups scope granted, then the resource /groups will not be available. If scopes sms, groups, templates are granted, then the access token can send SMS, create/edit/delete groups, add contacts to groups, create/edit/delete templates

3. Make authenticated requests

Once the access token is obtained, it has to be provided on each request as a bearer token within the Authorization http header (Bearer Token Usage RFC 6750).

Example using the access token as bearer authorization

POST /sms HTTP/1.1
Authorization: Bearer REPLACE_ACCESS_TOKEN

GET /groups HTTP/1.1
Authorization: Bearer REPLACE_ACCESS_TOKEN

If an access token is compromised, go to Admin Dashboard and revoke all tokens for that specific application. If needed, you can reset the application secret from the same section.

API keys, like access tokens, have a set of capabilities assigned to them. However, unlike access tokens wich provides more fine-grained access control and can have limited lifetime, API keys provides full access to all the account resources and are long-lived.

To authenticate an API request just add the custom header X-API-KEY to the request header.

You can generate and manage your API keys in the Admin Dashboard > HTTP API > API Keys.

*Admin Dashoard*

If an API Key is compromised, go to Admin Dashboard and deactivate or delete that API Key.

The API uses standard HTTP status codes to indicate the success or failure of the API calls.

In case of success the response body contains a JSON object with the following structure:

• info - object of objects - contains information about the fetched/created resource, e.g. ids, summary of fetched/processed collections, etc.
• data - array of objects - contains the collection of data fetched or processed

Request to get group details

GET /groups/4360975
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

Response with info and data

200 OK
Content-Type: application/json

{
    "info": {
        "id": 17,
        "name": "My group 3",
        "totalPhoneNumbers": 3,
        "totalCost": 0.123,
        "totalOptouts": 1,
        "phoneNumbersByCountry": {
            "ES": 1,
            "FR": 1,
            "GB": 1
        },
        "createdAt": "2021-07-10 13:03:08"
    },
    "data": [
        {
            "id": 44631,
            "phoneNumber": "+33612935399",
            "countryIso": "FR",
            "firstName": "Anton",
            "lastName": "Maheu",
            "email": null,
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": true,
            "dateAdded": "2021-07-10 13:03:09"
        },
        {
            "id": 44632,
            "phoneNumber": "+34612160806",
            "countryIso": "ES",
            "firstName": "Almanza",
            "lastName": "Quintero",
            "email": "almanza.quintero123@tempmail.com",
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": false,
            "dateAdded": "2021-07-10 13:03:09"
        },
        {
            "id": 44633,
            "phoneNumber": "+447400547989",
            "countryIso": "GB",
            "firstName": "Hayden",
            "lastName": "Francis",
            "email": null,
            "field1": null,
            "field2": null,
            "field3": null,
            "field4": null,
            "field5": null,
            "groupId": 17,
            "optout": false,
            "dateAdded": "2021-07-10 13:03:09"
        }
    ]
}

Request to create new group of contacts

POST /groups
Content-Type: application/json
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

{
    "name": "My new group"
}

Response only with info

201 Created
Content-Type: application/json

{
    "info": {
        "id": 18,
        "name": "My new group"
    }
}

Request to delete a shortlink

DELETE /shortlinks/xYuQ
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

Response only with info

200 OK
Content-Type: application/json

{
    "info": {
        "id": "xYuQ"
    }
}

The API uses standard HTTP status codes to indicate the failure of and API request. The body of the error response will always be a JSON object in the following format:

HTTP/1.1 400 Bad Request

{
    "error": {
        "type": "invalid_param",
        "message": "The name is empty or parameter 'name' not set",
        "uri": "https://sms.cx/docs/api/errors",
        "code": 1204
    }
}

Description of error object

There are some specific cases - when validating phone numbers - in wich the response body contains the error object plus the property invalid wich is an array with invalid phone numbers.

The endpoints that validate phone numbers at runtime and throw errors if invalid are:

• /sms
• /viber
• /whatsapp
• /multichannel
• /groups/{groupId}

Note: Pparameter allowInvalid with value true can be used in the request body in order not to throw an error and continue execution. The valid phone numbers will be added to the group, the invalid numbers will be placed in the info.invalid object.

Request to add phone numbers to a group

POST /groups/4339812
Content-Type: application/json
Authorization: Bearer 202f9f782e***************a2e1ff58103b971

{
    "phoneNumbers": [
        "+336129353",
        "+33612970283",
        "+3361211",
        "+43664187834",
        "+41781218472",
        "+351912110421",
        "+4915123473140",
        "+4915123595",
        "+4915123966046"
    ]
}

Response only with error and invalid

400 Bad Request
Content-Type: application/json

{
    "error": {
        "type": "invalid_param",
        "message": "The phone numbers provided are invalid",
        "uri": "https://sms.cx/docs/api/errors",
        "code": 1210
    },
    "invalid": [
        "+336129353",
        "+3361211",
        "+4915123595"
    ]
}

SMS.CX Messaging API uses the HTTP status codes for errors:

For 4XX response there was some problem with your authentication, the privileges, the structure of your request or rate limited.

A 5XX response indicate an internal error occurred, you should retry your request with an exponential backoff method.

When sending an SMS, the API allows to track the success or failure of the SMS by providing different statuses.

The following statuses are available:

Note that statuses of type Intermediate will not trigger a request to your callback URL. They can only be reported if you request the status by message ID.

The errorCode parameter in the DLR callback gives more information about a failed delivery. A non-null value indicates that the message could not be delivered.

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to send a SMS campaign to 20.000 phone numbers does not respond due to a network connection error, you can retry the request with the same idempotency id to guarantee that no more than one campaign is sent and you are not billed twice.

To perform an idempotent request, provide an additional idempotencyId parameter to the request body. To confirm that the server understood the request, the response will contain the header X-Idempotency-Id with your unique value.

SMS.CX Messaging API's idempotency works by saving the resulting status code and body of the first request made for any given idempotency ID, only if the incoming parameters pass validation and the API endpoint begin execution. Subsequent requests with the same id return the same result, including 500 errors. If incoming parameters failed validation (HTTP status 4XX), no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

An idempotency ID is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. The unique values you create must be valid UUIDs (from v1 to v5) to avoid collisions.

Idempotency IDs are removed from the system automatically after they're at least 24 hours old.

Idempotency IDs are supported on POST requests that affects the billing. Sending idempotency ids in GET and DELETE requests has no effect, as these requests are idempotent by definition.

The Messaging API is fast and can validate and send up to 25.000 SMS/Viber/Whatsapp in a single request. If the response from the API is intrerrupted due to a network connectivity error and you retry the request with the same idempotency ID, if the execution of the API endpoint didn't finished you will get the following intermediary reseponse:

{
    "info": {
        "idempotencyId": "287c1e8d-4842-4106-8fe9-4debf8855743",
        "route": "/sms",
        "status": "processing"
    }
}

In this case you should safely retry the request with an exponential backoff method.

The methods that accept an idempotency id are the following:

• Send SMS
• Send SMS Campaign
• Send Viber
• Send Viber Campaign
• Send Whatapp
• Send Whatapp Campaign
• Send Multichannel
• Send Multichannel Campaign

There are limits to the number of API calls that your application can make against a particular endpoint. Each API response you receive will include the headers X-Rate-Limit-Limit and X-Rate-Limit-Remaining

Exceeding a rate limit will result in an HTTP 429 Too Many Requests status code. It will include an X-Rate-Limit-Reset header that indicates the remaining window before the rate limit resets, in UTC epoch seconds (e.g. 1626119010).

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

For improved security you can create a list of allowed IP addresses. Only IP addresses in the allowed list can make API calls using the applications credentials (Access Tokens, API Keys). If the list is left empty, all IP addresses are allowed.

To add an IP address to the allowed list, go to Admin Dashboard.

*Admin Dashboard - HTTP API - Security*

Note: Only IPv4 addresses are supported

API requests made from an IP address not in the allowed list will result in the following response:

403 Forbidden
Content-Type: application/json

{
    "error": {
        "type": "access_denied",
        "message": "Access denied for this IP address",
        "uri": "https://developers.sms.cx/docs/rest/ip-access/errors",
        "code": 1605
    }
}

When making data requests it is likely that there is more data than can be returned in a single response. When that is the case the response will include a paging object with a next token, previous token and size of the returned collection. Whenever a next token is provided, there is additional data to retrieve so you will need to keep making API requests. If the next token is null then you reached the end of the data collection.

To request the next page of data, you must make the exact same query as the original, and also include a next request parameter set to the value from the previous response.

The same applies for previous token, except that the first request will have the previous token as null.

You can limit the number of results returned with the query parameter limit. The default and the maximum limit in the same time is 500.

Webhooks are an addition to an API, and rather of your code making the request for data, the API sends data to you. The data makes it to your application in the form of a HTTP request.

The API will make HTTP requests to your endpoints, saved in the application settings or that are set during your API calls. Your endpoints must return status HTTP 200 OK for the callback request to be marked as successful. If not successful, the API will retry the request using an exponential backoff algorithm.

The retry policy will follow this delay from the initial attempt:

SMS.CX API allows you to set a different callback/webhook URL for each resource that accepts this parameter.

However, if you want you can use only one endpoint for receiving data from SMS.CX API. The sent data is standardized across all callbacks, every request will have two objects: event and data. This makes it easier to use only one endpoint for all callbacks and identify the correct event for specific processing.

The event parameter can have the following values:

• dlr_update
• receive_sms
• receive_viber
• receive_whatsapp
• shortlink_hit
• shortlink_hit_update
• attachment_hit
• attachment_hit_update
• new_optout
• otp_update
• number_lookup

The SMS.CX API groups the data by event type in the data object and send up to 200 events in one single callback request. Therefore, your endpoint must expect to parse and iterate trough all the data object.

Note: If by any reason your endpoint cannot handle bulk event grouping, please contact us so we can switch your callback settings to single request. Also, you can request increase or decrease in the data object grouping (eg. 40 events per request, 500 events per request, etc.)

Example of callback request with event type "dlr_update" and 3 events grouped in the data object:

{
    "event": "dlr_update",
    "data": [
        {
            "campaignId": "961dbfa9-8e12-4f96-b59d-6c0c79c53edc",
            "msgId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "0ef52a99-10b1-4813-af84-9b285edfbc30",
            "msgId": "a710a44a-e784-4199-b73c-a2c8bfd41b59",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "961dbfa9-8e12-4f96-b59d-6c0c79c53edc",
            "msgId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "trackData": "7f543bdc-dcc5-47c3-b54a-ee425f78cb3c",
            "statusCode": 1,
            "status": "DELIVERED",
            "datetime": "2022-03-03 15:30:24"
        }
    ]
}

For complete details of each callback event (parameters list, examples) read the specific section:

• Receive delivery reports updates
• Receive SMS
• New short link hit
• New attachment hit
• New optout
• OTP update
• Number lookup