API - REST API integration

Setup

The developer documentation can be accessed here: https://api-doc.telqtele.com/#introduction

If you would like to use our platform via API, please log in to your TelQ account and go to the Integration Settings > API menu. Click “Enabled” button (unless it is already green), then click on ‘Generate’ next to ‘App key'. Save/copy the App ID and App Key values and then click Apply.

In the top section of the API page you will find the Developer Documentation that includes the API details.

By connecting to the host api.telqtele.com and using the App ID and App key copied in the previous step, you will be able to generate the Bearer Token. Once you receive the token value, set it up as the authorisation header. Please note that the validity of the token value is 24 hours - make sure to refresh it daily.

In the API section, you also have the possibility to set up ‘Allowed IPs’ in order to whitelist only specific IPs for API integration with TelQ. Please make sure not to use this option in case you are using a dynamic IP (with no IPs added, any IP will be allowed).

How it works

From the platform’s perspective, testing via API is similar to testing with no integration (more details can be found in the Manual Testing chapter), the only difference being the fact that you do not have to log in to TelQ platform in order to issue the test requests – in case of API, the test requests are made via API.

Once you successfully set up the API connection as described above, you can request the current coverage list from TelQ by requesting to get the Networks (/networks endpoint). TelQ will reply to your request with a list of MCC MNCs that have test numbers available at the moment of enquiry. portedFromMnc is an indication from which MNC the test numbers of this network have been ported. If the returned value is null, the test numbers of this network have not been ported.

We would like to remind you that we check our networks’ availability constantly, therefore it is highly recommended to get a fresh list of available networks before each test request.

You may select the destination that you would like to test and include its mcc, mnc and portedFromMnc in your test request (/tests endpoint). Also, you have the option to setup a Callback URL if you would like the test results to be forwarded to you automatically.

The API response will include the Test Number belonging to the MCC, MNC, Original MNC you requested and the Test ID Text that has to be included in the message body, alongside your text.
Copy these two values (test number and Test ID Text) and issue an SMS from your platform via the supplier that you wish to test.
Send the SMS to the test number that was allocated to you and include in the message body (along with your text) the Test ID Text corresponding to this test number.

An example of a message body would be: “dlawhakeyxrz ABCDEFG”, where ABCDEFG represents your own text and dlawhakeyxrz is the Test ID Text we issued for your test. Your own text can be any of your choosing (ie. “is your Google login code” etc), but we strongly advise you to avoid using the words “test”, “testing” etc or their translations in different languages in order to decrease the possibility of whitelisting.

It’s important to include the Test ID Text inside of the message body when you are issuing the test from your platform because the matching of the test request with the test result is done based on this value. Our system will only be able to get confirmation of delivery from the phone number if the Test ID Text is present in the delivered text.

We remind you that the Test ID Text has the validity of the TTL value (60mins by default), so please issue the SMS from your platform as soon as possible after you receive the response to your test request (including the test number and Test ID Text.)

Results

All the test requests registered for your account via the API will be listed in the Manual Testing section of your TelQ account. After the SMS is issued from your platform, if your SMS supplier is delivering to that MCC MNC, the Status in Results in your TelQ account – Manual Testing will be updated to

if the test was received by our test number and

if the test was not received by our test number within the TTL value for the Test ID Text.

If you set up a Callback URL, you will also receive the test results there.

Batch testing: You can issue a batch of tests in one go using REST API by following the example below (1. test to 206/10<-20 and the 2. to 716/06):

CODE

{
    "destinationNetworks": [
        {
            "mcc": "206",
            "mnc": "10",
            "portedFromMnc": "20"
        },
        {
            "mcc": "716",
            "mnc": "06",
        }
    ],
    "resultsCallbackUrl": "https://some-callback-url.com/some-path",
    "maxCallbackRetries": 1,
    "testTimeToLiveInSeconds": 200
}

The response from our side will be similar to this example:

CODE

[
    {
        "id": 894562,
        "phoneNumber": "33611223344",
        "testIdText": "zlrtyrvdl",
        "errorMessage": "null",
        "destinationNetwork": {
            "mcc": "206",
            "mnc": "10",
            "portedFromMnc": "20"
        }
    },
    {
        "id": 894563,
        "phoneNumber": null,
        "testIdText": null,
        "errorMessage": "NETWORK_OFFLINE",
        "destinationNetwork": {
            "mcc": "716",
            "mnc": "06",
        }
    }
]

You may submit as many tests as you need at once, but our advice is to limit the request to a maximum of 200 tests per batch in order to achieve the best performance.

For more information on results and the interpretation of results, please see Manual Testing – Results and Interpretation of results.