Setup
The developer documentation can be accessed here: https://api-doc.telqtele.com/#introduction
To use the TelQ platform via API, log in to your TelQ account and go to Integration Settings > API. Click Enabled (unless it's already enabled).
API credentials
Each account can have up to 5 active API credential pairs (App ID + App Key). Having several pairs lets you:
-
use separate credentials for different integrations or environments
-
rotate keys without downtime: create a new pair, switch your integration to it, then delete the old one
-
revoke a single pair without affecting your other integrations
To create a new pair:
-
Click Generate new credentials
-
Copy the App ID and App Key and store them somewhere safe.
The App Key is shown only once, at creation. TelQ cannot display it again. If you lose it, delete that pair and create a new one.
The credentials list shows each pair's App ID and creation date. App Keys are never displayed after creation.
To revoke a pair, click Delete next to it. Any integration using that pair will stop authenticating right away. Your other pairs keep working.
For security reasons, you can create or regenerate credentials up to 10 times per hour.
Authentication
Connect to api.telqtele.com and use any active App ID and App Key pair to generate a Bearer Token. Set the token as the authorization header in your requests. The token is valid for 24 hours, so make sure to refresh it daily.
Allowed IPs
In the API section you can also set Allowed IPs to accept API requests only from specific IPs. Don't use this option if you have a dynamic IP. If no IPs are added, any IP is 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):
{
"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:
[
{
"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.