Thermolinks SMS API docs
The RESTful API allows developers to expand and build their apps on Matrix. The API makes it easy to send messages to one or many destinations, check balance and routing, as well as enabling bulk messaging.
SMS Messages can be transmitted using the RESTful api, the following requirements must be met to enable the service:
You need a Matrix user account
You need sufficient credit on your Matrix user account
Services
The Services resource represents all web services currently available via Thermolinks’s RESTful API.
Authentication
Services having the /secure/ path (such as Send a single message and Route check) require authentication using Basic Auth which transmits Matrix account credentials as username/password pairs, encoded using base64.
Example:
curl -X GET -H 'Authorization: Basic Zm9vOmJhcg==' http://jasmin.thermolinks.com:8080/secure/balanceWe have passed the base64 encoded credentials through the Authorization header, ‘Zm9vOmJhcg==’ is the encoded username:password pair (‘foo:bar’), you can use any tool to base64 encode/decode.
If wrong or no authentication credentials are provided, a 401 Unauthorized error will be returned.
Send a single message
Send a single message to one destination address.
Definition:
http://jasmin.thermolinks.com:8080/secure/sendExamples:
curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
"to": 19012233451,
"from": "Thermolinks",
"content": "Hello",
"dlr": "yes",
"dlr-url": "http://yoururl/dlr_receiver.php",
"dlr-level": 3
}' http://jasmin.thermolinks.com:8080/secure/sendNote
Do not include username and password in the parameters, they are already provided through the Authorization header.
Result Format:
{"data": "Success \"c723d42a-c3ee-452c-940b-3d8e8b944868"}If successful, response header HTTP status code will be 200 OK and the message will be sent, the message id will be returned in data.
Send multiple messages
Send multiple messages to one or more destination addresses.
Definition:
http://jasmin.thermolinks.com:8080/secure/sendbatchExample of sending same message to multiple destinations:
curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
"messages": [
{
"to": [
"33333331",
"33333332",
"33333333"
],
"content": "Same content goes to 3 numbers"
}
]
}' http://jasmin.thermolinks.com:8080/secure/sendbatchResult Format:
{"data": {"batchId": "af268b6b-1ace-4413-b9d2-529f4942fd9e", "messageCount": 3}}If successful, response header HTTP status code will be 200 OK and and the messages will be sent, the batch id and total message count will be returned in data.
messages
[{“to”: 1, “content”: “hi”}, {“to”: 2, “content”: “hello”}]
Mandatory
A Json list of messages, every message contains the /secure/send parameters
globals
{“from”: “Brand”}
Optional
May contain any global message parameter, c.f. examples
batch_config
{“callback_url”: “http://127.0.0.1:7877”, “schedule_at”: “2017-11-15 09:00:00”}
Optional
May contain the following parameters: callback_url or/and errback_url (used for batch tracking in real time c.f. examples), schedule_at (used for scheduling sendouts c.f. examples).
Note
The Rest API server has an advanced QoS control to throttle pushing messages back to Jasmin, you may fine-tune it through the http_throughput_per_worker and smart_qos parameters.
Send binary messages
Sending binary messages can be done using single or batch messaging APIs.
It’s made possible by replacing the content parameter by the hex_content, the latter shall contain your binary data hex value.
Example of sending a message with coding=8:
curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
"to": 19012233451,
"from": "Brand",
"coding": 8,
"hex_content": "0623063106460628"
}' http://jasmin.thermolinks.com:8080/secure/sendThe hex_content used in the above example is the UTF16BE encoding of arabic word “أرنب” (‘x06x23x06x31x06x46x06x28’).
Same goes for sending batches with binary data:
curl -X POST -H 'Authorization: Basic Zm9vOmJhcg==' -d '{
"messages": [
{
"to": [
"33333331",
"33333332",
"33333333"
],
"hex_content": "0623063106460628"
}
]
}' http://jasmin.thermolinks.com:8080/secure/sendbatchUsage examples:
The ref:parameter <restapi-POST_sendbatch_params> listed above can be used in many ways to setup a sendout batch, we’re going to list some use cases to show the flexibility of these parameters:
Example 1, send different messages to different numbers::
{
"messages": [
{
"from": "Brand1",
"to": [
"55555551",
"55555552",
"55555553"
],
"content": "Message 1 goes to 3 numbers"
},
{
"from": "Brand2",
"to": [
"33333331",
"33333332",
"33333333"
],
"content": "Message 2 goes to 3 numbers"
},
{
"from": "Brand2",
"to": "7777771",
"content": "Message 3 goes to 1 number"
}
]
}Example 2, using global vars:
From the previous Example (#1) we used the same “from” address for two different messages (“from”: “Brand2”), in the below example we’re going to make the “from” a global variable, and we are asking for level3 dlr for all sendouts:
{
"globals" : {
"from": "Brand2",
"dlr-level": 3,
"dlr": "yes",
"dlr-url": "http://some.fancy/url"
}
"messages": [
{
"from": "Brand1",
"to": [
"55555551",
"55555552",
"55555553"
],
"content": "Message 1 goes to 3 numbers"
},
{
"to": [
"33333331",
"33333332",
"33333333"
],
"content": "Message 2 goes to 3 numbers"
},
{
"to": "7777771",
"content": "Message 3 goes to 1 number"
}
]
}So, globals are vars to be inherited in messages, we still can force a local value in some messages like the “from”: “Brand1” in the above example.
Example 3, using callbacks:
As explained, Jasmin is enqueuing a sendout batch everytime you call /secure/sendbatch, the batch job will run and call Jasmin’s http api to deliver the messages, since this is running in background you can ask for success or/and error callbacks to follow the batch progress.
{
"batch_config": {
"callback_url": "http://127.0.0.1:9090/successful_batch",
"errback_url": "http://127.0.0.1:9090/errored_batch"
},
"messages": [
{
"to": [
"55555551",
"55555552",
"55555553"
],
"content": "Hello world !"
},
{
"to": "7777771",
"content": "Holà !"
}
]
}About callbacks:
The RESTful api is a wrapper around Jasmin’s http api, it relies on Celery task queue to process long running batches.
When you launch a batch, the api will enqueue the sendouts through Celery and return a batchId, that’s the Celery task id.
Since the batch will be executed in background, the API provides a convenient way to follow its progression through two different callbacks passed inside the batch parameters:
{
"batch_config": {
"callback_url": "http://127.0.0.1:9090/successful_batch",
"errback_url": "http://127.0.0.1:9090/errored_batch"
},
"messages": [
{
"to": "7777771",
"content": "Holà !"
}
]
}The callback_url will be called (GET) everytime a message is successfuly sent, otherwise the errback_url is called.
In both callbacks the following parameters are passed:
batchId
50a4581a-6e46-48a4-b617-bbefe7faa3dc
The batch id
to
1234567890
The to parameter identifying the destination number
status
1
1 or 0, indicates the status of a message sendout
statusText
Success “07033084-5cfd-4812-90a4-e4d24ffb6e3d”
Extra text for the status
About batch scheduling:
It is possible to schedule the launch of a batch, the api will enqueue the sendouts through Celery and return a batchId while deferring message deliveries to the scheduled date & time.
{
"batch_config": {
"schedule_at": "2017-11-15 09:00:00"
},
"messages": [
{
"to": "7777771",
"content": "Good morning !"
}
]
}The above batch will be scheduled for the 15th of November 2017 at 9am, the Rest API will consider it’s local server time to make the delivery, so please make sure it’s accurate to whatever timezone you’re in.
It’s possible to use another schedule_at format:
{
"batch_config": {
"schedule_at": "86400s"
},
"messages": [
{
"to": "7777771",
"content": "Good morning !"
}
]
}The above batch will be scheduled for delivery in 1 day from now (86400 seconds = 1 day).
Balance check
Get user account’s balance and quota.
Definition:
http://jasmin.thermolinks.com:8080/secure/balanceExamples:
curl -X GET -H 'Authorization: Basic Zm9vOmJhcg==' http://jasmin.thermolinks.com:8080/secure/balanceNote
Do not include username and password in the parameters, they are already provided through the Authorization header.
Result Format:
{"data": {"balance": "10000.20", "sms_count": "ND"}}If successful, response header HTTP status code will be 200 OK, the balance and the sms count will be returned in data.
Route check
Check a route and it’s rate.
Definition:
http://jasmin.thermolinks.com:8080/secure/rateExamples:
curl -X GET -H 'Authorization: Basic Zm9vOmJhcg==' http://jasmin.thermolinks.com:8080/secure/rate?to=19012233451Note
Do not include username and password in the parameters, they are already provided through the Authorization header.
Result Format:
{"data": {"submit_sm_count": 1, "unit_rate": 2.50}}If successful, response header HTTP status code will be 200 OK, the message rate and “pdu count” will be returned in data.
Ping
A simple check to ensure this is a responsive Jasmin API, it is used by third-party apps like Web campaigners, cluster service checks, etc.
Definition:
http://jasmin.thermolinks.com:8080/pingExamples:
curl -X GET http://jasmin.thermolinks.com:8080/pingResult Format:
If successful, response header HTTP status code will be 200 OK and a static “Jasmin/PONG” value in data.