1. Introduction
    1. Prerequisites
    2. How it works
  2. Integration
    1. API endpoint
    2. Authentication
  3. Coverage
    1. Operator coverage
    2. Country coverage
    3. Current available operators
  4. Request a test
    1. Intro
    2. Single test request
    3. Multi test requests
  5. Test results
    1. Status definitions
    2. Single test result
    3. Multi test results
    4. Test results with filter options
    5. Callback report
  6. Glossary

Texter API

Texter is an SMS-route quality testing tool that uses live nodes.

With Texter, we aim to provide you with a testing method, that minimizes testing inaccuracies. For example the “whitelisting” of numbers, as well as fake DLR, grey routing detection, and more.

Prerequisites

To make use of our Texter API you need to be registered at CM.com and you need to be acquired in the Texter app.

You can request access via the contact center on the Texter product page

How it works

To use Texter, you supply us with an operator you want to test. We respond with a phone number and a 16 character key that must be in the SMS message that you want to send. After we give you the phone number, it will be your responsiblity to send the SMS message yourself. The Texter API doesn't send the SMS for you

After you send your test message with the supplied text, we provide you with the details of the potential delivery on the handset. Details such as whether the message has arrived, when it arrived and what has been arrived. You can receive these test details by providing us with a webhook URL to your own API or poll them from the Texter API.

We do our best to provide you with test nodes that have a good and stable internet connection. But it happens sometimes that our live test nodes don't have a perfect stable internet connection. However, it can happen that we receive the result of our test node several hours after you sent your test message due to slow internet connection. Despite receiving a result several hours later, we will still send it to your callback API.

Integration

API endpoint

  • Texter Api: https://api.cm.com/texter/v1

Our API supports sending messages via HTTP. You can send a POST request containing a JSON body.

Authentication

All required tokens which, as a registered user, you can find on our platform in the Texter app.

NOTE: Your tokens are private information and should never be incorporated into webpages and/or mobile applications where it can be exposed to 3rd parties.

API Key (GUID)

To make use of our APIs, you will need an API key in order to authenticate yourself. This ID must be present in every request inside a header named X-CM-PRODUCTTOKEN.

Texter product account (GUID)

Your Texter product account must be provided in the URL for most requests.

Coverage

Operator coverage

Get a list of all MCC/MNC codes that Texter covers. This list changes each day because our coverage depends on our registered live nodes.

We recommend checking this list first before requesting Texter tests to verify if we support the operator.

Request

GET https://api.cmtelecom.com/texter/v1/support/operators

Response

[
  "20404",
  "20408",
  "20416"
]

Country coverage

Get a list of all countries which Texter covers. This list is based on which countries our supported operators are located in.

Request

GET https://api.cmtelecom.com/texter/v1/support/countries

Response

Field Type Description
countryCode string ISO 3166-1 alpha-2 country code
countryName string Name of country
[
  {
    "countryCode": "BE",
    "countryName": "Belgium"
  },
  {
    "countryCode": "NL",
    "countryName": "Netherlands"
  },
  {
    "countryCode": "GB",
    "countryName": "United Kingdom"
  }
]

Current available operators

Get a list of MCC/MNC codes from Texter that indicates which operators have online live nodes at this very moment. When the operator contains offline users only, it will be excluded from the list. Because corresponding phone numbers can't be provided at that moment.

We recommend checking this list frequently to check if Texter can find an online test node for you since the connectivity of our live community shifts hourly.

Request

GET https://api.cmtelecom.com/texter/v1/support/currentavailableoperators

Response

[
  "20404",
  "20408",
  "20416"
]

Request a test

Intro

When you request a test, Texter will check if it has an online test node available. Texter will respond with test details if there is an online test node available for testing. But if Texter doesn’t have a test node available, or doesn't support the operator you want to test, the test details will be empty.

The test details will contain a message key that remains valid for 1 test message via 1 supplier for the given MSISDN. If you send multiple test messages with that same key (also via multiple suppliers), you will not get the result details of those messages.

The MSISDN will be given in the international E.164 notation with leading zeroes as number prefix by default.

The number prefix can be changed in the Texter app to one of the following options:

  • Leading zeroes (default)
  • Plus
  • No leading zeroes

Single test request

Request a single test at Texter.

If you want to perform multiple tests right after eachother, we recommend to use the multi test requests call.

Request

POST https://api.cmtelecom.com/texter/v1/testrequest/{texterProductAccount}

Request body

Field Required Type Description
mccMnc yes string Operator you want to test.
testDuration no integer Test duration in minutes until Texter expires the test with no delivered result (min = 1, max = 60, default = 5).
portabilityStatus no integer Portability status that the test node must have (0 = Ignore, 1 = Non ported, 2 = Ported, default = 0).
resultApiUrl no string Callback URL which receives the result reports. If this is not given, then Texter will use the general callback URL if configured in the Texter app.
{
  "mccMnc": "20416",
  "testDuration": 5,
  "portabilityStatus": 0,
  "resultApiUrl": "https://cm.com/callback"
}

Response

Field Type Description
details string Status message of the requested test (Operator not supported, No candidate available, Found an available candidate).
mccMnc string Requested operator.
requestedPortabilityStatus integer Requested portability status.
test object Test information, is null if no online test node could be found. (See below)

Test:

Field Type Description
id string Code identifier of your test.
msisdn string Phone number of test node.
isMsisdnNetworkPorted bool Is the MSISDN a ported number, can be null if the status is unknown.
messageKey string Set of 16 characters that must be in your text message.
preferredAlphaNumericSender string Alphanumeric sender suggestion to use in your text message.
preferredNumericSender string Numeric sender suggestion to use in your text message.
{
  "details": "Found an available candidate",
  "mccMnc": "20416",
  "requestedPortabilityStatus": 0,
  "test": {
    "id": "20a82d0c-60f7-4895-9eec-8438dcebcf38",
    "msisdn": "0031611223344",
    "isMsisdnNetworkPorted": false,
    "messageKey": "atchint umge din",
    "preferredAlphaNumericSender": "abisizoldel",
    "preferredNumericSender": "00778279878279"
  }
}

Multi test requests

You can request multiple Texter tests for a batch of operators you want to test. Operators can be included multiple times in the batch if you want to send multiple tests for the same operator.

Request

POST https://api.cmtelecom.com/texter/v1/testrequest/multiple/{texterProductAccount}

Request body

Field Required Type Description
mccMnc yes string Operator you want to test.
testDuration no integer Test duration in minutes until Texter expires the test with no delivered result (min = 1, max = 60, default = 5).
portabilityStatus no integer Portability status that the test node must have (0 = Ignore, 1 = Non ported, 2 = Ported, default = 0).
resultApiUrl no string Callback URL which receives the result reports. If this is not given, then Texter will use the general callback URL if configured in the Texter app.
[
  {
    "mccMnc": "20416",
    "testDuration": 5,
    "portabilityStatus": 0,
    "resultApiUrl": "https://cm.com/callback"
  },
  {
    "mccMnc": "20400",
    "testDuration": 3,
    "portabilityStatus": 1,
    "resultApiUrl": "https://cm.com/callback"
  },
  {
    "mccMnc": "20416",
    "testDuration": 5,
    "portabilityStatus": 2,
    "resultApiUrl": "https://cm.com/callback"
  }
]

Response

Field Type Description
details string Status message of the requested test (Operator not supported, No candidate available, Found an available candidate).
mccMnc string Requested operator.
requestedPortabilityStatus integer Requested portability status.
test object Test information, is null if no online test node could be found. (See below)

Test:

Field Type Description
id string Code identifier of your test.
msisdn string Phone number of test node.
isMsisdnNetworkPorted bool Is the MSISDN a ported number, can be null if the status is unknown.
messageKey string Set of 16 characters that must be in your text message.
preferredAlphaNumericSender string Alphanumeric sender suggestion to use in your text message.
preferredNumericSender string Numeric sender suggestion to use in your text message.
[
  {
    "details": "Found an available candidate",
    "mccMnc": "20416",
    "requestedPortabilityStatus": 0,
    "test": {
      "id": "20a82d0c-60f7-4895-9eec-8438dcebcf38",
      "msisdn": "0031611223344",
      "isMsisdnNetworkPorted": false,
      "messageKey": "atchint umge din",
      "preferredAlphaNumericSender": "abisizoldel",
      "preferredNumericSender": "00778279878279"
    }
  },
  {
    "details": "Operator not supported",
    "mccMnc": "20400",
    "requestedPortabilityStatus": 0,
    "test": null
  },
  {
    "details": "Found an available candidate",
    "mccMnc": "20416",
    "requestedPortabilityStatus": 2,
    "test": {
      "id": "388BA892-6C20-4977-9585-E58F9CD49DB8",
      "msisdn": "0031655667788",
      "isMsisdnNetworkPorted": true,
      "messageKey": "ste whomeblughte",
      "preferredAlphaNumericSender": "lindopeabip",
      "preferredNumericSender": "00105580205580"
    }
  }
]

Test results

Status definitions

Code Name Description
0 Pending The test result is still pending.
1 Finished The test has finished with delivered results on the handset.
2 No result The test has expired with no delivery results on the handset. However, should the message eventually be delivered within 24 hours, then the test will be updated to 'Finished' after all
3 Handset unreachable Temporary status. Texter detected that the handset went offline during this test. This temporary status is only used in the callback report towars your callback URL.
4 Invalid test The test has expired while the handset still was offline and has been invalidated. However, should the handset come online again within 24 hours, then the test will be updated to either 'Finished' or 'No result'
5 Rejected by supplier Dashboard only status. Your chosen supplier has rejected your request of sending a text message.

Get single result

Poll the status of a single test with potential delivered results. Supply your test identifier in the URL to receive the current status, test details and test results.

Request

GET https://api.cmtelecom.com/texter/v1/testresult/{texterProductAccount}/{id}

Response

Field Type Description
id string Identifier of your test
requestDate dateTime UTC date and time when the test was requested
expirationDate datetime UTC date and time when the test will be considered not delivered
statusCode integer Status code of the test (see Status definitions)
status string Status description (see Status definitions)
mccMnc string Requested operator
msisdn string Phone number of the test node
isMsisdnNetworkPorted boolean Is the Msisdn a ported number, can be null if the status is unknown
messageKey string Message key of your test
result object Object containing result data from the handset, is null if nothing has been delivered

Result:

Field Type Description
sender string Received sender of your test message
content string Received content of your test message
phoneReceivedDateTime dateTime Date and time (UTC) when your test message was received on the test node
serviceCenter string Service center (SMSC) that lastly has been used for your delivered message
serviceCenterCountry string ISO country code of service center
syncedWithNTP boolean Is the received date and time of the test node synced with a NTP server
resultReceivedDateTime dateTime Date and time (UTC) when Texter received the test results from the test node with internet delay included
encoding integer The encoding with which the message was delivered to the phone, can be null
udh string User data header(s) (comma seperated) buried within the delivered message, can be null
pdu string array Multipart PDU of the delivered message, can be null
{
  "id": "dfa49097-4912-4ad2-b76f-9d59ac31fdf9",
  "requestDate": "2020-07-04T18:42:33.037Z",
  "statusCode": 1,
  "status": "Finished",
  "mccMnc": "20404",
  "msisdn": "0031611223344",
  "isMsisdnNetworkPorted": false,
  "messageKey": "uvamp umolle owi",
  "preferredAlphaNumericSender": "dendasalute",
  "preferredNumericSender": "00674182674182",
  "expirationDate": "2020-07-04T18:47:33.03Z",
  "result": {
    "sender": "dendasalute",
    "content": "uvamp umolle owi: }2<0(~e`ab&",
    "phoneReceivedDateTime": "2020-07-04T18:42:43.987Z",
    "serviceCenter": "+31686899908",
    "serviceCenterCountry": "NL",
    "syncedWithNtp": true,
    "resultReceivedDateTime": "2020-07-04T18:45:13.913Z",
    "encoding": 25,
    "udh": "0003010201,0003010202",
    "pdu": [
      "07911386869909F84014D0E4B29B1C9E87D9757A1900190270400"
    ]
  }
}

Get multiple results

Poll the status of multiple tests with potential delivered results. Supply your test identifiers in the request body to receive the current status, test details and test results.

Request

POST https://api.cmtelecom.com/texter/v1/testresult/{texterProductAccount}

Request body

Array of GUID identifiers

[
  "DFA49097-4912-4AD2-B76F-9D59AC31FDF9",
  "3E0BEBCD-92CB-497B-A884-C9E007C11E0A"
]

Response

Field Type Description
id string Identifier of your test
requestDate dateTime UTC date and time when the test was requested
expirationDate datetime UTC date and time when the test will be considered not delivered
statusCode integer Status code of the test (see Status definitions)
status string Status description (see Status definitions)
mccMnc string Requested operator
msisdn string Phone number of the test node
isMsisdnNetworkPorted boolean Is the Msisdn a ported number, can be null if the status is unknown
messageKey string Message key of your test
result object Object containing result data from the handset, is null if nothing has been delivered

Result:

Field Type Description
sender string Received sender of your test message
content string Received content of your test message
phoneReceivedDateTime dateTime Date and time (UTC) when your test message was received on the test node
serviceCenter string Service center (SMSC) that lastly has been used for your delivered message
serviceCenterCountry string ISO country code of service center
syncedWithNTP boolean Is the received date and time of the test node synced with a NTP server
resultReceivedDateTime dateTime Date and time (UTC) when Texter received the test results from the test node with internet delay included
encoding integer The encoding with which the message was delivered to the phone, can be null
udh string User data header(s) (comma seperated) buried within the delivered message, can be null
pdu string array Multipart PDU of the delivered message, can be null
[
  {
    "id": "dfa49097-4912-4ad2-b76f-9d59ac31fdf9",
    "requestDate": "2020-07-04T18:42:33.037Z",
    "statusCode": 1,
    "status": "Finished",
    "mccMnc": "20404",
    "msisdn": "0031611223344",
    "isMsisdnNetworkPorted": false,
    "messageKey": "uvamp umolle owi",
    "preferredAlphaNumericSender": "dendasalute",
    "preferredNumericSender": "00674182674182",
    "expirationDate": "2020-07-04T18:47:33.03Z",
    "result": {
      "sender": "dendasalute",
      "content": "uvamp umolle owi: }2<0(~e`ab&",
      "phoneReceivedDateTime": "2020-07-04T18:42:43.987Z",
      "serviceCenter": "+31686899908",
      "serviceCenterCountry": "NL",
      "syncedWithNtp": true,
      "resultReceivedDateTime": "2020-07-04T18:45:13.913Z",
      "encoding": 25,
      "udh": "0003010201,0003010202",
      "pdu": [
        "07911386869909F84014D0E4B29B1C9E87D9757A1900190270400"
      ]
    }
  },
  {
    "id": "3e0bebcd-92cb-497b-a884-c9e007c11e0a",
    "requestDate": "2020-07-14T10:16:10.72Z",
    "statusCode": 1,
    "status": "Finished",
    "mccMnc": "20416",
    "msisdn": "0031655667788",
    "isMsisdnNetworkPorted": true,
    "messageKey": "uzelle andukemoa",
    "preferredAlphaNumericSender": "traldospupe",
    "preferredNumericSender": "00559523759523",
    "expirationDate": "2020-07-14T10:21:10.737Z",
    "result": {
      "sender": "traldospupe",
      "content": "uzelle andukemoa: åù¿OÅc]31FC)?€;GøÉ|$?Z&<@+,Ü%~à:SÖñbò¥[?!?ÑÄ^¤>-èÇBö?{=Æ.0_¡æ#§ì2Ø?aäé/T(A}üß*£'",
      "phoneReceivedDateTime": "2020-07-14T10:16:12.803Z",
      "serviceCenter": "+31624000000",
      "serviceCenterCountry": "NL",
      "syncedWithNtp": true,
      "resultReceivedDateTime": "2020-07-14T10:16:13.653Z",
      "encoding": 0,
      "udh": null,
      "pdu": [
        "07911326040000F00414D07479984D7ECFE1757819000002704121"
      ]
    }
  }
]

Get results with filter options

You can poll a list of tests and results by using some additional filters. Optional parameters can be given to filter the Texter test results in the response.

By default, this API call will get your most recent test details

Request

GET https://api.cmtelecom.com/texter/v1/testresult/{productAccount}

Optional request parameters

Field Type Description
mccMnc string Operator filter
fromDate dateTime Get test results of tests initiated after this date and time
toDate dateTime Get test results of tests initiated before this date and time
amountOfResults integer Maximum amount of test results to include in the response (default = 100, max = 10000)

Callback report

Texter can automatically send results of your Texter tests to a specified callback URL specified either configured in the Texter app or set in your API request (ResultApiUrl parameter). Your callback API must support a HTTP POST and respond with a status in the 200 range.

Request body

Field Type Description
id string Identifier of your test
statusCode integer Status code of the test (see Status definitions)
status string Status description (see Status definitions)
messageKey string Message key of your test
result object Object containing result data from the handset, is null if nothing has been delivered

Result:

Field Type Description
sender string Received sender of your test message
content string Received content of your test message
phoneReceivedDateTime dateTime Date and time (UTC) when your test message was received on the test node
msisdn string Phone number of the test node
isMsisdnNetworkPorted boolean Is the Msisdn a ported number, can be null if the status is unknown
serviceCenter string Service center (SMSC) that lastly has been used for your delivered message
serviceCenterCountry string ISO country code of service center
syncedWithNTP boolean Is the received date and time of the test node synced with a NTP server
resultReceivedDateTime dateTime Date and time (UTC) when Texter received the test results from the test node with internet delay included
encoding integer The encoding with which the message was delivered to the phone, can be null
udh string User data header(s) (comma seperated) buried within the delivered message, can be null
pdu string array Multipart PDU of the delivered message, can be null
{
  "id": "dfa49097-4912-4ad2-b76f-9d59ac31fdf9",
  "statusCode": 1,
  "status": "Finished",
  "messageKey": "uvamp umolle owi",
  "result": {
    "sender": "dendasalute",
    "content": "uvamp umolle owi: }2<0(~e`ab&",
    "phoneReceivedDateTime": "2020-07-04T18:42:43.987Z",
    "msisdn": "0031611223344",
    "isMsisdnNetworkPorted": false,
    "serviceCenter": "+31686899908",
    "serviceCenterCountry": "NL",
    "syncedWithNtp": true,
    "resultReceivedDateTime": "2020-07-04T18:45:13.913Z",
    "encoding": 25,
    "udh": "0003010201,0003010202",
    "pdu": [
      "07911386869909F84014D0E4B29B1C9E87D9757A1900190270400"
    ]
  }
}

Glossary

Term Description
MCC Mobile country code
MNC Mobile network code
MSISDN Mobile Station International Subscriber Directory Number
ISO International Organization for Standardization