Introduction
Welcome to the TelQ Telecom API. You can use our REST API to obtain a list of our available networks, send tests and consult test results.
API Versions
API Version 2.1
New customers should use this version of the API.
We are happy to announce the release of our new API Version 2.1. We have introduced a new feature that gives our users fine control over the test-id-text to be used within tests. Please look at the /tests model for more details on how to use this powerful tool.
API Version 2.0
On this version we have strived to simplify and standarize our models and provide additional information when available. We provide new features like custom test TTL and callback tokens. Please review this document for instructions on how to use our new API v2.0
API Versions 1.0 through 1.5
Version 1.5 of the API continue to be supported.
You can find the relevant documentation for each version below:
Versions 1.0, 1.1, 1.2, 1.3 and 1.4 have been deprecated, This means no new development or bug fixes will occur on those versions, but they will continue to be supported by our app through 2021. We may stop supporting them at some point in the future but we will give ample warning to all our customers about it.
OpenAPI Specification
You can find the OpenAPI 2.0 Specification for our v2.1 API at our swagger hub page: https://app.swaggerhub.com/apis/TelQ/testing/v2.1
You can obtain autogenerated SDKs for many popular programing languages from this spec.
TelQ Telecom Java SDK
We are happy to announce the release of SDK for Java that simplifies the integration of our new API v2.1.
All you need to do to start using it is import this maven dependency to your project. com.telqtele/sdk/1.3.1
Select the "Java" tab from the panel to the right for instructions on how to perform the different operations using our Java SDK.
Select the "Java", "Python" or "PHP" tab above to see details about the respective SDKs.
<dependency>
<groupId>com.telqtele</groupId>
<artifactId>sdk</artifactId>
<version>1.3.1</version>
</dependency>
TelQ Telecom Python SDK
We are happy to announce the release of SDK for Python that simplifies the integration of our API.
All you need to do to start using it is install our package in your project. telq
Select the "Python" tab from the panel to the right for instructions on how to perform the different operations using our SDK.
pip install telq
TelQ Telecom PHP SDK
We are happy to announce the release of SDK for PHP that simplifies the integration of our API.
All you need to do to start using it is install our package in your project. https://github.com/TelQ/sdk-php
Select the "PHP" tab from the panel to the right for instructions on how to perform the different operations using our SDK.
composer require telq/sdk
Authentication
Authentication example:
# With shell, you can just pass the correct header with each request
curl -X POST "https://api.telqtele.com/v2.1/client/token"
-H "accept: application/json"
-H "Content-Type: application/json" -d "{ \"appId\": 000001, \"appKey\": \"keykeykeykey\"}"
# Make sure to replace `000001` with your appId and `keykeykeykey` with your appKey
/*
With our Java SDK you simply need to initialise
TelQTestClient with your app key and app id.
*/
TelQTestClient testClient = TelQTestClient.getInstance("<yourAppKey>", "<yourAppId>");
/*
Make sure to put your app key and app id in the getInstance call.
Furthermore, keep in mind that your token will be automatically requested, but if for any reason
you destruct the test client, you will have to initialize it again with your app key and id.
*/
from telq import TelQTelecomAPI
telq_client = TelQTelecomAPI()
test_client.authenticate(api_id="<yourAppKey>", api_key="<yourAppId>")
###
# Make sure to pass your app key and app id in the authenticate call.
# Furthermore, keep in mind that your token will be automatically requested, but if for any reason
# you destruct the test client, you will have to initialize it again with your app key and id.
###
use TelQ\Sdk\Api;
use TelQ\Sdk\Http\HttpException;
$appId = <APPID>;
$appKey = <APPKEY>;
$api = new Api($appId, $appKey);
try {
// call api
} catch (HttpException $exception) {
echo 'Handle http exception', PHP_EOL;
echo 'Response code ', $exception->getResponse()->getStatus(), PHP_EOL;
echo 'Response body ', $exception->getResponse()->getBody(), PHP_EOL;
}
The above command returns:
{
"ttl": 86400,
"value": "WDoskdWWDkdjsaSWWWSSsht/knEQGAE+MH+mwa9sqSD
+ca3C9BbWvYDmSWWDDpppmdkdg6ilXwfGAfrjuBsW+ZFBpZAN1n+3
oy40jnXLfsYYma8q2HBknEQGAE+MH0u+cxEQRxjiyN9y6lWmf75QJ
oXmtE8cDIrFfShTcZ+kTHnp6rgjdd0ctwNimb07xyPQvOK0="
}
/*
The code above will return an instance of TelQTestClient that has been initialized.
*/
###
# The code above will return an instance of TelQ API Client that has been initialized.
###
/*
The code above will return an instance of TelQTestClient that has been initialized.
*/
TelQ uses API keys (appId, appKey) to provide access to the API. You can find your App ID and generate your App Key on the API Menu of the TelQ App.
In order to use our APIs, follow these steps:
Step 1: Obtain the Token using the appId and appKey through the /token
REST endpoint. The Bearer Token is used for authorization purposes in all subsequent calls. The TTL (Time to live) of the token is 86400 seconds (24 hours), hence the new token has to be re-created upon the expiration.
Step 2: When calling our /tests or /results endpoints, use the value returned from the /token endpoint as the Authorization header. (Bearer Token)
We expect for the Token to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer WDoskdWWDkdjsaSWWWSSsht/kn+ca3C9BbWvYDmSWWDDpppmdkdg6ilXwfGAfrjuBsW+ZFBpZAN14NhJjRbuCshZ/JsN5NKMNkdsadsaddaassssdds67Cp19q6rLgjdd0ctYmXyxh9bMiR8+B4q/nSOS3UPmScv9CsoRp7q9vqyOOT37GYHEyXTSifpK5e7/oy40jnXLfsYYma8q2HByPQvOK0=
If you are testing via Swaggerhub, you can click on the "Authorize" button in the user interface, input the returned value and click on "Authorize".
Networks
Request Available Networks
curl -X GET "https://api.telqtele.com/v2.1/client/networks"
-H "accept: application/json"
/*
Keep in mind that to use TelQTestClient,
first you need to initialise it with your app key and app id.
*/
List<Network> networks = testClient.getNetworks();
available_networks = test_client.get_networks()
###
# Keep in mind that to use TelQTelecomAPI,
# first you need to initialise it with your app key and app id (step above).
###
$networks = $api->getNetworks();
foreach ($networks as $network) {
echo 'Mcc: ', $network->getMcc(), PHP_EOL;
echo 'Country name: ', $network->getCountryName(), PHP_EOL;
echo 'Mnc: ', $network->getMnc(), PHP_EOL;
echo 'Provider name: ', $network->getProviderName(), PHP_EOL;
echo 'Ported from mnc: ', $network->getPortedFromMnc() ?: 'empty', PHP_EOL;
echo 'Ported from provider name: ', $network->getPortedFromProviderName() ?: 'empty', PHP_EOL;
echo PHP_EOL;
}
echo 'Networks: ', count($networks), PHP_EOL;
The above command returns:
[
{
"mcc": "262",
"countryName": "Germany",
"mnc": "02",
"providerName": "Vodafone",
"portedFromMnc": "07",
"portedFromProviderName": "Provider"
}
{
"mcc": "505",
"countryName": "Australia",
"mnc": "02",
"providerName": "Optus"
}
]
/*
This will return the list of all available networks at the current moment.
Keep in mind, that this list updated frequently and it's not recommended to use this list to initiate tests after
a long time has passed.
*/
###
# This will return the list of all available networks at the current moment.
# Keep in mind, that this list updated frequently and it's not recommended to use this list to initiate tests after
# a long time has passed.
###
/*
This will return the list of all available networks at the current moment.
Keep in mind, that this list updated frequently and it's not recommended to use this list to initiate tests after
a long time has passed.
*/
This endpoint retrieves a list of all our currently available Networks. Please note that the list of available networks updates frequently and we recommend retrieving the list every minute. The returned values (mcc, mnc, portedFromMnc) will be used in the /test endpoint to request test numbers. Test messages should then be sent from your system to these numbers to perform the test.
mcc is the Mobile Country Code, as defined by The ITU-T Recommendation E.212. This value will always contain 3 digits.
mnc is the Mobile Network Code, as defined by The ITU-T Recommendation E.212. This value can be 2 to 3 digits long.
portedFromMnc indicates from which mnc the phone number has been ported. If this param is not present, the test number has not been ported and belongs to the original network.
/networks
HTTP Request
GET https://api.telqtele.com/v2.1/client/networks
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
Tests
Request New Tests
Request example:
{
"destinationNetworks": [
{
"mcc": "208",
"mnc": "10",
"portedFromMnc": "20"
}
]
}
curl -X POST "https://api.telqtele.com/v2.1/client/tests" -H "accept: */*"
-H "Content-Type: application/json" -d "{ \"destinationNetworks\": [ { \"mcc\": \"208\",
\"mnc\": \"10\", \"portedFromMnc\": \"20\" } ] }"
TestRequest testRequest = TestRequest.builder()
.networks(networks)
.build();
List<Test> requestedTests = testClient.initiateNewTests(testRequest);
destinationNetworks = [
{
"mcc": "206",
"mnc": "10",
"portedFromMnc": "20"
},
{
"mcc": "716",
"mnc": "06"
}
]
###
# A request with only the mandatory (networks) parameter set up within the test client
# object will have this structure:
###
requested_tests = test_client.initiate_new_tests(destinationNetworks=destinationNetworks)
use TelQ\Sdk\Models\Destination;
use TelQ\Sdk\Models\Tests;
// new Destination('mcc', 'mnc', 'ported from mnc')
$sendTests = Tests::fromArray([
'destinationNetworks' => [
new Destination('222', '36', '10'),
new Destination('505', '01')
]
]);
$tests = $api->sendTests($sendTests);
foreach ($tests as $test) {
echo 'Id: ', $test->getId(), PHP_EOL;
echo 'PhoneNumber: ', $test->getPhoneNumber(), PHP_EOL;
echo 'TestIdText: ', $test->getTestIdText(), PHP_EOL;
echo 'Error message: ', $test->getErrorMessage() ?: 'empty', PHP_EOL;
echo 'Destination:', PHP_EOL;
echo ' Mcc: ', $test->getDestinationNetwork()->getMcc(), PHP_EOL;
echo ' Mnc: ', $test->getDestinationNetwork()->getMnc(), PHP_EOL;
echo ' Ported from mnc: ', $test->getDestinationNetwork()->getPortedFromMnc() ?: 'empty', PHP_EOL;
echo PHP_EOL;
}
This Endpoint receives a list with the Destination Networks where you want to send your tests. For each requested network, a test will be created if the network is still available at the time of the test request. Keep in mind that networks can go offline sometimes after the results from the /networks endpoint have been returned.
New in 2.1: To use the dynamic test-id-text feature, you need to provide the testIdTextType with one of the options: "ALPHA", "ALPHA_NUMERIC", "NUMERIC" or "WHATSAPP_CODE". You can also specify the length and case (when applicable). Consult the parameters table for more details. Remember to include your token for Authorization. You can provide a callback URL to receive updates whenever the status of your tests changes. This is optional, as you can also view test results through the /results endpoint.
/tests
POST https://api.telqtele.com/v2.1/client/tests
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
results-callback-token | null | If you would like to authenticate our Test Results Callbacks, you can send an authentication token in this parameter. It will be included as the Authorization bearer token of the callbacks we make to your server. |
Request Details
A request body with all the optional values has the following structure:
{
"destinationNetworks": [
{
"mcc": "206",
"mnc": "10",
"portedFromMnc": "20"
},
{
"mcc": "716",
"mnc": "06",
}
],
"resultsCallbackUrl": "https://some-callback-url.com/some-path",
"testIdTextType": "ALPHA_NUMERIC",
"testIdTextCase": "MIXED",
"testIdTextLength": "6",
"maxCallbackRetries": 1,
"testTimeToLiveInSeconds": 200
}
List<Network> networks = new ArrayList<>();
Network network_1 = Network.builder()
.mcc("206")
.mnc("10")
.portedFromMnc("20")
.build();
Network network_2 = Network.builder()
.mcc("716")
.mnc("06")
.build();
networks.add(network_1);
networks.add(network_2);
int maxCallBackRetries = 1;
String resultsCallbackUrl = "https://some-callback-url.com/some-path";
int testTimeToLive = 200;
String callBackToken = "peHWFdAXikjzmMgqPTwhpeHWFdAXikjzmMgqPTwhpeHWFdAXikjzmMgqPTwh";
TestIdTextOptions testIdTextOptions = TestIdTextOptions.builder()
.testIdTextType(TestIdTextType.ALPHA_NUMERIC)
.testIdTextCase(TestIdTextCase.MIXED)
.testIdTextLength(6)
.build();
TestRequest testRequest = TestRequest.builder()
.networks(networks)
.maxCallbackRetries(maxCallBackRetries)
.callbackUrl(resultsCallbackUrl)
.callbackToken(callBackToken)
.testTimeToLive(testTimeToLive)
.timeUnit(TimeUnit.MINUTES)
.testIdTextOptions(testIdTextOptions)
.build();
List<Test> requestedTests = testClient.initiateNewTests(testRequest);
requested_tests = test_client.initiate_new_tests(
destinationNetworks=destinationNetworks,
resultsCallbackUrl="https://my-callback-url.com/telq_result",
maxCallbackRetries=3,
testIdTextType="ALPHA_NUMERIC",
testIdTextCase="MIXED",
testIdTextLength=7,
testTimeToLiveInSeconds=3000
)
requested_tests = test_client.initiate_new_tests(destinationNetworks=destinationNetworks)
$sendTests = Tests::fromArray([
'destinationNetworks' => [
new Destination('222', '36', '10'),
new Destination('505', '01')
],
'resultsCallbackUrl' => 'https://my-domain.com/telq-callback',
'maxCallbackRetries' => 3,
'testIdTextType' => 'ALPHA',
'testIdTextCase' => 'MIXED',
'testIdTextLength' => 6,
'testTimeToLiveInSeconds' => 3600
]);
The above command returns:
[
{
"id": 894562,
"phoneNumber": "33611223344",
"testIdText": "zlrtyrvdl",
"errorMessage": "null",
"destinationNetwork": {
"mcc": "206",
"mnc": "10",
"portedFromMnc": "20"
}
}
]
###
# This test initiation returns a List of Tests, test response consists of data describing a single test
# initialized. Careful not to lose your test id. Otherwise you won't be able to retrieve test results from our API.
###
/*
This test initiation returns a List of Tests, test response consists of data describing a single test
initialized. Careful not to lose your test id. Otherwise you won't be able to retrieve test results from our API.
*/
JSON Request Object Description
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
destinationNetworks | array | required | null | The list of networks you want to issue tests to. Empty or null value will return an error. |
mcc | string | required | null | The Mobile Country Code for the destination you want to test. This value will always contain 3 digits. |
mnc | string | required | null | The Mobile Network Code for the destination you want to test. This value can be 2 to 3 digits long. |
portedFromMnc | string | optional | null | The Mobile Network Code from which the number you are requesting was ported from. |
resultsCallbackUrl | string | optional | null | The callback URL where you would like to receive TestResult updates anytime the status of your tests changes. |
maxCallbackRetries | integer | optional | 3 | The maximum number of attempts you want us to try when calling your "callback url" with updates. Maximum is 5. |
testIdTextType | string | optional | ALPHA | The type of testIdText to use in this test. Options are: "ALPHA", "ALPHA_NUMERIC", "NUMERIC", "WHATSAPP_CODE". |
testIdTextCase | string | optional | MIXED | The case to use for letters in the testIdText. Applies only to ALPHA and ALPHA_NUMERIC types. Options are: "UPPER", "LOWER", "MIXED". |
testIdTextLength | integer (32) | optimal | 10 | The number of characters to use for generating the testIdText. default=10, minimum=4, maximum=20. Doesn't apply to WHATSAPP_CODE type, since it has a fixed length of 7. |
testTimeToLiveInSeconds | integer | optional | 3600 | The maximum amount of time you want your tests to wait for a message. Default is 1 hour. (Minimum of 1 minute, maximum of 3 hours) |
Response Details
[
{
"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",
}
}
]
/*
This returns a list of all tests that have been initialized. They contain some basic data, and the most important
parameter, test id. You need the test it to request test results.
*/
List<Test> requestedTests = testClient.initiateNewTests(testRequest);
/*
You can get the test id this way. (For example)
*/
Long testId = requestedTests.get(0).getId();
###
# Each test initiation returns a JSON response, containing the test details.
# Most importantly, it contains the phoneNumber, testIdText, and id.
# You will need the (test) id to request the test results.
###
###
# You can get the test id (of the first test) this way:
###
test_id = requested_tests[0].get('id')
// You can get the test result (of the test with id 13777294) this way:
$result = $api->getTestResult(13777294);
echo 'Id: ', $result->getId(), PHP_EOL;
JSON Response Object Description
The response consists of an array of Test objects, containing each a destinationNetwork and details about the test request. Here is a description of each of the keys contained by a Test object:
Object/Key | Data Type | Description |
---|---|---|
destinationNetwork | object | Includes the network details for a destination you requested, for your identification purposes |
mcc | string | The Mobile Country Code for the destination you requested a test to. This value will always contain 3 digits. |
mnc | string | The Mobile Network Code for the destination you requested a test to. This value can be 2 to 3 digits long. |
portedFromMnc | string | The Mobile Network Code from which the number you requested was ported from. This value can be 2 to 3 digits long and can be null |
id | integer (64) | The id number of your test. You will need it to request your test results through our /test-results endpoint or identify results sent to your callback. |
phoneNumber | string | The phone number you must use for performing your test. If null, it means the Network you requested was unavailable at the time of the test. The returned numbers it will always be in international format, without + or 00 in the beginning. |
testIdText | string | The text you must send in the body of your test sms text, used by our systems to identify your test. The length of this string can vary. |
testIdTextType | string | The type of testIdText used this test. Options are: "ALPHA", "ALPHA_NUMERIC", "NUMERIC", "WHATSAPP_CODE" |
testIdTextCase | string | The case used for letters in the testIdText. Applies only to ALPHA and ALPHA_NUMERIC types. Options are: "UPPER", "LOWER", "MIXED" |
testIdTextLength | integer (32) | The number of characters used for generating the testIdText. default=10, minimum=4, maximum=20. Doesn't apply to WHATSAPP_CODE type, since it has a fixed length of 7. |
errorMessage | string | A short description of any errors that prevented your test from being created. |
Test Results
There are two ways to retrieve Test Results:
Using the /results endpoint while providing the testId returned by the /tests endpoint response. Described in this section.
By providing a callback URL that will receive test results each time a test status changes. Described in the next section Callbacks
/results/<id>
curl -X GET "https://api.telqtele.com/v2.1/client/results/23"
-H "accept: */*"
/*
Getting your test result would look like this. Presuming that testId is a variable of type Long
that contains a test id.
*/
Result result = testClient.getTestResult(testId);
###
# Getting your test result would look like this:
###
test_result = test_client.get_test_results(test_id)
$result = $api->getTestResult(13777294);
echo 'Id: ', $result->getId(), PHP_EOL;
echo 'TestIdText: ', $result->getTestIdText(), PHP_EOL;
echo 'Sender delivered: ', $result->getSenderDelivered() ?: 'empty', PHP_EOL;
echo 'Text delivered: ', $result->getTextDelivered() ?: 'empty', PHP_EOL;
echo 'Test created: ', $result->getTestCreatedAt()->format('Y-m-d H:i:s'), PHP_EOL; // return DateTime https://www.php.net/manual/en/class.datetime.php
echo 'Sms received: ', $result->getSmsReceivedAt() ? $result->getSmsReceivedAt()->format('Y-m-d H:i:s'): 'empty', PHP_EOL;
echo 'Receipt delay: ', $result->getReceiptDelay() ?: 'empty', PHP_EOL;
echo 'Test status: ', $result->getTestStatus(), PHP_EOL;
echo 'Network:', PHP_EOL;
if ($result->getDestinationNetworkDetails()) {
echo ' Mcc: ', $result->getDestinationNetworkDetails()->getMcc(), PHP_EOL;
echo ' Country name: ', $result->getDestinationNetworkDetails()->getCountryName(), PHP_EOL;
echo ' Mnc: ', $result->getDestinationNetworkDetails()->getMnc(), PHP_EOL;
echo ' Provider name: ', $result->getDestinationNetworkDetails()->getProviderName(), PHP_EOL;
echo ' Ported from mnc: ', $result->getDestinationNetworkDetails()->getPortedFromMnc() ?: 'empty', PHP_EOL;
echo ' Ported from provider name: ', $result->getDestinationNetworkDetails()->getPortedFromProviderName() ?: 'empty', PHP_EOL;
} else {
echo ' empty', PHP_EOL;
}
echo 'Smsc info:', PHP_EOL;
if ($result->getSmscInfo()) {
echo ' Smsc number: ', $result->getSmscInfo()->getSmscNumber() ?: 'empty', PHP_EOL;
echo ' Country name: ', $result->getSmscInfo()->getCountryName() ?: 'empty', PHP_EOL;
echo ' Country code: ', $result->getSmscInfo()->getCountryCode() ?: 'empty', PHP_EOL;
echo ' Mcc: ', $result->getSmscInfo()->getMcc() ?: 'empty', PHP_EOL;
echo ' Mnc: ', $result->getSmscInfo()->getMnc() ?: 'empty', PHP_EOL;
echo ' Provider name: ', $result->getSmscInfo()->getProviderName() ?: 'empty', PHP_EOL;
} else {
echo ' empty', PHP_EOL;
}
echo 'Pdu delivered: ', $result->getPdusDelivered() ? implode(', ', $result->getPdusDelivered()) : 'empty', PHP_EOL;
HTTP Request
GET https://api.telqtele.com/v2.1/client/results/<id>
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
URL Path Parameters
Parameter | Description |
---|---|
id | The id of the Test. This id is returned by the POST /tests endpoint. |
Response Details
Object/Key | Data Type | Description |
---|---|---|
id | integer (64) | The id of this test |
testIdText | string | The text identifier you sent in the body of your test SMS |
senderDelivered | string | The sender id that was delivered with the test SMS to the phone |
textDelivered | string | The text delivered in the test SMS to the phone |
testCreatedAt | string (ISO 8601) | Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z) |
smsReceivedAt | string (ISO 8601) | Timestamp for when our backend receives notification from our test app that the test SMS was received in the phone. Time is UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z) |
receiptDelay | integer | The number of seconds elapsed between the test request creation and the receipt of the SMS on the mobile device |
testStatus | string | The current status of this test. Options are: WAIT, POSITIVE, NOT_DELIVERED, TEST_NUMBER_NOT_AVAILABLE, INTERNAL_ERROR,TEST_NUMBER_OFFLINE or NETWORK_OFFLINE. See detailed description here |
destinationNetworkDetails | object | Includes the network details for a destination you requested, for identification purposes |
mcc | string | The Mobile Country Code for the destination you have tested. This value will always contain 3 digits. |
mnc | string | The Mobile Network Code for the destination you have tested. This value can be 2 to 3 digits long |
portedFromMnc | string | The Mobile Network Code from which the number you requested was ported from |
countryName | string | The country name of the destination you have tested. |
providerName | string | Provider name of the destination you have tested. |
portedFromProviderName | string | In case the provider has been ported, the name of the provider it has been ported from. |
smscInfo | object | This object contains details about the smsc that delivered the test SMS to the mobile device. We make our best effort to retrieve this data from the supplier, but all the values in this object could be null if they were unavailable |
smscNumber | string | The smsc number that delivered the test SMS. Can be null if unavailable |
countryName | string | The country name for the smsc that delivered the test SMS. Can be null if unavailable |
countryCode | string | The country code for the smsc that delivered the test SMS (ISO Alpha-2). Can be null if unavailable |
mcc | string | The Mobile Country Code for the smsc that delivered the test SMS. This value will always contain 3 digits. Can be null if unavailable |
mnc | string | The Mobile Network Code for the smsc that delivered the test SMS. This value can be 2 to 3 digits long. Can be null if unavailable |
providerName | string | The providerName of the smsc that delivered the test sms. Can be null if unavailable |
pdusDelivered | array[string] | An array of strings containing the Hexadecimal PDUs received by the device |
Test Status
Status | Final Status | Description |
---|---|---|
WAIT | no | This status means we are waiting to receive the test sms in the device with the test number provide. This is the default state of new tests until the sms is received, the TTL expires or the device/network became unavailable |
POSITIVE | yes | Test results change to this status when the test sms you sent through your system has been delivered to the mobile device |
NOT_DELIVERED | yes | Means the TTL of this test has expired and a test sms was never received ont he mobile device |
TEST_NUMBER_NOT_AVAILABLE | no | This status is displayed when our test number has become unnavailable, we will attempt to contact the phone again |
TEST_NUMBER_OFFLINE | yes | The test number we provided has gone offline indefinetly, this is a final state and you will not be billed for this test |
NETWORK_OFFLINE | yes | The network has gone offline for testing. You will not be billed for this test |
INTERNAL_ERROR | yes | This means our systems have suffered an internal error and your test could not be completed. Please contact TelQ Support if this happens. You will not be billed for this test |
Callbacks
If you provided a valid callback URL in your /tests request, our system will send a POST request to said endpoint with a TestResult object each time the test status changes.
Header Parameters
Parameter | Description |
---|---|
Authorization | If a callback URL is present and you provided a value for the results-callback-token header parameter in your tests request, the results-callback-token value will be included as the Authorization value on the callbacks we make to your system so your endpoint can validate the authenticity of the calls. |
Callback Request Details
The POST body of a callback contains JSON structured like this:
{
"id": 23,
"testIdText":"irrgprny",
"senderDelivered":"+4944557775544",
"textDelivered":"irrgprny fgsfgsd",
"testCreatedAt":"2020-02-13T17:01:54.352886Z","smsReceivedAt":"2020-02-13T17:05:27Z",
"receiptDelay":213,
"testStatus":"POSITIVE",
"destinationNetwork": {
"mcc": "206",
"mnc": "10",
"portedFromMnc": "20"
},
"smscInfo":{
"smscNumber":null,
"countryName":"France",
"countryCode":"FR",
"mcc":null,
"mnc":null,
"providerName":null
},
"pdusDelivered":["07913348466110F3040D91945102131605F60880022032225771611165B93BBF0ECBDD7990F93C345FE764"]
}
Object/Key | Data Type | Description |
---|---|---|
id | integer (64) | The id of this test |
testIdText | string | The text identifier you sent in the body of your test SMS |
senderDelivered | string | The sender id that was delivered with the test SMS to the phone |
textDelivered | string | The text delivered in the test SMS to the phone |
testCreatedAt | string (ISO 8601) | Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z) |
smsReceivedAt | string (ISO 8601) | Timestamp for when our backend receives notification from our test app that the test SMS was received in the phone. Time is UTC using the ISO 8601 standard (e.g., 2020-02-13T17:05:27Z) |
receiptDelay | integer | The number of seconds elapsed between the test request creation and the receipt of the SMS on the mobile device |
testStatus | string | The current status of this test. Options are: WAIT, POSITIVE, NOT_DELIVERED, TEST_NUMBER_NOT_AVAILABLE, INTERNAL_ERROR,TEST_NUMBER_OFFLINE or NETWORK_OFFLINE. See detailed description here |
destinationNetwork | object | Includes the network details for a destination you requested, for your identification purposes |
mcc | string | The Mobile Country Code for the destination you want to test. This value will always contain 3 digits. |
mnc | string | The Mobile Network Code for the destination you want to test. This value can be 2 to 3 digits long |
portedFromMnc | string | The Mobile Network Code from which the number you requested was ported from |
smscInfo | object | This object contains details about the smsc that delivered the test SMS to the mobile device. We make our best effort to retrieve this data from the supplier, but all the values in this object could be null if they were unavailable |
smscNumber | string | The smsc number that delivered the test SMS. Can be null if unavailable |
countryName | string | The country name for the smsc that delivered the test SMS. Can be null if unavailable |
countryCode | string | The country code for the smsc that delivered the test SMS (ISO Alpha-2). Can be null if unavailable |
mcc | string | The Mobile Country Code for the smsc that delivered the test SMS. This value will always contain 3 digits. Can be null if unavailable |
mnc | string | The Mobile Network Code for the smsc that delivered the test SMS. This value can be 2 to 3 digits long. Can be null if unavailable |
providerName | string | The providerName of the smsc that delivered the test SMS. Can be null if unavailable |
pdusDelivered | array[string] | An array of strings containing the Hexadecimal PDUs received by the device |
Errors
The TelQ Telecom API version 2.0 uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your appId, appKey or token is incorrect. |
404 | Not Found -- The specified TestResult could not be found. |
405 | Method Not Allowed -- You tried to a method not supported by our API |
406 | Not Acceptable -- You requested a format that isn't JSON. |
500 | Internal Server Error -- We had a problem with our service. Please contact our support team for assistance. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |