This documentation provides instructions on how to quickly integrate Premium messaging services into various solutions by using Qikli SMS HTTP application programming interface (HTTP API). Use HTTP API for sending SMS messages.
The API is based on REST standards, enabling you to use your browser for accessing URLs.
Use any HTTP client in any programming language to interact with our API.
HTTP API INTRODUCTION
The HTTP application programming interface (HTTP API) is the easiest way to integrate Qikli SMS services using standardized REST interface.
Base URL
Submit all requests to the base URL. All the requests are submitted through HTTP POST or GET method.
Although you can use HTTP protocol, we strongly recommend you to submit all requests to the API over HTTPS so the traffic is encrypted and privacy is ensured.
Base URL: http://api.sms.qikli.com/sms/2/text/advanced
Content-Type & Accept header
The API supports JSON and XML Content-Types and Accept criteria that should be specified
in the header. If the Content-Type is not specified you will receive a General error. Depending on which Accept type is chosen in the deader for the request, the same one will be applied in the response.
Content-Type: application/json or application/xml
Accept header: application/json or application/xml
Authorization
We support basic authorization using a username and password with Base64 encoding variation
RFC2045-MIME.
The authorization header is constructed as follows:
1. Username and password are combined into a string username:password.
2. The resulting string is encoded using the RFC2045-MIME variant of Base64.
The authorization method and a space, like this: "Basic", are put before the encoded string
Example
Username: Aladdin Password: open sesame Base64 encoded string: QWxhZGRpbjpvcGVuIHNlc2FtZQ== Authorization header: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
SEND SMS
First, you'll need a valid Qikli SMS account.
Next, your username and password has to be encoded in base64 like described in the
Authorization Section
The message will be sent only to a valid phone number (numbers), written in international format E.g. 233201133119. We strongly recommend using the E.164 number formatting. E.164 numbers are internationally standardized to a fifteen digit maximum length. Phone numbers are usually prefixed with + (plus sign), followed by a country code, network code and the subscriber number. Phone numbers that are not E.164 formatted may work, depending on the handset or network.
POST http://api.sms.qikli.com/sms/2/text/advanced
Full JSON request sample is shown below:
{
"messages":
[
{
"from": "SAMPLESENDER",
"destinations":
[
{
"to": "233205072987\\",
"messageId": "MESSAGE-ID-127-xyz"
}
],
"to": "2332xxxxxxxx",
"text": "A long time ago, in a galaxy far, far away"
}
],
"bulkId": "BULK-ID-123-xyz",
"tracking":
{
"track": "SMS",
"type": "MY_CAMPAIGN"
}
}
Response sample
{
"bulkId": "BULK-ID-123-xyz",
"messages": [
{
"to": "2332xxxxxxxx",
"status": {
"groupId": 1,
"groupName": "PENDING",
"id": 26,
"name": "MESSAGE_ACCEPTED",
"description": "Message sent to next instance"
},
"messageId": "MESSAGE-ID-127-xyz"
}
]
}
messages is an array of all SMS messages that were sent in the last request. In our case, it
contains only one message.
to is a phone number which you have sent the SMS message to
Each message successfully submitted to Qikli SMS platform is uniquely identified with
the messageId. Furthermore, the Message ID can be used for checking delivery
status or sent messages logs.
status is the object that further describes the state of the sent message.
For a full list of available statuses, please check the end of this document.
GET DELIVERY REPORTS
If you are for any reason unable to receive real time delivery reports on your endpoint, you can use this API method to learn if and when the message has been delivered to the recipient. Each request will return a batch of delivery reports - only once. The following API request will return only new reports that arrived since the last API request.
GET http://api.sms.qikli.com/sms/1/reports
Available query parameters are:
bulkId: The ID uniquely identifies the sent SMS request. This filter will enable you to
receive delivery reports for all the messages using just one request. You will receive
a bulkId in the response after sending a SMS request, or you can set a custom one.
messageId: The ID that uniquely identifies the message sent. You will receive
a messageId in the response after sending a message, or you can set a custom one.
limit: The maximum number of delivery reports you want to get. Default value is 50.
As a response, you will get a collection of unread delivery reports.
Important: Delivery reports can only be retrieved one time. Once you retrieve a delivery report, you will not be able to get the same report again by using this endpoint.
Request example
http://api.sms.qikli.com/sms/1/reports?messageId=MESSAGE-ID-123-xyz&limit=2
Response
{
"results":[
{
"bulkId":"BULK-ID-123-xyz",
"messageId":"MESSAGE-ID-123-xyz",
"to":"41793026727",
"sentAt":"2019-11-09T16:00:00.000+0000",
"doneAt":"2019-11-09T16:00:00.000+0000",
"smsCount":1,
"price":{
"pricePerMessage":0.01,
"currency":"EUR"
},
"status":{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
},
"error":{
"groupId":0,
"groupName":"Ok",
"id":0,
"name":"NO_ERROR",
"description":"No Error",
"permanent":false
}
]
}
Note: If you try making this same request again, you will get an empty set because all delivery reports were read:
If you send a mass number of messages but you are only interested in seeing the delivery report for only one, just set a query parameter in the request.
Append ?messageId=xxxxxxx to the request URL, and you will get a delivery report only for that message.
RESPONSE CODES
Status Groups
|
GroupId |
GroupName |
Description |
|
0 |
ACCEPTED |
Message is accepted. |
|
1 |
PENDING |
Message is in pending status. |
|
2 |
UNDELIVERABLE |
Message is undeliverable. |
|
3 |
DELIVERED |
Message is delivered. |
|
4 |
EXPIRED |
Message is expired. |
|
5 |
REJECTED |
Message is rejected. |