Introduction
Welcome to the TelQ Telecom API! You can use our REST API to obtain the list of our available networks, send tests, consult your test results, manage your SMPP sessions and suppliers and more.
API Versions
API Version 3
We recommend our new customers to use this version of the API.
API v3 Update | Description |
---|---|
Live number testing API | With this version, we have introduced the possibility to create Live number testing tests via API. This means our users will be able to specify all the parameters of their SMPP tests, including the sender, text and supplier via which the test SMS will be sent. For more information, see: Live Number Testing |
Sessions and suppliers API | We have introduced the possibility for our users to manage their Sessions and Suppliers on our testing platform directly via API. For more information, see: Sessions and Suppliers |
Batch test results | We have also implemented new API for retrieving test results, which will give our users the option to navigate through all of their Live and Manual testing test results. For more information see related sections: Manual Testing and Live Number Testing |
Networks filtered by MCC/MNC | Last, but not least, we have included optional parameters in the /networks endpoint, which means our users can now request the available networks based on the specified MCC and MNC |
Switching to API v3 from our older API versions
Since we now implemented REST API also for our Live number testing, we decided to modify some of the existing endpoints and parameters in Manual testing API in order to be consistent with the new Live number testing API. Please see all the relevant changes below:
Retrieve Test Results Endpoint
Change | v2.1 | v3 |
---|---|---|
Endpoint URL | GET /client/results/{testId} | GET /client/tests/{testId} |
Field renamed | testStatus | receiptStatus 1 |
Field added | - | phoneNumber 2 |
1testStatus parameter in the test result response has been renamed to receiptStatus to be consistent with our UI naming
2Phone number is now included in the test results' response, within destinationNetworkDetails
Test Submission Endpoint (POST /client/tests)
Change | Field | Description |
---|---|---|
Fields removed | testIdTextType testIdTextCase testIdTextLength |
These fields have been removed in v3 POST /client/tests response body in order to only keep the essential information in the response to the test submission request |
API Version 2.1
In this version, we introduced a new feature that gives our users fine control over the test-id-text to be used within tests.
API Version 2.0
In this version we simplified and standardized our models and provided additional information when available. We provided new features like custom test TTL and callback tokens.
API Version 1.5 and lower
Version 1.5 of the API continues to be supported.
Versions 1.0, 1.1, 1.2, 1.3 and 1.4 have been deprecated and are not supported anymore.
OpenAPI Specification
OpenAPI 3.0 specification for our new API v3 is now public at: https://app.swaggerhub.com/apis/TelQ/testing/v3
You can find the OpenAPI 2.0 specification for our older 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 programming languages from this specification.
TelQ Telecom API SDKs
Coming soon for our new API v3...
To simplify the integration of our API, you can use one of the SDKs that we have prepared:
Programming language | Resource | Latest supported version |
---|---|---|
Java | maven | v1.3.3 |
Python | pypi | 1.3.0 |
PHP | github | v2.0.1 |
Select the corresponding tab (Java/Python/PHP) from the panel on the right for instructions on how to perform the corresponding operations using our SDKs.
Authentication
Authentication example:
# With shell, you can just pass the correct header with each request
curl -X POST "https://api.telqtele.com/v3/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
TelqApi with your app key and app id.
*/
TelqApi telqApi = new TelqApi("<yourAppKey>", "<yourAppId>");
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 TelqApi client 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 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
Endpoint
GET https://api.telqtele.com/v3/client/networks
In API v3, you can use some or all the optional parameters mcc
, mnc
and portedFromMnc
to filter the list of networks:
GET https://api.telqtele.com/v3/client/networks?mcc=231&mnc=03
curl -X GET "https://api.telqtele.com/v3/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.mt.getNetworks();
// You can also filter the list of networks by mcc and mnc
networks = telqApi.mt.getNetworks("631",null);
networks = telqApi.mt.getNetworks(null,"02");
networks = telqApi.mt.getNetworks(null, null, "01");
available_networks = test_client.network.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 the list of our currently available Networks.
The returned values (mcc, mnc, portedFromMnc) will be used in the /tests endpoint to request test numbers.
Test messages should then be sent from your system to these numbers to perform the test.
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
Parameters
Parameter | Required | Default | Description |
---|---|---|---|
mcc | no | null | Return only the networks with this MCC. mcc is the Mobile Country Code, as defined by The ITU-T Recommendation E.212. This value will always contain 3 digits. |
mnc | no | null | Return only the networks with this MNC. 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 | no | null | Return only the networks ported from this MNC. You may set this parameter to null to select only non-ported networks. |
Response body
[
{
"mcc": "231",
"countryName": "Slovakia",
"mnc": "02",
"providerName": "Telekom",
"portedFromMnc": null,
"portedFromProviderName": null
},
{
"mcc": "231",
"countryName": "Slovakia",
"mnc": "03",
"providerName": "Swan",
"portedFromMnc": null,
"portedFromProviderName": null
},
... more networks
]
JSON Request Object Get Networks
Object/Key | Data Type | Description |
---|---|---|
mcc | string | The Mobile Country Code |
mnc | string | The Mobile Network Code |
portedFromMnc | string | The Mobile Network Code of the network from which the number has been ported |
countryName | string | The name of the country |
providerName | string | The name of the provider |
portedFromProviderName | string | The name of the provider from which the number has been ported |
Manual Testing
Create MT tests
Endpoint
POST https://api.telqtele.com/v3/client/tests
Request example:
{
"destinationNetworks": [
{
"mcc": "208",
"mnc": "10",
"portedFromMnc": "20"
}
]
}
New in 3.0: You may now specify the test number directly instead of MCC and MNC.
curl -X POST "https://api.telqtele.com/v3/client/tests" -H "accept: */*"
-H "Content-Type: application/json" -d "{ \"destinationNetworks\": [ { \"mcc\": \"208\",
\"mnc\": \"10\", \"portedFromMnc\": \"20\" } ] }"
# Specify number directly ...
{
"destinationNetworks": [
{
"phoneNumber":"123456789"
}
],
"testIdTextType": "ALPHA_NUMERIC",
"testIdTextCase": "MIXED",
"testIdTextLength": "8",
"maxCallbackRetries": 1,
"testTimeToLiveInSeconds": 200
}
TestRequest testRequest = TestRequest.builder()
.networks(networks)
.build();
List<Test> requestedTests = telqApi.mt.createTests(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.mt.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->sendManualTests($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.
From 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 /tests endpoint.
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 body
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.mt.createTests(testRequest);
requested_tests = test_client.mt.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.mt.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 | The list of networks you want to issue tests to. Empty or null value will return an error. | |
mcc | string | required | The Mobile Country Code for the destination you want to test. This value will always contain 3 digits. | |
mnc | string | required | 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, min. 0 and max. 5. |
testIdTextType | string | optional | ALPHA | The type of testIdText to use in this test. The allowed values 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. The allowed values are: ["UPPER", "LOWER", "MIXED"] |
testIdTextLength | integer (32) | optional | 10 | The number of characters to use for generating the testIdText, min. 4 and max. 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, min. 60 (1 minute), max. 10800 (3 hours) |
Response Body
[
{
"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",
}
}
]
# or ...
[
{
"id": 123399,
"testIdText": "365450",
"phoneNumber": "77055626363",
"errorMessage": null,
"destinationNetwork": {
"mcc": "722",
"mnc": "070",
"portedFromMnc": null
}
}
]
/*
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.mt.createTests(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->getManualTestResult(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. |
errorMessage | string | A short description of any errors that prevented your test from being created. |
Get MT test results
There are three ways to retrieve the MT test results via API:
Using the /tests endpoint with the optional parameters (page, size, order, from and to) returning a page of test results
Using the /tests/{id} endpoint while providing the (test) id returned during test creation returning an individual test result
Providing a callback URL at test creation that will receive test results each time the test status changes. Described in the Callbacks section
Get MT test results page
This endpoint allows our users to:
- Navigate through all their test results.
- Filter for test results within a specified date range.
- Retrieve the most recent test results.
Pagination facilitates the navigation through all the test results. By configuring the order
parameter, you can control the order in which the tests are displayed. By default, tests are sorted in descending order.
Endpoint
GET https://api.telqtele.com/v3/client/tests
New in v3: You can now specify additional parameters in the URL, e.g.:
curl -X GET "https://api.telqtele.com/v3/client/tests?from=2023-09-13T12:47:00Z&to=2023-10-13T12:47:00Z&page=1&size=10&order=asc"
-H "accept: */*"
GET https://api.telqtele.com/v3/client/tests?from=timestamp&to=timestamp&page=0&size=1000&order=asc
/*
Getting your test result would look like this. Presuming that testId is a variable of type Long
that contains a test id.
*/
MtApiTestResultDto result = testClient.mt.getTestById(testId);
// Get a page of test results
PageConf pageConf = PageConf.builder()
.page(1)
.size(10)
.build();
Instant from = Instant.parse("2023-09-13T12:47:00Z");
Instant to = Instant.parse("2023-10-13T12:47:00Z");
Page<MtApiTestResultDto> page = telqApi.mt.getTestPage(pageConf, from, to);
###
# Getting your test result would look like this:
###
test_result = test_client.mt.get_test_results(test_id)
// today tests
$range = new RangeFilter(
new DateTime('today 00:00:00'),
new DateTime('today 23:59:59')
);
$page = 0;
$pageSize = 20;
$results = $api->getManualTestsResults($page, $pageSize, 'desc', $range);
echo 'Page: ', $results->getPage(), PHP_EOL;
echo 'Size: ', $results->getSize(), PHP_EOL;
echo 'Order: ', $results->getOrder(), PHP_EOL;
echo 'Error: ', $results->getError() ?: 'empty', PHP_EOL;
foreach ($results->getContent() as $result) {
echo 'Id: ', $result->getId(), PHP_EOL;
echo 'TestIdText: ', $result->getTestIdText(), PHP_EOL;
}
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
URL Path Parameters
Parameter | Description |
---|---|
page | Specifies the page number, starting from 0 for the first page |
size | Defines the number of items per page. The maximum page size is 1000 results |
order | Controls the sort order based on the specified field and direction |
from | Specifies the start date and time for the range filter, in UTC. ISO 8601 format (2018-10-28T19:34:50.63Z) |
to | Specifies the end date and time for the range filter, in UTC. ISO 8601 format (2018-10-28T19:34:50.63Z) |
Response Body
{
"id": 120970,
"testIdText": "fEgMxrKAEk",
"senderDelivered": null,
"textDelivered": null,
"testCreatedAt": "2023-10-26T10:49:42.442454Z",
"smsReceivedAt": null,
"receiptDelay": null,
"receiptStatus": "WAIT",
"destinationNetworkDetails": {
"mcc": "289",
"mnc": "88",
"portedFromMnc": null,
"countryName": "Abkhazia",
"providerName": "A-Mobile",
"portedFromProviderName": null,
"phone": "79407295193"
},
"smscInfo": {
"smscNumber": "79407777793",
"countryName": null,
"countryCode": null,
"mcc": null,
"mnc": null,
"providerName": null
},
"pdusDelivered": null
}
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 when our system received the information from the test number that the message was delivered |
receiptStatus | 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 |
phoneNumber | string | The phone number used for performing your test |
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 |
Get individual MT test result
This endpoint allows you to retrieve the results of a specific test by its ID.
curl -X GET "https://api.telqtele.com/v3/client/tests/23"
-H "accept: */*"
GET https://api.telqtele.com/v3/client/tests/<id>
Parameter | Description |
---|---|
id | The unique identifier of the test. This id is returned by the POST /tests endpoint. |
Response Body
The response body is identical to the one in Get MT test results page.
Get MT test results via Callback
As an alternative to directly requesting the test results via our endpoints, you can also provide a callback URL at the test creation (resultsCallbackUrl
).
Our system will then send to this callback URL the current status of the test each time it changes. You can see more details about the callback body in the Callbacks section.
Receipt 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 unavailable, we will attempt to contact the phone again |
TEST_NUMBER_OFFLINE | yes | The test number we provided has gone offline indefinitely, 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 |
Sessions
This section documents how you can manage your SMPP Sessions on the TelQ Testing platform via our REST API.
You can create, update, delete and retrieve the list of all your existing sessions.
For details, please refer to the corresponding chapters of this section.
Create session
This endpoint allows you to create a new SMPP session on our platform.
Endpoint
POST https://api.telqtele.com/v3/client/sessions
Request body
curl -X POST "https://api.telqtele.com/v3/client/sessions" \
-H "Content-Type: application/json" \
-d '{
"hostIp": "123.231.12.123",
"hostPort": 2775,
"systemId": "my_session",
"password": "Pghks46i",
"systemType": null,
"throughput": 5,
"destinationTon": 1,
"destinationNpi": 1,
"enabled": true,
"windowSize": 1,
"useSSL": false,
"windowWaitTimeout": 60000
}'
LntApiCreateOrUpdateSessionDto sessionDto = LntApiCreateOrUpdateSessionDto.builder()
.destinationNpi((byte) 0x01)
.destinationTon((byte) 0x00)
.hostIp("testing.test")
.systemId("systemId")
.throughput(10)
.hostPort(123)
.systemType("123")
.useSSL(true)
.windowSize(10)
.password("password")
.build();
LntApiSessionCreationResponseDto session = telqApi.lnt.createSession(sessionDto);
$session = $api->createSession(CreateUpdateSession::fromArray([
'hostIp' => '127.0.0.1',
'hostPort' => 9998,
'systemId' => 'login',
'password' => 'password',
'systemType' => null,
'throughput' => 5,
'destinationTon' => 1,
'destinationNpi' => 1,
'enabled' => false,
'windowSize' => 1,
'useSSL' => false,
'windowWaitTimeout' => 60000
]));
echo 'ID: ', $session->getSmppSessionId(), PHP_EOL;
echo 'Host: ', $session->getHostIp(), ':', $session->getHostPort(), PHP_EOL;
echo 'System ID: ', $session->getSystemId(), PHP_EOL;
echo 'System type: ', $session->getSystemType(), PHP_EOL;
echo 'Enabled: ', $session->getEnabled() ? 'ON' : 'OFF', PHP_EOL;v
sessionData = SessionData(
hostIp="127.0.0.1",
hostPort=34554,
systemId="user",
password="pass",
throughput=5,
destinationTon=1,
destinationNpi=1,
enabled=True,
windowSize=1,
useSSL=False,
windowWaitTimeout=60000
)
response = telq_api.session.create(sessionData)
JSON Request Object Description
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
hostIp | string | yes | SMPP session domain or IP address | |
hostPort | integer | yes | SMPP session port | |
systemId | string | yes | SMPP session system_id, 1-16 characters, cannot contain space |
|
password | string | yes | SMPP session password, 1-9 characters, only latin characters and numbers are allowed |
|
systemType | string | no | null | SMPP session system_type, max. 13 chars |
throughput | integer | no | 5 | SMPP throughput in SMS per second, allowed values [5-50] |
destinationTon | integer | no | 1 | Allowed values [0, 1, 5] |
destinationNpi | integer | no | 1 | Allowed values [0, 1] |
enabled | boolean | no | true | Specifies whether the session will be enabled upon creation, true or false |
windowSize | integer | no | 1 | Allowed values [1-20] |
useSSL | boolean | no | false | Specifies whether the session will use SSL, true or false |
windowWaitTimeout | integer | no | 60000 | Window wait timeout in ms, min. 10000, max. 300000 |
Response body
{
"smppSessionId": 15388,
"hostIp": "123.231.12.123",
"hostPort": 2775,
"systemId": "my_session",
"systemType": null,
"enabled": true
}
JSON Response Object Description
The essential parameters are repeated from the corresponding create session request.
The most important parameter for the subsequent operations is the assigned smppSessionId
:
Object/Key | Data Type | Description |
---|---|---|
smppSessionId | long | assigned unique SMPP session id |
Update session
This endpoint allows you to update an existing session with the specified smppSessionId
PUT https://api.telqtele.com/v3/client/sessions
Request body
curl -X PUT "https://api.telqtele.com/v3/client/sessions" \
-H "Content-Type: application/json" \
-d '{
"smppSessionId": 15412,
"hostIp": "123.172.12.123",
"hostPort": 2775,
"systemId": "my_session_1",
"password": "fh34ryQd",
"systemType": null,
"throughput": 7,
"destinationTon": 1,
"destinationNpi": 1,
"enabled": true,
"windowSize": 1,
"windowWaitTimeout": 60000,
"useSSL": false
}'
LntApiCreateOrUpdateSessionDto sessionDto = LntApiCreateOrUpdateSessionDto.builder()
.smppSessionId(15412)
.destinationNpi((byte) 0x01)
.destinationTon((byte) 0x00)
.hostIp("testing.test")
.systemId("systemId")
.throughput(10)
.hostPort(123)
.systemType("123")
.useSSL(true)
.windowSize(10)
.password("password")
.systemId("sysId")
.enabled(false)
.windowWaitTimeout(10_000L)
.build();
telqApi.lnt.updateSession(sessionDto);
$api->updateSession(CreateUpdateSession::fromArray([
'smppSessionId' => 20603,
'hostIp' => '127.0.0.1',
'hostPort' => 9997,
'systemId' => 'login',
'password' => 'password',
'systemType' => null,
'throughput' => 5,
'destinationTon' => 1,
'destinationNpi' => 1,
'enabled' => false,
'windowSize' => 1,
'useSSL' => false,
'windowWaitTimeout' => 60000
]));
sessionData = SessionData(
hostIp="127.0.0.1",
hostPort=34554,
systemId="user",
password="pass",
throughput=5,
destinationTon=1,
destinationNpi=1,
enabled=True,
windowSize=1,
useSSL=False,
windowWaitTimeout=60000,
smppSessionId=sessionId
)
telq_api.session.update(sessionData)
JSON Request Object Description
Object/Key | Data Type | Required | Description |
---|---|---|---|
smppSessionId | long | yes | Unique identifier of the SMPP session |
hostIp | string | yes | SMPP session domain or IP address |
hostPort | integer | yes | SMPP session port |
systemId | string | yes | SMPP session system_id, 1-16 characters, cannot contain space |
password | string | yes | SMPP session password, 1-9 characters, only latin characters and numbers are allowed |
systemType | string | no | SMPP session system_type, max. 13 characters if not specified, systemType will be set to null |
throughput | integer | yes | SMPP throughput in SMS per second, allowed values [5-50] |
destinationTon | integer | yes | Allowed values [0, 1, 5] |
destinationNpi | integer | yes | Allowed values [0, 1] |
enabled | boolean | yes | Specifies whether the session will be enabled upon creation, true or false |
windowSize | integer | yes | Allowed values [1-20] |
useSSL | boolean | yes | Specifies whether the session will use SSL, true or false |
windowWaitTimeout | integer | yes | Window wait timeout in ms, min. 10000, max. 300000 |
JSON Response Object Description
The update operation was successful if the 200 OK response is returned.
Delete session
This endpoint allows you to delete an existing session.
Endpoint
DELETE https://api.telqtele.com/v3/client/sessions/{smppSessionId}
Parameters
Parameter | Description |
---|---|
smppSessionId | Id of the session being deleted |
Request
curl -X DELETE "https://api.telqtele.com/v3/client/sessions/15412" \
-H "Content-Type: application/json"
telqApi.lnt.deleteSessionById(15412);
$api->deleteSession(20603);
telq_api.session.delete(15412)
The delete operation was successful if the 200 OK response is returned.
Retrieve individual session
This endpoint allows you to request information about an individual session object.
Endpoint
GET https://api.telqtele.com/v3/client/sessions/{smppSessionId}
curl -X GET "https://api.telqtele.com/v3/client/sessions/15388" \
-H "Content-Type: application/json"
LntApiSessionDto sessionWithUserDto = telqApi.lnt.getSessionById(15388L);
$session = $api->getSession(20603);
echo 'ID: ', $session->getSmppSessionId(), PHP_EOL;
echo 'Host: ', $session->getHostIp(), ':', $session->getHostPort(), PHP_EOL;
echo 'System ID: ', $session->getSystemId(), PHP_EOL;
echo 'System type: ', $session->getSystemType(), PHP_EOL;
echo 'Enabled: ', $session->getEnabled() ? 'ON' : 'OFF', PHP_EOL;
echo 'Throughput: ', $session->getThroughput(), PHP_EOL;
echo 'Destination TON: ', $session->getDestinationTon(), PHP_EOL;
echo 'Destination NPI: ', $session->getDestinationNpi(), PHP_EOL;
echo 'Window size: ', $session->getWindowSize(), PHP_EOL;
echo 'Window wait timeout: ', $session->getWindowWaitTimeout(), PHP_EOL;
echo 'SSL: ', $session->getUseSSL() ? 'YES' : 'NO', PHP_EOL;
echo 'User: ', $session->getUserId(), ' ', $session->getUserName(), PHP_EOL;
echo 'Online: ', $session->getOnline() ? 'YES' : 'NO', PHP_EOL;
echo 'Suppliers: ', $session->getSupplierCount(), PHP_EOL;
telq_api.session.get(15388)
Parameters
Parameter | Default | Description |
---|---|---|
smppSessionId | null | Unique identifier of the SMPP session |
Response body
JSON Response Object Description
{
"smppSessionId": 15388,
"hostIp": "123.321.12.123",
"hostPort": 2775,
"systemId": "my_session",
"systemType": null,
"throughput": 5,
"destinationTon": 1,
"destinationNpi": 1,
"enabled": true,
"userId": 1,
"userName": "userName",
"online": false,
"lastError": "Unable to connect to host [123.123.123.123] and port [123] within 10000 ms",
"windowSize": 1,
"useSSL": false,
"windowWaitTimeout": 60000,
"supplierCount": 2
}
Object/Key | Data Type | Description |
---|---|---|
smppSessionId | long | Unique identifier of the SMPP session |
hostIp | string | SMPP session domain or IP address |
hostPort | integer | SMPP session port |
systemId | string | SMPP session system_id |
systemType | string | SMPP session system_type |
throughput | integer | SMPP throughput in SMS per second |
destinationTon | integer | [0, 1, 5] |
destinationNpi | integer | [0, 1] |
enabled | boolean | True if the session is currently enabled |
userId | long | Unique identifier of the user that created this session |
userName | string | Username of the user that created this session |
online | boolean | True if the session is currently online |
lastError | string | Returns the last error associated with this session |
windowSize | integer | Window size, [1-20] |
useSSL | boolean | True, if the session is using SSL protocol |
windowWaitTimeout | integer | Window wait timeout in milliseconds |
supplierCount | integer | Total number of suppliers assigned to this session object |
Retrieve sessions page
This endpoint allows you to retrieve information about your existing sessions.
Pagination facilitates the navigation through the sessions, with the optional parameters page
and size
.
Endpoint
GET https://api.telqtele.com/v3/client/sessions?page=0&size=25
curl -X GET "https://api.telqtele.com/v3/client/sessions?page=0&size=25" \
-H "Content-Type: application/json"
PageConf pageConf = PageConf.builder()
.page(0)
.size(20)
.build();
Page<LntApiSessionDto> sessions = telqApi.lnt.getSessions(pageConf);
// first page, 20 items per page, sort - desc by id
$sessions = $api->getSessions(0, 20, 'desc');
echo 'Total count: ', $sessions->getTotalElements(), PHP_EOL;
echo 'Total pages: ', $sessions->getTotalPages(), PHP_EOL, PHP_EOL;
foreach ($sessions->getContent() as $session) {
echo 'ID: ', $session->getSmppSessionId(), PHP_EOL;
echo 'Host: ', $session->getHostIp(), ':', $session->getHostPort(), PHP_EOL;
echo 'System ID: ', $session->getSystemId(), PHP_EOL;
echo 'System type: ', $session->getSystemType(), PHP_EOL;
echo 'Enabled: ', $session->getEnabled() ? 'ON' : 'OFF', PHP_EOL;
echo 'Throughput: ', $session->getThroughput(), PHP_EOL;
echo 'Destination TON: ', $session->getDestinationTon(), PHP_EOL;
echo 'Destination NPI: ', $session->getDestinationNpi(), PHP_EOL;
echo 'Window size: ', $session->getWindowSize(), PHP_EOL;
echo 'Window wait timeout: ', $session->getWindowWaitTimeout(), PHP_EOL;
echo 'SSL: ', $session->getUseSSL() ? 'YES' : 'NO', PHP_EOL;
echo 'User: ', $session->getUserId(), ' ', $session->getUserName(), PHP_EOL;
echo 'Online: ', $session->getOnline() ? 'YES' : 'NO', PHP_EOL;
echo 'Suppliers: ', $session->getSupplierCount(), PHP_EOL, PHP_EOL;
}
telq_api.session.list(page=0, size=20).get('content')
Parameters
Parameter | Required | Default | Description |
---|---|---|---|
page | no | 0 | Page number |
size | no | 20 | Amount of elements per page |
Response body
{
"content": [
{
"smppSessionId": 15415,
"hostIp": "122.23.243.12",
"hostPort": 2775,
"systemId": "session_132",
"systemType": null,
"throughput": 5,
"destinationTon": 1,
"destinationNpi": 1,
"enabled": true,
"userId": 1,
"online": true,
"lastError": null,
"windowSize": 1,
"useSSL": null,
"windowWaitTimeout": 60000,
"supplierCount": 1
},
{
"smppSessionId": 15414,
"hostIp": "122.23.243.15",
"hostPort": 2775,
"systemId": "session_131",
"systemType": null,
"throughput": 5,
"destinationTon": 1,
"destinationNpi": 1,
"enabled": true,
"userId": 2,
"online": false,
"lastError": "Unable to connect to host [122.122.122.122] and port [122] within 10000 ms",
"windowSize": 1,
"useSSL": null,
"windowWaitTimeout": 60000,
"supplierCount": 1
}
... (more elements)
],
"pageable": {
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 10,
"paged": true,
"unpaged": false
},
"totalPages": 4,
"last": false,
"totalElements": 35,
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"size": 10,
"number": 0,
"first": true,
"numberOfElements": 10,
"empty": false
}
JSON Response Object Description
Object/Key | Data Type | Description |
---|---|---|
content | array | Contains the list of corresponding session objects. The size of the list is determined by the size request parameter |
pageable | object | Contains information about the corresponding paginated result such as: page number, sorting info, page size etc. |
totalPages | integer | Total number of pages for the selected size of paginated response |
last | boolean | True if the corresponding page is the last one |
totalElements | integer | Total number of existing sessions |
sort | object | Returns the sorting configuration of the page |
size | integer | Amount of elements per page |
number | integer | Current page number |
first | boolean | True if the current page is the first |
empty | boolean | True if there are no existing sessions |
For detailed information about the session object within the content section, please refer to Retrieve individual session section.
Suppliers
This section documents how you can manage your Suppliers on the TelQ Testing platform via our REST API.
You can create, update, delete and retrieve the list of all your existing suppliers.
For details, please refer to the corresponding chapters of this section.
Create supplier
This endpoint allows you to create a new supplier and assign it to an existing session.
Endpoint
POST https://api.telqtele.com/v3/client/suppliers
Request body
curl -X POST "https://api.telqtele.com/v3/client/suppliers" \
-H "Content-Type: application/json" \
-d '{
"smppSessionId": 15388,
"supplierName": "My supplier",
"routeType": "Wholesale",
"attributeList": [
"DOMESTIC"
],
"comment": "My first supplier",
"serviceType": null,
"tlv": [
{
"tagHex": "ABCD",
"valueHex": "AAAA"
}
],
"udh": [
{
"tagHex": "AB",
"valueHex": "ABCD"
}
]
}'
LntApiCreateOrUpdateSupplierDto supplierDto = LntApiCreateOrUpdateSupplierDto.builder()
.supplierName("supplierName")
.attributeList(Arrays.asList(RouteAttribute.DLR, RouteAttribute.SPAM))
.comment("comment text")
.routeType("Wholesale")
.serviceType("434")
.smppSessionId(session.getSmppSessionId())
.tlvs(Arrays.asList(LntApiTlvDto.builder().tagHex("AAAA").valueHex("BBBB").build()))
.udhs(Arrays.asList(LntApiUdhDto.builder().tagHex("AA").valueHex("BBBB").build()))
.build();
LntApiSupplierCreationResponseDto supplier = telqApi.lnt.createSupplier(supplierDto);
$supplier = $api->createSupplier(CreateUpdateSupplier::fromArray([
'supplierName' => 'TestSupplier',
'routeType' => 'direct',
'attributeList' => ['TWO_WAY', 'P2P'],
'comment' => null,
'serviceType' => null,
'tlv' => [
new UdhTlv('1B1A', '1AAF')
],
'udh' => [
new UdhTlv('1F', '11BB')
],
'smppSessionId' => 20602
]));
echo 'Supplier ID: ', $supplier->getSupplierId(), PHP_EOL;
echo 'Session ID: ', $supplier->getSmppSessionId(), PHP_EOL;
echo 'Name: ', $supplier->getSupplierName(), PHP_EOL;
echo 'Route type: ', $supplier->getRouteType(), PHP_EOL;
echo 'Attributes: ', implode(', ', $supplier->getAttributeList()), PHP_EOL;
echo 'Service type: ', $supplier->getServiceType(), PHP_EOL;
echo 'Comment: ', $supplier->getComment(), PHP_EOL;
supplierData = SupplierData(
smppSessionId=sessionId,
supplierName="test supplier",
routeType="Wholesale"
)
response = telq_api.supplier.create(supplierData)
supplierId = response.get('supplierId')
JSON Request Object Description
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
smppSessionId | long | yes | Id of the session to which the new supplier will be assigned | |
supplierName | string | yes | Name of the supplier, max. 30 chars Pre-defined values: [Direct, Wholesale, Premium, HQ, SIM, SS7, Other] |
|
routeType | string | yes | Route type of the supplier, max. 30 chars | |
attributeList | array | no | null | Attributes of the supplier. The allowed values for the array elements are: [DOMESTIC, INTERNATIONAL, TRANSACTIONAL, PROMOTIONAL, PRE_REGISTRATION, SHORT_CODE, LONG_CODE, TWO_WAY, P2P, SMSC, DLR, SPAM] |
comment | string | no | null | Custom comment associated with the supplier, max. 100 chars |
serviceType | string | no | null | Service type of the supplier, max. 5 chars |
tlv | array | no | null | An array of TLV values defined in HEX format for the supplier as: tagHex and valueHex |
udh | array | no | null | An array of UDH values defined in HEX format for the supplier as: tagHex and valueHex |
Response body
{
"supplierId": 1403,
"smppSessionId": 15388,
"supplierName": "My supplier",
"routeType": "Wholesale",
"attributeList": [
"DOMESTIC"
],
"comment": "My first supplier",
"serviceType": null
}
JSON Response Object Description
The essential parameters are repeated from the corresponding create supplier request.
The most important parameter for the subsequent operations is the assigned supplierId
:
Object/Key | Data Type | Description |
---|---|---|
supplierId | long | Assigned unique Supplier id |
Update supplier
This operation allows you to update the existing supplier with the specified supplierId
.
Endpoint
PUT https://api.telqtele.com/v3/client/suppliers
Request body
curl -X PUT "https://api.telqtele.com/v3/client/suppliers" \
-H "Content-Type: application/json" \
-d '{
"supplierId": 1411,
"supplierName": "supplier-123-123",
"routeType": "Wholesale",
"attributeList": [
"P2P", "INTERNATIONAL"
],
"comment": "comment 123",
"serviceType": null,
"tlv": [
{
"tagHex": "BBBB",
"valueHex": "BBBB"
}
],
"udh": [
{
"tagHex": "AA",
"valueHex": "AAAA"
}
]
}'
LntApiCreateOrUpdateSupplierDto supplierDto = LntApiCreateOrUpdateSupplierDto.builder()
.supplierId(1411L)
.supplierName("supplierName")
.attributeList(Arrays.asList(RouteAttribute.DLR, RouteAttribute.SPAM))
.comment("comment text")
.routeType("Wholesale")
.serviceType("434")
.smppSessionId(session.getSmppSessionId())
.tlvs(Arrays.asList(LntApiTlvDto.builder().tagHex("AAAA").valueHex("BBBB").build()))
.udhs(Arrays.asList(LntApiUdhDto.builder().tagHex("AA").valueHex("BBBB").build()))
.build();
telqApi.lnt.updateSupplier(supplierDto);
$api->updateSupplier(CreateUpdateSupplier::fromArray([
'supplierId' => 73115,
'supplierName' => 'TestSupplier',
'routeType' => 'direct',
'attributeList' => ['TWO_WAY', 'P2P'],
'comment' => 'My comment',
'serviceType' => null,
'tlv' => [
new UdhTlv('1B1A', '1AAF')
],
'udh' => [
new UdhTlv('1F', '11BB')
],
'smppSessionId' => 20602
]));
supplierData = SupplierData(
supplierId=supplierId,
supplierName="test supplier",
routeType="Wholesale"
)
telq_api.supplier.update(supplierData)
JSON Request Object Description
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
supplierId | long | yes | Unique identifier of the supplier being updated | |
supplierName | string | yes | Name of the supplier, max. 30 chars | |
routeType | string | yes | Route type of the supplier, max. 30 chars Pre-defined values: [Direct, Wholesale, Premium, HQ, SIM, SS7, Other] |
|
attributeList | array | no | null | Attributes of the supplier. Allowed values for array elements: [DOMESTIC, INTERNATIONAL, TRANSACTIONAL, PROMOTIONAL, PRE_REGISTRATION, SHORT_CODE, LONG_CODE, TWO_WAY, P2P, SMSC, DLR, SPAM] |
comment | string | no | null | Custom comment associated with the supplier, max. 100 chars |
serviceType | string | no | null | Service type of the supplier, max. 5 chars |
tlv | array | no | null | An array of TLV values defined in HEX format for the supplier as: tagHex and valueHex |
udh | array | no | null | An array of UDH values defined in HEX format for the supplier as: tagHex and valueHex |
JSON Response Object Description
The update operation was successful if the 200 OK response is returned.
Delete supplier
This endpoint allows you to delete an existing supplier.
Endpoint
DELETE https://api.telqtele.com/v3/client/suppliers/{supplierId}
Parameters
Parameter | Description |
---|---|
supplierId | Unique identifier of the supplier being deleted |
Request
curl -X DELETE "https://api.telqtele.com/v3/client/supplier/1411" \
-H "Content-Type: application/json"
telqApi.lnt.deleteSupplierById(1411L);
$api->deleteSupplier(73115);
telq_api.supplier.delete(supplierId)
The delete operation was successful if the 200 OK response is returned.
Re-assign Suppliers
This is a bulk operation that allows our users to re-assign a list of existing suppliers to another SMPP session.
Endpoint
POST https://api.telqtele.com/v3/client/suppliers/assign
Request body
curl -X PUT "https://api.telqtele.com/v3/client/suppliers/assign" \
-H "Content-Type: application/json" \
-d '{
"smppSessionId" : 15388,
"supplierIds" : [1401, 1402, 1403]
}'
Set<Long> supplierIds = new HashSet<>();
supplierIds.addAll(Arrays.asList(1401, 1402, 1403));
LntApiAssignSuppliersDto assignDto = LntApiAssignSuppliersDto.builder()
.smppSessionId(15388)
.supplierIds(supplierIds)
.build()
telqApi.lnt.assignSuppliersToSession(assignDto);
$supplierIds = [73115, 73113];
$sessionId = 20602;
$api->assignSuppliersToSession($supplierIds, $sessionId);
telq_api.supplier.assign(smpp_session_id=sessionId1, supplier_id_list=[supplierId])
JSON Request Object Description
Object/Key | Data Type | Required | Description |
---|---|---|---|
smppSessionId | long | yes | Unique identifier of the SMPP session to which all the specified suppliers will be assigned |
supplierIds | array | yes | An array of supplierId 's of the user's suppliers which will be assigned to the specified session |
JSON Response Object Description
The re-assign operation was successful if the 200 OK response is returned.
Retrieve individual supplier
This endpoint allows you to request information about an individual supplier object.
Endpoint
GET https://api.telqtele.com/v3/client/suppliers/{supplierId}
Parameters
Parameter | Default | Description |
---|---|---|
supplierId | null | Unique identifier of the requested supplier |
curl -X GET "https://api.telqtele.com/v3/client/suppliers/1411" \
-H "Content-Type: application/json"
LntApiSupplierDto updatedSupplier = telqApi.lnt.getSupplierById(1411L);
$supplier = $api->getSupplier(73115);
JSON Response Object Description
{
"supplierId": 1400,
"supplierName": "Supplier 5",
"routeType": "Wholesale",
"attributeList": null,
"comment": "no comment",
"serviceType": null,
"tlv": [],
"udh": []
"smppSessionId": 15405,
"userId": 1
}
Object/Key | Data Type | Description |
---|---|---|
supplierId | long | Unique identifier of the supplier |
smppSessionId | long | Unique identifier of the SMPP session to which the supplier is assigned |
supplierName | string | Name of the supplier |
routeType | string | Route type of the supplier |
attributeList | array | Attributes of the supplier. Allowed values for array elements: [DOMESTIC, INTERNATIONAL, TRANSACTIONAL, PROMOTIONAL, PRE_REGISTRATION, SHORT_CODE, LONG_CODE, TWO_WAY, P2P, SMSC, DLR, SPAM] |
comment | string | Custom comment associated with the supplier |
userId | long | Unique identifier of the user that created this supplier |
serviceType | string | Service type of the supplier |
tlv | array | An array of TLV values defined in HEX format for the supplier as: tagHex and valueHex |
udh | array | An array of UDH values defined in HEX format for the supplier as: tagHex and valueHex |
Retrieve suppliers page
This endpoint allows you to retrieve information about your existing suppliers.
Pagination facilitates the navigation through the suppliers, with the optional parameters page
and size
.
Endpoint
GET https://api.telqtele.com/v3/client/suppliers?page=0&size=25
Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number |
size | 20 | Amount of elements per page |
curl -X GET "https://api.telqtele.com/v3/client/suppliers" \
-H "Content-Type: application/json"
PageConf pageConf = PageConf.builder()
.page(0)
.size(20)
.build();
Page<LntApiSupplierDto> suppliers = telqApi.lnt.getSuppliers(pageConf);
// first page, 20 items per page, sort - desc by id
$suppliers = $api->getSuppliers(0, 20, 'desc');
echo 'Total count: ', $suppliers->getTotalElements(), PHP_EOL;
echo 'Total pages: ', $suppliers->getTotalPages(), PHP_EOL, PHP_EOL;
foreach ($suppliers->getContent() as $supplier) {
echo 'Supplier ID: ', $supplier->getSupplierId(), PHP_EOL;
echo 'Session ID: ', $supplier->getSmppSessionId(), PHP_EOL;
echo 'Name: ', $supplier->getSupplierName(), PHP_EOL;
echo 'Route type: ', $supplier->getRouteType(), PHP_EOL;
echo 'Attributes: ', implode(', ', $supplier->getAttributeList()), PHP_EOL;
echo 'Service type: ', $supplier->getServiceType(), PHP_EOL;
echo 'UDH: ', count($supplier->getUdh()), PHP_EOL;
echo 'TLV: ', count($supplier->getTlv()), PHP_EOL;
echo 'Comment: ', $supplier->getComment(), PHP_EOL;
echo 'User: ', $supplier->getUserId(), PHP_EOL, PHP_EOL;
}
Response body
{
"content": [
{
"supplierId": 1425,
"supplierName": "test-supplier-public-api1",
"routeType": "Wholesale",
"attributeList": [
"DOMESTIC"
],
"comment": "comment",
"serviceType": null,
"tlv": [],
"udh": [],
"smppSessionId": 10588,
"userId": 2726
},
{
"supplierId": 1424,
"supplierName": "testSession",
"routeType": "Wholesale",
"attributeList": [
"DOMESTIC"
],
"comment": null,
"serviceType": null,
"tlv": [],
"udh": [],
"smppSessionId": 10588,
"userId": 2726
},
{
"supplierId": 1423,
"supplierName": "supplier999",
"routeType": "Wholesale",
"attributeList": null,
"comment": null,
"serviceType": null,
"tlv": null,
"udh": null,
"smppSessionId": null,
"userId": 850
},
... (more elements)
],
"pageable": {
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"pageNumber": 0,
"pageSize": 100,
"offset": 0,
"paged": true,
"unpaged": false
},
"totalPages": 1,
"last": true,
"totalElements": 63,
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"first": true,
"numberOfElements": 63,
"size": 100,
"number": 0,
"empty": false
}
JSON Response Object Description
Object/Key | Data Type | Description |
---|---|---|
content | array | Contains the list of corresponding supplier objects. The size of the list is determined by the size request parameter |
pageable | object | Contains information about the corresponding paginated result such as: page number, sorting info, page size etc. |
totalPages | integer | Total number of pages for selected size of paginated response |
last | boolean | True if the corresponding page is the last one |
totalElements | integer | Total number of existing suppliers |
sort | object | Returns the sorting configuration of the page |
size | integer | Amount of elements per page |
number | integer | Current page number |
first | boolean | True if the current page is the first page |
empty | boolean | True if the are no existing suppliers |
For detailed information about the supplier object within the content section, please refer to the Retrieve individual supplier section
Retrieve suppliers status list
This endpoint allows you to retrieve live information about your suppliers and their corresponding sessions to check their current availability.
Endpoint
GET https://api.telqtele.com/v3/client/sessions-suppliers?page=0&size=25
Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number |
size | 20 | Amount of elements per page |
curl -X GET "https://api.telqtele.com/v3/client/sessions-suppliers?page=0&size=20" \
-H "Content-Type: application/json"
PageConf pageConf = PageConf.builder()
.page(0)
.size(20)
.build();
Page<LntApiSessionsSuppliersStatusResponse> suppliersStatusResponsePage =
telqApi.lnt.getSessionSuppliers(pageConf);
$pairs = $api->getSessionsSuppliers(0, 20, 'desc');
echo 'Total count: ', $pairs->getTotalElements(), PHP_EOL;
echo 'Total pages: ', $pairs->getTotalPages(), PHP_EOL, PHP_EOL;
foreach ($pairs->getContent() as $pair) {
echo 'Supplier ID: ', $pair->getSupplierId(), PHP_EOL;
echo 'Session ID: ', $pair->getSmppSessionId(), PHP_EOL;
echo 'Name: ', $pair->getSupplierName(), PHP_EOL;
echo 'Route type: ', $pair->getRouteType(), PHP_EOL;
echo 'Attributes: ', implode(', ', $pair->getAttributes()), PHP_EOL;
echo 'Online: ', $pair->getOnline() ? 'YES' : 'NO', PHP_EOL, PHP_EOL;
}
telq_api.supplier.list_status().get('content')
Response body
{
"content": [
{
"smppSessionId": 313,
"supplierId": 809,
"supplierName": "My supplier",
"routeType": "Direct",
"online": true,
"attributeList": []
},
{
"smppSessionId": 313,
"supplierId": 810,
"supplierName": "My other supplier",
"routeType": "Wholesale",
"online": false,
"attributeList": []
},
... (more elements)
],
"pageable": {
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"pageNumber": 0,
"pageSize": 100,
"offset": 0,
"paged": true,
"unpaged": false
},
"totalPages": 1,
"last": true,
"totalElements": 63,
"sort": {
"unsorted": false,
"sorted": true,
"empty": false
},
"first": true,
"numberOfElements": 63,
"size": 100,
"number": 0,
"empty": false
}
JSON Response Object Description
Object/Key | Data Type | Description |
---|---|---|
content | array | Contains the list of corresponding session-supplier objects (described below). The size of the list is determined by the size request parameter |
pageable | object | Contains information about the corresponding paginated result such as: page number, sorting info, page size etc. |
totalPages | integer | Total number of pages for the selected size of paginated response |
last | boolean | True if the corresponding page is the last one |
totalElements | integer | Total number of existing objects |
sort | object | Returns the sorting configuration of the page |
size | integer | Amount of elements per page |
number | integer | Current page number |
first | boolean | True if the current page is the first one |
empty | boolean | True if there are no existing session-supplier objects |
JSON Response Object Description (individual session-supplier object)
Object/Key | Data Type | Description |
---|---|---|
routeType | string | Route type of the supplier |
online | boolean | True if the corresponding session is now online |
smppSessionId | long | Unique identifier of the corresponding SMPP session |
supplierName | string | Name of the supplier |
supplierId | long | Unique identifier of the supplier |
attributeList | array | Attributes of the supplier. Allowed values for array elements: [DOMESTIC, INTERNATIONAL, TRANSACTIONAL, PROMOTIONAL, PRE_REGISTRATION, SHORT_CODE, LONG_CODE, TWO_WAY, P2P, SMSC, DLR, SPAM] |
Live Number Testing
Create LNT tests
This endpoint allows you to trigger Live number testing tests via API, in batches or individually.
Endpoint
POST https://api.telqtele.com/v3/client/lnt/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 Body
curl -X POST https://api.telqtele.com/v3/client/lnt/tests \
-H "Content-Type: application/json" \
-d '{
"tests": [
{
"sender": "Google",
"text": "G-{TEST_ID_TEXT} is your Google verification code",
"testIdTextType": "NUMERIC",
"testIdTextLength": 6,
"supplierId": 17,
"mcc": "603",
"mnc": "01",
"portedFromMnc": "01"
},
// ...more tests
],
"resultsCallbackUrl": "https://some-callback-url.com/some-path",
"maxCallbackRetries": 2,
"dataCoding": "01", // [00, 01, 03, 08, F0]
"sourceTon": "02", // [00, 01, 02, 03, 04, 05, 06]
"sourceNpi": "12", // [00, 01, 03, 04, 06, 08, 09, 0A, 0E, 12]
"testTimeToLiveInSeconds": 600,
"smppValidityPeriod": 120,
"scheduledDeliveryTime": "2209131247000000", // format YYMMDDhhmmsstnnp
"replaceIfPresentFlag": 0,
"priorityFlag": 1,
"sendTextAsMessagePayloadTlv": 0,
"commentText": "Optional comment",
"tlv": [{
"tagHex":"1B1A", // only HEX values (2 bytes length)
"valueHex":"1AAF" // only HEX values
}
],
"udh":[{
"tagHex":"1F", // only HEX values (1 byte length)
"valueHex": "11BB" // only HEX values
}]
}'
// single test
LntApiTestRequestDto testRequestDto = LntApiTestRequestDto.builder()
.tests(Collections.singletonList(
LntApiCreateTestDto.builder()
.sender("123456789")
.text("Hello, World!")
.testIdTextLength(6)
.supplierId(6L)
.mcc("412")
.mnc("88")
.build()
)).build();
// advanced options
testRequestDto = LntApiTestRequestDto.builder()
.maxCallbackRetries(3)
.dataCoding("01")
.commentText("my comment")
.priorityFlag(Byte.valueOf("1"))
.testTimeToLiveInSeconds(360)
.sourceNpi("02")
.sourceTon("01")
.smppValidityPeriod(360)
.resultsCallbackUrl("https://example.com/callback")
.sendTextAsMessagePayloadTlv(false)
.scheduledDeliveryTime("2209131247000000")
.replaceIfPresentFlag(false)
.udh(Collections.singletonList(
LntApiUdhDto.builder()
.tagHex("1F")
.valueHex("11BB")
.build()
))
.tlv(Collections.singletonList(
LntApiTlvDto.builder()
.tagHex("1B1A")
.valueHex("1AAF")
.build()
))
.tests(Collections.singletonList(
LntApiCreateTestDto.builder()
.sender("123456789")
.text("Hello, World!")
.testIdTextLength(6)
.testIdTextCase(TestIdTextCase.MIXED)
.testIdTextType(TestIdTextType.NUMERIC)
.portedFromMnc(null)
.supplierId(6L)
.mcc("412")
.mnc("88")
.build()
)).build();
LntApiCreateTestResponseDto testsCreated = telqApi.lnt.createTests(testRequestDto);
tests = [Test(
sender="Google",
text="This is sample message",
testIdTextType="ALPHA",
testIdTextCase="LOWER",
testIdTextLength=7,
supplierId=6,
mcc="276",
mnc="02",
portedFromMnc=None
)]
telq_api.lnt.initiate_new_tests(tests)
use TelQ\Sdk\Models\Lnt\LiveNumberTest;
use TelQ\Sdk\Models\Lnt\LiveNumberTests;
use TelQ\Sdk\Models\UdhTlv;
$sendTests = LiveNumberTests::fromArray([
'tests' => [
LiveNumberTest::fromArray([
'sender' => '123456789',
'text' => 'Hello, World!',
'testIdTextType' => 'NUMERIC',
'testIdTextCase' => 'MIXED',
'testIdTextLength' => 6,
'supplierId' => 6,
'mcc' => '412',
'mnc' => '88'
])
],
'resultsCallbackUrl' => 'https://example.com/callback',
'maxCallbackRetries' => 3,
'dataCoding' => '01',
'sourceTon' => '01',
'sourceNpi' => '02',
'testTimeToLiveInSeconds' => 360,
'smppValidityPeriod' => 360,
'scheduledDeliveryTime' => new DateTime('2022-09-13 12:47:00'),
'replaceIfPresentFlag' => 0,
'priorityFlag' => 1,
'sendTextAsMessagePayloadTlv' => 0,
'commentText' => 'my comment',
'tlv' => [
new UdhTlv('1B1A', '1AAF')
],
'udh' => [
new UdhTlv('1F', '11BB')
],
]);
$response = $api->sendLiveNumberTests($sendTests);
# Specifying the phone number directly ...
"tests": [
{
"sender": "Google",
"text": "G-{TEST_ID_TEXT} is your Google verification code",
"testIdTextType": "NUMERIC",
"testIdTextLength": 6,
"supplierId": 17,
"phoneNumber":"123456789"
},
// ...more tests
],
JSON Request Object Description Test Group
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
tests | array | required | The list of Live number tests that will be created | |
tlv | array | no | null | An array of TLV values defined in HEX format for the supplier as: tagHex and valueHex |
udh | array | no | null | An array of UDH values defined in HEX format for the supplier as: tagHex and valueHex |
dataCoding | string | no | SMPP data_coding parameter The allowed values are: [00, 01, 03, 08, F0] If not specified, our system will determine the appropriate setting based on the sender and text parameters |
|
sourceTon | string | no | SMPP source_addr_ton parameter The allowed values are: [00, 01, 02, 03, 04, 05, 06] If not specified, our system will determine the appropriate setting based on the sender parameter |
|
sourceNpi | string | no | SMPP source_addr_npi parameter The allowed values are: [00, 01, 03, 04, 06, 08, 09, 0A, 0E, 12] If not specified, our system will determine the appropriate setting based on the sender parameter |
|
priorityFlag | byte | no | 1 | SMPP priority_flag parameter |
smppValidityPeriod | int | no | null | SMPP validity_period parameter in s, min. 60(1 min) and max. 86400(1 day) |
testTimeToLiveInSeconds | int | no | 3600 | The time to live (TTL) for the test, in seconds, min. 60(1 min) and max. 10800(3h) |
commentText | string | no | null | Custom comment associated with the test |
resultsCallbackUrl | string | no | null | Callback URL to receive all the status updates of the tests |
maxCallbackRetries | int | no | 3 | The maximum number of retries for the callback, min. 0 and max. 5 |
replaceIfPresentFlag | boolean | no | false | SMPP replace_if_present_flag parameter |
sendTextAsMessagePayloadTlv | boolean | no | false | Send text as message payload TLV |
scheduledDeliveryTime | string | no | null | SMPP schedule_delivery_time parameter |
JSON Request Object Description Test
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
sender | string | required | The sender with which the test SMS will be submitted | |
text | string | required | The text of the test SMS. Use {TEST_ID_TEXT} as a placeholder to place the test id text anywhere within the text. |
|
supplierId | string | required | The unique identifier of the user's supplier via which the test SMS will be sent | |
mcc | string | required | The MCC mobile country code of the test destination | |
mnc | string | required | The MNC mobile network code of the test destination | |
portedFromMnc | string | optional | null | The ported from network code of the test destination |
phoneNumber | string | optional | null | As an alternative to specifying the MCC-MNC of a network, you can also specify the test number directly. Please note that we do not recommend testing external phone numbers since they do not have our software installed, which means that we cannot retrieve the Receipt confirmation from them. We consider an external number a number which is not part of our test number pool. |
testIdTextType | string | optional | "ALPHA_NUMERIC" | The test ID text type parameter The allowed values are: "ALPHA", "ALPHA_NUMERIC", "NUMERIC", "WHATSAPP_CODE" |
testIdTextCase | string | optional | "MIXED" | The test ID text case parameter The allowed values are: "UPPER", "LOWER", "MIXED" |
testIdTextLength | string | optional | 6 | The test ID text length parameter, min. 4, max. 20 |
JSON Request Object Description TLV
Object/Key | Data Type | Description |
---|---|---|
tagHex | string | The TLV tag |
valueHex | string | The TLV value |
JSON Request Object Description UDH
Object/Key | Data Type | Description |
---|---|---|
tagHex | string | The UDH tag |
valueHex | string | The UDH value |
Response Body
// Response body
{
"tests": [
{
"id": 1151236,
"testIdText": "iFnRrJ",
"phoneNumber": "79407295193",
"destinationNetwork": {
"mcc": "289",
"mnc": "88",
"portedFromMnc": null
},
"errorMessage": null
}
],
"error": null
}
JSON Object Description Create Test Response
Object/Key | Data Type | Description |
---|---|---|
tests | array | The list of Live number testing tests that were created |
error | string | A short description of any errors that prevented the test group from being created |
JSON Object Description Test
Object/Key | Data Type | Description |
---|---|---|
id | integer | The unique identifier of your test. You will need it to request your test results via our /tests endpoint or to identify results sent to your callback |
testIdText | string | The text identifier included in the body of your test SMS |
phoneNumber | string | The phone number used for performing your test. If null, it means the Network you requested was unavailable at the time of the test. The returned numbers will always be in international format, without + or 00 in the beginning |
destinationNetwork | object | Includes the network details for the destination you requested, for your identification purposes |
errorMessage | string | A short description of any errors that prevented the test from being created |
JSON Object Description Destination Network
Object/Key | Data Type | Description |
---|---|---|
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 |
Get LNT test results
There are three ways to retrieve the LNT test results via API:
Using the /lnt/tests endpoint with the optional parameters (page, size, order, from and to) returning a page of test results
Using the /lnt/tests/{id} endpoint while providing the (test) id returned during test creation returning an individual test result
Providing a callback URL at test creation that will receive test results each time a test status changes. Described in the Callbacks section
Get LNT test results page
This endpoint allows our users to:
- Navigate through all their test results.
- Filter for test results within a specified date range.
- Retrieve the most recent test results.
Pagination facilitates the navigation through all the test results. By configuring the order
parameter, you can control the order in which the tests are displayed. By default, tests are sorted in descending order.
Endpoint
GET https://api.telqtele.com/v3/client/lnt/tests
Parameters
Parameter | Required | Default | Description |
---|---|---|---|
page | no | 0 | Specifies the page number, starting from 0 for the first page |
size | no | 20 | Defines the number of items per page. The maximum page size is 1000 results |
order | no | DESC | Controls the sort by id based on the specified direction |
from | no | null | Specifies the start date and time for the range filter, in UTC. ISO 8601 format (2018-10-28T19:34:50.63Z) |
to | no | null | Specifies the end date and time for the range filter, in UTC. ISO 8601 format (2018-10-28T19:34:50.63Z) |
Sample uses of the optional parameters
curl -X GET "https://api.telqtele.com/v3/client/lnt/tests" \
-H "Content-Type: application/json"
Retrieving the most recent test results:
GET https://api.telqtele.com/v3/client/lnt/tests
curl -X GET "https://api.telqtele.com/v3/client/lnt/tests?page=0&size=1000&order=asc" \
-H "Content-Type: application/json"
PageConf pageConfig = PageConf.builder()
.page(0)
.size(1000)
.order(PageConf.Order.ASC)
.build();
Page<LntApiTestResultDto> tests = telqApi.lnt.getTestPage(pageConfig, null, null);
telq_api.lnt.get_test_results(date_from, date_to, page=1, size=20, order="asc")
$results = $api->getLiveNumberTestsResults(0, 1000, 'asc');
Retrieving test results using the optional parameters for page, size and order:
GET https://api.telqtele.com/v3/client/lnt/tests?page=0&size=1000&order=asc
curl -X GET "https://api.telqtele.com/v3/client/lnt/tests?from=2023-10-18T10:14:04.038983Z&to=2023-10-20T10:14:04.038983Z&page=0&size=100&order=asc" \
-H "Content-Type: application/json"
Page<LntApiTestResultDto> tests = telqApi.lnt.getTestPage(
null,
Instant.parse("2023-10-18T10:14:04.038983Z"),
Instant.parse("2023-10-18T10:14:08.038983Z")
);
$range = new RangeFilter(
new DateTime('2023-10-18 10:14:04'),
new DateTime('2023-10-18 10:14:08')
);
$results = $api->getLiveNumberTestsResults(0, 1000, 'desc', $range);
Filtering for test results within a specified date range:
GET https://api.telqtele.com/v3/client/lnt/tests?from=2023-10-18T10:14:04.038983Z&to=2023-10-20T10:14:04.038983Z
curl -X GET "https://api.telqtele.com/v3/client/lnt/tests?size=1" \
-H "Content-Type: application/json"
To retrieve the most recent test result, specify the size parameter as 1:
GET https://api.telqtele.com/v3/client/lnt/tests?size=1
Response Body
{
"content": [
{
"id": 1013798,
"testIdText": "590359",
"senderSent": "Google",
"senderDelivered": "Google",
"textSent": "G-{TEST_ID_TEXT} is your Google verification code.",
"textDelivered": "G-590359 is your Google verification code.",
"testCreatedAt": "2023-10-18T10:14:04.038983Z",
"smppSessionId": 1,
"supplier": {
"supplierId": 6,
"supplierName": "TelQ",
"routeType": "Wholesale"
},
"smsReceivedAt": "2023-10-18T10:14:08.038983Z",
"receiptStatus": "POSITIVE",
"dlrStatus": "DELIVERED",
"receiptDelay": 4,
"dlrDelay": 7,
"scheduledTaskId": null,
"destinationNetworkDetails": {
"mcc": "204",
"mnc": "16",
"portedFromMnc": null,
"countryName": "Netherlands",
"providerName": "T-Mobile",
"portedFromProviderName": null,
"phoneNumber": "31639654167",
"manualNumber": null
},
"smscInfo": {
"smscNumber": "+46707990043",
"countryName": "Sweden",
"countryCode": "SE",
"mcc": "240",
"mnc": "07",
"providerName": "Tele2"
},
"retry": false,
"pdusDelivered": [
"0791947106004034040BD0C7F7FBCC2E0300003201622104638021B618AC76B3DD40E93928FFAECB41F6B23C6D4E8FC3F4F4DB0D1ABFC965"
],
"user": {
"id": 2837,
"email": "[email protected]",
"username": "TelQ_Demo",
"fullName": "TelQ Telecom"
}
},
// more tests ...
],
"page": 0,
"size": 20,
"order": "asc",
"error": null
}
JSON Request Object Get Tests Response
Object/Key | Data Type | Description |
---|---|---|
content | array | The list of Live number testing tests |
page | string | The page number |
size | string | The page size |
order | string | The sorting order |
error | string | The error message |
JSON Request Object Test
Object/Key | Data Type | Description |
---|---|---|
id | number | The unique identifier of the test |
testIdText | string | The test ID text |
senderSent | string | The submitted sender |
senderDelivered | string | The sender delivered to our test device |
textSent | string | The submitted text |
textDelivered | string | The text delivered to our test device |
testCreatedAt | string | The test creation timestamp ISO 8601 format (2018-10-28T19:34:50.63Z) |
smppSessionId | number | The ID of SMPP session via which the test was sent |
supplier | object | The supplier object |
smsReceivedAt | string | The timestamp of the SMS received ISO 8601 format (2018-10-28T19:34:50.63Z) |
receiptStatus | string | The Receipt status |
dlrStatus | string | The DLR status |
receiptDelay | number | The Receipt delay |
dlrDelay | number | The DLR delay |
scheduledTaskId | number | The Scheduled task ID in case the test was triggered by a scheduled task |
destinationNetworkDetails | object | The destination network details object |
smscInfo | object | The SMSC info object |
retry | boolean | True if this test was a retry (backup test) |
pdusDelivered | array | The list of PDUs delivered to our test device |
user | object | The user who sent the test |
JSON Request Object Supplier
Object/Key | Data Type | Description |
---|---|---|
supplierId | number | The unique identifier of the supplier |
supplierName | string | The name of the supplier |
routeType | string | The route type of the supplier |
JSON Request Object Destination Network Details
Object/Key | Data Type | Description |
---|---|---|
mcc | string | The MCC mobile country code |
mnc | string | The MNC mobile network code |
portedFromMnc | string | The ported from network |
countryName | string | The country name |
providerName | string | The provider name |
portedFromProviderName | string | The ported from provider name |
phoneNumber | string | The test phone number |
manualNumber | boolean | True if the number was manually specified |
JSON Request Object SMSC Info
Object/Key | Data Type | Description |
---|---|---|
smscNumber | string | The SMSC number |
countryName | string | The country name |
countryCode | string | The country code |
mcc | string | The MCC mobile country code |
mnc | string | The MNC mobile network code |
providerName | string | The provider name |
JSON Request Object User
Object/Key | Data Type | Description |
---|---|---|
id | number | The unique user identifier |
string | The user's email | |
username | string | The user's username |
fullName | string | The user's full name |
Get individual LNT test result
This endpoint allows you to retrieve the results of a specific test by its ID.
curl -X GET "https://api.telqtele.com/v3/client/lnt/tests/1155470" \
-H "Content-Type: application/json"
LntApiTestResultDto test = telqApi.lnt.getTestById(1155470L);
$api->getLiveTestResult(1155470);
GET https://api.telqtele.com/v3/client/lnt/tests/<id>
Parameter | Description |
---|---|
id | The unique identifier of the test. This id is returned by the POST /tests endpoint. |
Response Body
The response body is identical to the one in Get LNT test results page.
Get LNT test results via Callback
As an alternative to directly requesting the test results via our endpoints, you can also provide a callback URL at the test creation (resultsCallbackUrl
).
Our system will then send to this callback URL the current status of the test each time it changes. You can see more details about the callback body in the Callbacks section below.
CLI Testing
Get CLI testing networks
Endpoint
GET https://api.telqtele.com/v3/client/cli/networks
curl -X GET "https://api.telqtele.com/v3/client/cli/networks"
-H "accept: application/json"
You can use some or all the optional parameters mcc
, mnc
and portedFromMnc
to filter the list of networks:
GET https://api.telqtele.com/v3/client/cli/networks?mcc=231&mnc=03
This endpoint retrieves the list of Networks currently available for CLI testing.
The returned values (mcc, mnc, portedFromMnc) will be used in the /tests endpoint to request test numbers.
Test call should then be triggered from your system to these numbers to perform the tests.
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
Parameters
Parameter | Required | Default | Description |
---|---|---|---|
mcc | no | null | Return only the networks with this MCC. mcc is the Mobile Country Code, as defined by The ITU-T Recommendation E.212. This value will always contain 3 digits. |
mnc | no | null | Return only the networks with this MNC. 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 | no | null | Return only the networks ported from this MNC. You may set this parameter to null to select only non-ported networks. |
Response body
The above command returns:
[
{
"mcc": "732",
"countryName": "Colombia",
"mnc": "154",
"providerName": "Virgin Mobile (MVNO)",
"portedFromMnc": "101",
"portedFromProviderName": "Claro"
},
{
"mcc": "470",
"countryName": "Bangladesh",
"mnc": "02",
"providerName": "Airtel",
"portedFromMnc": null,
"portedFromProviderName": null
}
]
JSON Request Object Get Networks
Object/Key | Data Type | Description |
---|---|---|
mcc | string | The Mobile Country Code |
mnc | string | The Mobile Network Code |
portedFromMnc | string | The Mobile Network Code of the network from which the number has been ported |
countryName | string | The name of the country |
providerName | string | The name of the provider |
portedFromProviderName | string | The name of the provider from which the number has been ported |
Create CLI tests
Endpoint
POST https://api.telqtele.com/v3/client/cli/tests
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.
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 Body
Request example:
{
"destinationNetworks": [
{
"mcc": "732",
"mnc": "154",
"portedFromMnc": "101"
}
],
"resultsCallbackUrl": "https://some-callback-url.com/some-path",
"maxCallbackRetries": 1,
"testTimeToLiveInSeconds": 120
}
JSON Request Object Description
Object/Key | Data Type | Required | Default Value | Description |
---|---|---|---|---|
destinationNetworks | array | required | The list of networks you want to issue tests to. Empty or null value will return an error | |
mcc | string | required | The Mobile Country Code for the destination you want to test. This value will always contain 3 digits | |
mnc | string | required | 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, min. 0 and max. 5 |
testTimeToLiveInSeconds | integer | optional | 60 | The maximum amount of time you want your tests to wait for a call, min. 60 (1 minute), max. 600 (10 mins) |
Response Body
// Response body
{
"tests": [
{
"id": 108,
"phoneNumber": "33611223344",
"destinationNetwork": {
"mcc": "712",
"mnc": "01",
"portedFromMnc": "045"
},
"errorMessage": null
}
],
"error": null
}
JSON Object Description Create Test Response
Object/Key | Data Type | Description |
---|---|---|
tests | array | The list of CLI testing tests that were created |
error | string | A short description of any errors that prevented the test group from being created |
JSON Object Description Test
Object/Key | Data Type | Description |
---|---|---|
id | integer | The unique identifier of your test. You will need it to request your test results via our /tests endpoint or to identify results sent to your callback |
phoneNumber | string | The phone number used for performing your test. If null, it means the Network you requested was unavailable at the time of the test. The returned numbers will always be in international format, without + or 00 in the beginning |
destinationNetwork | object | Includes the network details for the destination you requested, for your identification purposes |
errorMessage | string | A short description of any errors that prevented the test from being created |
JSON Object Description Destination Network
Object/Key | Data Type | Description |
---|---|---|
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 |
Get test result
Endpoint
This endpoint allows you to retrieve the results of a specific test by its ID.
curl -X GET "https://api.telqtele.com/v3/client/cli/tests/{testId}" \
-H "Content-Type: application/json"
GET https://api.telqtele.com/v3/client/cli/tests/{testId}
Header Parameters
Parameter | Default | Description |
---|---|---|
Authorization | null | The Bearer Token for authorization |
Response example:
{
"id": 170,
"testCreatedAt": "2024-06-04T15:17:41.090834Z",
"callReceivedOnPhoneAt": "2024-06-04T15:18:06.106Z"
"callReceivedOnServerAt": "2024-06-05T16:08:27.617361897Z",
"destinationNetworkDetails": {
"mcc": "732",
"mnc": "154",
"portedFromMnc": "101",
"countryName": "Colombia",
"providerName": "Virgin Mobile (MVNO)",
"portedFromProviderName": "Claro",
"phoneNumber": "5513974217124"
},
"receiptStatus": "RECEIVED",
"receiptDelay": 25,
"CLI": "01719354273",
"userId": 1234
}
Response body
Object/Key | Data Type | Description |
---|---|---|
id | integer (64) | The test ID of this test |
testCreatedAt | string (ISO 8601) | Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:20.973465Z) |
callReceivedOnPhoneAt | string (ISO 8601) | Timestamp for when our test app detected the test call on the phone. Time is UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:58.650Z) |
callReceivedOnServerAt | string (ISO 8601) | Timestamp for when our backend received the notification about the test call received on the phone. Time is UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:59.598971270Z) |
destinationNetworkDetails | object | Includes the network details of the destination of the test call |
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 |
countryName | string | The country name for the destination network |
providerName | string | The provider name for the destination network |
portedFromProviderName | string | The provider name from which the number you requested was ported |
phoneNumber | string | Test number used for the test call |
receiptStatus | string | The current status of this test. Options are: WAIT, RECEIVED, EXPIRED, TEST_NUMBER_OFFLINE, NETWORK_OFFLINE or INTERNAL_ERROR. |
receiptDelay | integer | The amount of seconds between the test request creation and when our system received the information from the test number that the call was received |
CLI | string | The Calling Line Identification (CLI) used for the test call |
userId | string | The ID of the user that sent this test |
Callbacks
Callbacks are available for Manual testing and Live number testing test results.
In addition to test result callbacks, we also offer the option to request Scheduler alert callbacks within our UI. The body of such Scheduler alert callback can be found in the Scheduler alert section.
Manual testing
If you provided a valid callback URL in your /tests request, our system will send a POST request to the specified endpoint with a TestResult object anytime the status of your test 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,
"receiptStatus":"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 when our system received the information from the test number that the message was delivered |
receiptStatus | string | The current receipt 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 |
Live number testing
If you provided a valid callback URL in your /tests request, our system will send a POST request to the specified endpoint with a TestResult object anytime the status (either DLR or Receipt) of your test changes.
Alternatively, you can provide a valid callback URL in our UI within the Integration settings / API menu.
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": 4246,
"testIdText": "249165",
"senderSent": "IMO",
"senderDelivered": "IMO",
"textSent": "{TEST_ID_TEXT} is your code",
"textDelivered": "249165 is your code",
"testCreatedAt": "2020-02-13T17:01:54.352886Z",
"sessionId": 8,
"supplier": {
"supplierId": 17,
"supplierName": "GT",
"routeType": "DIRECT"
},
"smsReceivedAt": "2020-02-13T17:03:54.352886Z",
"receiptStatus": "POSITIVE",
"dlrStatus": "DELIVERED",
"receiptDelay": 10,
"dlrDelay": 9,
"scheduledTaskId": null,
"testIdTextType": "NUMERIC",
"testIdTextCase": null,
"testIdTextLength": 6,
"destinationNetworkDetails": {
"mcc": "427",
"mnc": "01",
"portedFromMnc": null,
"countryName": "Qatar",
"providerName": "Ooredoo",
"portedFromProviderName": null,
"phone": "97450775267",
"manualNumber": null
},
"smscInfo": {
"smscNumber": "+97477922224",
"countryCode": "QA",
"mcc": "427",
"mnc": "02",
"providerName": "Vodafone"
},
"retry": false,
"pdusDelivered": [
"07917974972222F42406D0C9E61300004220509095352113325A2E66AB81D27350FE5D9783C66F7219"
],
"username": "example-telecom"
}
Object/Key | Data Type | Description |
---|---|---|
id | integer (64) | The test ID of this test |
testIdText | string | The text identifier sent in the body of your test SMS |
senderSent | string | The Sender ID that was sent with the test SMS to the phone |
senderDelivered | string | The Sender ID that was delivered with the test SMS to the phone |
textSent | string | The text sent in 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) |
sessionId | integer (64) | The ID of the SMPP session via which this test was sent |
supplier | object | The details of supplier used to send this test |
smsReceivedAt | string (ISO 8601) | Timestamp for when our backend received 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) |
receiptStatus | string | The current status of this test. Options are: WAIT, POSITIVE, TEXT_REPLACED, SENDER_REPLACED, NOT_DELIVERED, TEST_NUMBER_NOT_AVAILABLE, TEST_NUMBER_OFFLINE, SMPP_SESSION_OFFLINE, NETWORK_OFFLINE or INTERNAL_ERROR. See detailed description here |
dlrStatus | string | Delivery report received from the supplier via SMPP |
receiptDelay | integer | The number of seconds elapsed between the test request creation and when our system received the information from the test number that the message was delivered |
dlrDelay | integer | The number of seconds between the time when we received the confirmation that the SMS has been submitted (submit_sm resp) and the time when we receive the DLR in our system (deliver_sm) |
scheduledTaskId | integer | The ID of the scheduled task that triggered this test |
destinationNetworkDetails | object | Includes the network details of the destination to which the test SMS was sent |
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 |
phone | string | Test number to which the test SMS was sent |
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 this object can be null if no information is available |
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 |
retry | boolean | True if this test was a retry |
pdusDelivered | array[string] | An array of strings containing the Hexadecimal PDUs received by the test device |
username | string | The username of the user that sent this test |
CLI testing
If you provided a valid callback URL in your /tests request, our system will send a POST request to the specified endpoint with a TestResult object anytime the status of your test 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": 170,
"testCreatedAt": "2024-06-04T15:17:41.090834Z",
"callReceivedOnPhoneAt": "2024-06-04T15:18:06.106Z"
"callReceivedOnServerAt": "2024-06-05T16:08:27.617361897Z",
"destinationNetworkDetails": {
"mcc": "732",
"mnc": "154",
"portedFromMnc": "101",
"countryName": "Colombia",
"providerName": "Virgin Mobile (MVNO)",
"portedFromProviderName": "Claro",
"phoneNumber": "5513974217124"
},
"receiptStatus": "RECEIVED",
"receiptDelay": 25,
"CLI": "01719354273",
"userId": 1234
}
Object/Key | Data Type | Description |
---|---|---|
id | integer (64) | The test ID of this test |
testCreatedAt | string (ISO 8601) | Timestamp for when the test request was created in UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:20.973465Z) |
callReceivedOnPhoneAt | string (ISO 8601) | Timestamp for when our test app detected the test call on the phone. Time is UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:58.650Z) |
callReceivedOnServerAt | string (ISO 8601) | Timestamp for when our backend received the notification about the test call received on the phone. Time is UTC using the ISO 8601 standard (e.g., 2024-06-07T10:19:59.598971270Z) |
destinationNetworkDetails | object | Includes the network details of the destination of the test call |
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 |
countryName | string | The country name for the destination network |
providerName | string | The provider name for the destination network |
portedFromProviderName | string | The provider name from which the number you requested was ported |
phoneNumber | string | Test number used for the test call |
receiptStatus | string | The current status of this test. Options are: WAIT, RECEIVED, EXPIRED, TEST_NUMBER_OFFLINE, NETWORK_OFFLINE or INTERNAL_ERROR. |
receiptDelay | integer | The amount of seconds between the test request creation and when our system received the information from the test number that the call was received |
CLI | string | The Calling Line Identification (CLI) used for the test call |
userId | string | The ID of the user that sent this test |
Scheduler alert
Callback URL
The Callback URL can be added within our UI in the last step of the scheduler task configuration. This URL is where the API will send a callback request if any reporting rules apply.
The callback will contain the report data structured as shown below.
{
"reportId": 1, // Unique identifier for the report
"createdAt": "2021-01-01T00:00:00Z", // ISO 8601 formatted date and time when the report was created
"scheduledTaskId": 12345,
"scheduledTaskTitle": "Austria&Germany", // Title of the scheduled task
"testId": 1029746, // Identifier for the associated test
"senderId": "Google",
"text": "G-{TEST_ID_TEXT} is your Google verification code.",
"phone": "50687058156",
"sessionId": 2130,
"supplier": {
"supplierId": 6,
"supplierName": "Telq", // Name of the supplier
"routeType": "RT" // Type of route used
},
"reportRule": {
"receiptStatus": "NOT_DELIVERED", // Current status of the test (refer to the list of available test statuses)
"receiptStatusWaitingTimeSec": 3600, // Time in seconds to wait for a test status change (range: 1-86400, here representing 1 hour)
"dlrStatus": "UNKNOWN", // Current state of the message (refer to the list of available message states)
"dlrStatusWaitingTimeSec": 3600 // Time in seconds to wait for a message state change (range: 1-86400, here representing 1 hour)
},
"receiptDelay": 6,
"dlrDelay": 7,
"callbackUrl": "https://tools.telqtele.com/callback-random"
}
Object/Key | Description |
---|---|
reportId | Unique identifier of the report |
createdAt | ISO 8601 formatted date and time when the report was created |
scheduledTaskId | Unique identifier of the corresponding Scheduled task |
scheduledTaskTitle | Title of the corresponding scheduled task |
testId | Unique identifier of the associated test |
senderId | Sender of the corresponding test |
text | Text of the corresponding test |
phone | Test number that was used for the corresponding test |
sessionId | Unique identifier of the SMPP session via which the corresponding test was sent |
supplier | Supplier object |
supplierId | Unique identifier of the Supplier via which the corresponding test was sent |
supplierName | Name of the supplier |
routeType | Route type of the supplier |
reportRule | Scheduler alert rule object |
receiptStatus | Receipt status rule that triggered this alert |
receiptStatusWaitingTimeSec | Time in seconds to wait for this Receipt status change (range: 1-86400, here representing 1 hour) |
dlrStatus | DLR status rule that triggered this alert |
dlrStatusWaitingTimeSec | Time in seconds to wait for this DLR status change (range: 1-86400, here representing 1 hour) |
receiptDelay | The number of seconds elapsed between the test request creation and when our system received the information from the test number that the message was delivered |
dlrDelay | The number of seconds between the time when we received the confirmation that the SMS has been submitted (submit_sm resp) and the time when we receive the DLR in our system (deliver_sm) |
callbackUrl | The callback URL at which the Scheduler alert is being received |
Available Receipt and DLR statuses
Status | Status Type | Description |
---|---|---|
WAIT | Rec.status | Initial Receipt status |
POSITIVE | Rec.status | Test message was delivered without any modification or error |
NOT_DELIVERED | Rec.status | No SMS was received during TTL (default 1 hour) on our test device |
SENDER_REPLACED | Rec.status | Sender differs in received SMS. Status may be overwritten by TEXT_REPLACED |
TEXT_REPLACED | Rec.status | Text differs in received SMS. Overwrites SENDER_REPLACED |
TEST_NUMBER_NOT_AVAILABLE | Rec.status | Applies if the test number becomes unavailable during the test. This is an intermediate status and can be overwritten |
INTERNAL_ERROR | Rec.status | This status is set when some unexpected error happens during test execution. This is a final status |
TEST_NUMBER_OFFLINE | Rec.status | Final Receipt status |
NETWORK_OFFLINE | Rec.status | We don't have any available test numbers in the chosen destination at the moment. This is a final status |
SMPP_SESSION_OFFLINE | Rec.status | The SMPP connection was offline when attempting to send this test |
NO_DLR_RECEIVED | Rec. status | The SMS was submitted correctly, but we didn’t receive any deliver_sm within the set time limit (test TTL) |
PARTIALLY_DELIVERED | Rec. status | For concatenated messages, when we received a deliver_sm for some of the message parts, but not for all the parts |
SUBMIT_SM_FAILED | Rec. status | We didn't receive the positive submit_sm_resp back from the SMS platform within the time limit (60s) |
PENDING | DLR status | Default TelQ DLR status, returned when no DLR has been received from the SMS platform and the TTL of the test has not yet expired |
SCHEDULED | DLR status | |
ENROUTE | DLR status | |
DELIVERED | DLR status | |
EXPIRED | DLR status | |
DELETED | DLR status | |
UNDELIVERABLE | DLR status | |
ACCEPTED | DLR status | |
UNKNOWN | DLR status | |
REJECTED | DLR status | |
SKIPPED | DLR status |
Errors
The TelQ Telecom API version 3 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. |