HTTP API

This document is targeted at software designers/programmers wishing to integrate SMS messaging as a function into their applications using HTTP protocol, e.g. in connection with WEB-server, unified messaging, information services etc..

If you need to use a stateful tcp protocol (SMPP v3.4), please refer to SMPP Server API.

SMS Messages can be transmitted using HTTP protocol, the following requirements must be met to enable the service:

  • You need a Jasmin user account
  • You need sufficient credit on your Jasmin user account [1]

Note

The ABCs:

  • MT is referred to Mobile Terminated, a SMS-MT is an SMS sent to mobile
  • MO is referred to Mobile Originated, a SMS-MO is an SMS sent from mobile

Features

The ja-http API allows you to:

  • Send and receive SMS through Jasmin’s connectors,
  • Receive http callbacks for delivery notification (receipts) when SMS-MT is received (or not) on mobile station,
  • Send and receive long (more than 160 characters) SMS, unicode/binary content and receive http callbacks when a mobile station send you a SMS-MO.
  • Check your balance status,
  • Check a message rate price before sending it.

Sending SMS-MT

In order to deliver SMS-MT messages, Data is transferred using HTTP GET/POST requests. The Jasmin gateway accepts requests at the following URL:

http://127.0.0.1:1401/send

Note

Host 127.0.0.1 and port 1401 are default values and configurable in /etc/jasmin/jasmin.cfg, see jasmin.cfg / http-api.

This guide will help understand how the API works and provide Examples for sending SMS-MT.

HTTP request parameters

When calling Jasmin’s URL from an application, the below parameters must be passed (at least mandatory ones), the api will return a message id on success, see HTTP response.

ja-http sending SMS parameters
Parameter Value / Pattern Example(s) Presence Description / Notes
to Destination address 20203050 Mandatory Destination address, only one address is supported per request
from Originating address 20203050, Jasmin Optional Originating address, In case rewriting of the sender’s address is supported or permitted by the SMS-C used to transmit the message, this number is transmitted as the originating address
coding 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13 or 14 1 Optional Sets the Data Coding Scheme bits, default is 0, accepts values all allowed values in SMPP protocol [1]
username Text (30 char. max) jasmin_user Mandatory Username for Jasmin user account.
password Text (30 char. max) jasmin_pass Mandatory Password for Jasmin user account.
priority 0, 1, 2 or 3 2 Optional Default is 0 (lowest priority)
validity-period Integer 1440 Optional Message validity (minutes) to be passed to SMSC, default is value is None (message will take SMSC’s default)
dlr yes or no yes Optional Default is no (no DLR will be tracked)
dlr-url HTTP(s) URL http://host/dlr.php Mandatory if dlr If a DLR is requested (dlr = ‘yes’), dlr-url MUST be set, if not, dlr value is reconsidered as ‘no’
dlr-level 1, 2 or 3 2 Mandatory if dlr 1: SMS-C level, 2: Terminal level, 3: Both
dlr-method GET or POST GET Mandatory if dlr DLR is transmitted through http to a third party application using GET or POST method.
tags Text 1,702,9901 Optional Will tag the routable to help interceptor or router enable specific business logics.
content Text Hello world ! Mandatory if hex-content not defined Content to be sent
hex-content Binary hex value 0623063106460628 Mandatory if content not defined Binary to be sent

HTTP response

When the request is validated, a SubmitSM PDU is set up with the provided request parameters and sent to the routed connector through a AMQP queue, a queued message-id is returned:

Success "07033084-5cfd-4812-90a4-e4d24ffb6e3d"

Otherwise, an error is returned:

Error "No route found"
HTTP response code details
HTTP Code HTTP Body Meaning
200 Success “07033084-5cfd-4812-90a4-e4d24ffb6e3d” Message is successfully queued, messaged-id is returned
400 Error “Mandatory arguments not found, please refer to the HTTPAPI specifications.” Request parameters validation error
400 Error “Argument _ is unknown.” Request parameters validation error
400 Error “Argument _ has an invalid value: _.” Request parameters validation error
400 Error “Mandatory argument _ is not found.” Request parameters validation error
400 dynamic messages Credentials validation error, c.f. User credentials
403 Error “Authentication failure for username:_” Authentication error
403 Error “Authorization failed for username:_” Credentials validation error, c.f. User credentials
403 Error “Cannot charge submit_sm, check RouterPB log file for details” User charging error
412 Error “No route found” Message routing error
500 Error “Cannot send submit_sm, check SMPPClientManagerPB log file for details” Fallback error, checking log file will provide better details

Examples

Here is an example of how to send simple GSM 03.38 messages:

# Python example
# http://jasminsms.com
import urllib2
import urllib

baseParams = {'username':'foo', 'password':'bar', 'to':'+336222172', 'content':'Hello'}

# Send an SMS-MT with minimal parameters
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(baseParams)).read()

# Send an SMS-MT with defined originating address
baseParams['from'] = 'Jasmin GW'
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(baseParams)).read()

Here is an example of how to request acknowledgement when sending a SMS:

# Python example
# http://jasminsms.com
import urllib2
import urllib

# Send an SMS-MT and request terminal level acknowledgement callback to http://myserver/acknowledgement
params = {'username':'foo', 'password':'bar', 'to':'+336222172', 'content':'Hello',
          'dlr-url':'http://myserver/acknowledgement', 'dlr-level':2}
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(params)).read()

And more use cases for sending long, UCS2 (UTF16) and binary messages:

# Python example
# http://jasminsms.com
import urllib2
import urllib

baseParams = {'username':'foo', 'password':'bar', 'to':'+336222172', 'content':'Hello'}

# Sending long content (more than 160 chars):
baseParams['content'] = 'Very long message ....................................................................................................................................................................................'
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(baseParams)).read()

# Sending UCS2 (UTF-16) arabic content
baseParams['content'] = '\x06\x23\x06\x31\x06\x46\x06\x28'
baseParams['coding'] = 8
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(baseParams)).read()

# Sending UCS2 (UTF-16) arabic binary content
baseParams['hex-content'] = '0623063106460628'
baseParams['coding'] = 8
urllib2.urlopen("http://127.0.0.1:1401/send?%s" % urllib.urlencode(baseParams)).read()

In PHP:

<?php
// Sending simple message using PHP
// http://jasminsms.com

$baseurl = 'http://127.0.0.1:1401/send'

$params = '?username=foo'
$params.= '&password=bar'
$params.= '&to='.urlencode('+336222172')
$params.= '&content='.urlencode('Hello world !')

$response = file_get_contents($baseurl.$params);
?>

In Ruby:

# Sending simple message using Ruby
# http://jasminsms.com

require 'net/http'

uri = URI('http://127.0.0.1:1401/send')
params = { :username => 'foo', :password => 'bar',
           :to => '+336222172', :content => 'Hello world' }
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)

jasmin.cfg / http-api

The jasmin.cfg file (INI format, located in /etc/jasmin) contain a section called http-api where all ja-http API related config elements are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[http-api]
bind          = 0.0.0.0
port          = 1401

long_content_max_parts = 5
# Splitting long content can be made through SAR options or UDH
# Possible values are: sar and udh
long_content_split = udh

access_log         = /var/log/jasmin/http-access.log
log_level          = INFO
log_file           = /var/log/jasmin/http-api.log
log_format         = %(asctime)s %(levelname)-8s %(process)d %(message)s
log_date_format    = %Y-%m-%d %H:%M:%S
[http-api] configuration section
Element Default Description
bind 0.0.0.0 The HTTP API listener will only bind to this specified address, given 0.0.0.0 the listener will bind on all interfaces.
port 1401 The binding TCP port.
long_content_max_parts 5 If the message to be sent is to be split into several parts. This is the maximum number of individual SMS-MT messages that can be used.
long_content_split udh Splitting method: ‘udh’: Will split using 6-byte long User Data Header, ‘sar’: Will split using sar_total_segments, sar_segment_seqnum, and sar_msg_ref_num options.
access_log /var/log/jasmin/http-access.log Where to log all http requests (and errors).
log_*   Python’s logging module configuration.

Receiving DLR

When requested through dlr-* fields when Sending SMS-MT, a delivery receipt (DLR) will be sent back to the application url (set in dlr-url) through HTTP GET/POST depending on dlr-method.

The receiving end point must reply back using a “200 OK” status header and a body containing an acknowledgement of receiving the DLR, if one or both of these conditions are not met, the DLRThrower service will consider reshipment of the same message if config/dlr-thrower/max_retries is not reached (see jasmin.cfg / dlr-thrower).

In order to acknowledge DLR receipt, the receiving end point must reply back with exactly the following html body content:

ACK/Jasmin

Note

It is very important to acknowledge back each received DLR, this will prevent to receive the same message many times, c.f. Processing for details

Note

Reshipment of a message will be delayed for config/dlr-thrower/retry_delay seconds (see jasmin.cfg / dlr-thrower).

HTTP Parameters for a level 1 DLR

The following parameters are sent to the receiving end point (at dlr-url) when the DLR’s dlr-level is set to 1 (SMS-C level only)

ja-http parameters for a level 1 DLR
Parameter Value / Pattern Example(s) Presence Description / Notes
id Universally Unique IDentifier (UUID) 16fd2706-8baf-433b-82eb-8c7fada847da Always Internal Jasmin’s gateway message id used for tracking messages
message_status ESME_* SMPP Command status ESME_ROK, ESME_RINVNUMDESTS Always The delivery status
level 1 1 Always This is a static value indicating the dlr-level originally requested

HTTP Parameters for a level 2 or 3 DLR

The following parameters are sent to the receiving end point (at dlr-url) when DLR’s dlr-level is set to 2 or 3 (Terminal level or all levels)

ja-http parameters for a level 2 or 3 DLR
Parameter Value / Pattern Example(s) Presence Description / Notes
id Universally Unique IDentifier (UUID) 16fd2706-8baf-433b-82eb-8c7fada847da Always Internal Jasmin’s gateway message id used for tracking messages
id_smsc Integer 2567 Always Message id returned from the SMS-C
message_status ESME_* SMPP Command status ESME_ROK, ESME_RINVNUMDESTS Always The delivery status
level 1 1 Always This is a static value indicating the dlr-level originally requested
subdate Date & time format: YYMMDDhhmm 1311022338 Optional The time and date at which the short message was submitted
donedate Date & time format: YYMMDDhhmm 1311022338 Optional The time and date at which the short message reached it’s final state
sub Integer 1 Optional Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list.The value is padded with leading zeros if necessary
dlvrd Integer 1 Optional Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list.The value is padded with leading zeros if necessary
err Integer 0 Optional Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message
text Text (20 char. max) Hello foo bar Optional The first 20 characters of the short message

Processing

The flowchart below describes how dlr delivery and retrying policy is done inside DLRThrower service:

DLR delivery flowchart as processed by DLRThrower service

jasmin.cfg / dlr-thrower

The jasmin.cfg file (INI format, located in /etc/jasmin) contain a section called deliversm-thrower where all DLRThrower service related config elements are:

1
2
3
4
5
6
7
8
[dlr-thrower]
http_timeout       = 30
retry_delay        = 30
max_retries        = 3
log_level          = INFO
log_file           = /var/log/jasmin/dlr-thrower.log
log_format         = %(asctime)s %(levelname)-8s %(process)d %(message)s
log_date_format    = %Y-%m-%d %H:%M:%S
[http-api] configuration section
Element Default Description
http_timeout 30 Sets socket timeout in seconds for outgoing client http connections.
retry_delay 30 Define how many seconds should pass within the queuing system for retrying a failed throw.
max_retries 3 Define how many retries should be performed for failing throws of DLR.
log_*   Python’s logging module configuration.

Receiving SMS-MO

SMS-MO incoming messages (Mobile Originated) are forwarded by Jasmin to defined URLs using simple HTTP GET/POST, the forwarding is made by deliverSmHttpThrower service, and the URL of the receiving endpoint is selected through a route checking process (c.f. The message router).

Receiving endpoint is a third party application which acts on the messages received and potentially generates replies, (HTTP Client connector manager for more details about HTTP Client connector management).

The parameters below are transmitted for each SMS-MO, the receiving end point must provide an url (set in jasminApi.HttpConnector.baseurl) and parse the below parameters using GET or POST method (depends on jasminApi.HttpConnector.method).

The receiving end point must reply back using a “200 OK” status header and a body containing an acknowledgement of receiving the SMS-MO, if one or both of these conditions are not met, the deliverSmHttpThrower service will consider reshipment of the same message if config/deliversm-thrower/max_retries is not reached, (see jasmin.cfg / deliversm-thrower).

In order to acknowledge SMS-MO receipt, the receiving end point must reply back with exactly the following html body content:

ACK/Jasmin

Note

It is very important to acknowledge back each received SMS-MO, this will prevent to receive the same message many times, c.f. Processing for details

Note

Reshipment of a message will be delayed for config/deliversm-thrower/retry_delay seconds (see jasmin.cfg / deliversm-thrower).

HTTP Parameters

When receiving an URL call from Jasmin’s deliverSmHttpThrower service, the below parameters are delivered (at least Always present ones).

ja-http receiving SMS parameters
Parameter Value / Pattern Example(s) Presence Description / Notes
id Universally Unique IDentifier (UUID) 16fd2706-8baf-433b-82eb-8c7fada847da Always Internal Jasmin’s gateway message id
from Originating address +21620203060, 20203060, Jasmin Always Originating address
to Destination address +21620203060, 20203060, Jasmin Always Destination address, only one address is supported per request
origin-connector Alphanumeric id 23, bcd, MTN, clickatell, beepsend Always Jasmin http connector id
priority 1, 2 or 3 2 Optional Default is 1 (lowest priority)
coding Numeric 8 Optional Default is 0, accepts values all allowed values in SMPP protocol [2]
validity YYYY-MM-DD hh:mm:ss 2013-07-16 00-46:54 Optional The validity period parameter indicates the Jasmin GW expiration time, after which the message should be discarded if not delivered to the destination
content Text Hello world ! Always Content of the message
binary Hexlified binary content 062A063062A Always Content of the message in binary hexlified form

Note

When receiving multiple parts of a long SMS-MO, deliverSmHttpThrower service will concatenate the content of all the parts and then throw one http call with concatenated content.

Processing

The flowchart below describes how message delivery and retrying policy are done inside deliverSmHttpThrower service:

MO delivery flowchart as processed by deliverSmHttpThrower service

jasmin.cfg / deliversm-thrower

The jasmin.cfg file (INI format, located in /etc/jasmin) contain a section called deliversm-thrower where all deliverSmHttpThrower service related config elements are:

1
2
3
4
5
6
7
8
[deliversm-thrower]
http_timeout       = 30
retry_delay        = 30
max_retries        = 3
log_level          = INFO
log_file           = /var/log/jasmin/deliversm-thrower.log
log_format         = %(asctime)s %(levelname)-8s %(process)d %(message)s
log_date_format    = %Y-%m-%d %H:%M:%S
[http-api] configuration section
Element Default Description
http_timeout 30 Sets socket timeout in seconds for outgoing client http connections.
retry_delay 30 Define how many seconds should pass within the queuing system for retrying a failed throw.
max_retries 3 Define how many retries should be performed for failing throws of SMS-MO.
log_*   Python’s logging module configuration.

Checking account balance

In order to check user account balance and quotas, user may request a HTTP GET/POST from the following URL:

http://127.0.0.1:1401/balance

Note

Host 127.0.0.1 and port 1401 are default values and configurable in /etc/jasmin/jasmin.cfg, see jasmin.cfg / http-api.

HTTP request parameters

ja-http balance request parameters
Parameter Value / Pattern Example(s) Presence Description / Notes
username Text (30 char. max) jasmin_user Mandatory Username for Jasmin user account.
password Text (30 char. max) jasmin_pass Mandatory Password for Jasmin user account.

HTTP response

Successful response:

{"balance": 100.0, "sms_count": "ND"}

Otherwise, an error is returned.

Examples

Here is an example of how to check balance:

# Python example
# http://jasminsms.com
import urllib2
import urllib
import json

# Check user balance
params = {'username':'foo', 'password':'bar'}
response = urllib2.urlopen("http://127.0.0.1:1401/balance?%s" % urllib.urlencode(params)).read()
response = json.loads(response)

print 'Balance:', response['balance']
print 'SMS Count:', response['sms_count']

#Balance: 100.0
#SMS Count: ND

Checking rate price

It is possible to ask Jasmin’s HTTPAPI for a message rate price before sending it, the request will lookup the route to be considered for the message and will provide the rate price if defined.

Request is done through HTTP GET/POST to the following URL:

http://127.0.0.1:1401/rate

Note

Host 127.0.0.1 and port 1401 are default values and configurable in /etc/jasmin/jasmin.cfg, see jasmin.cfg / http-api.

HTTP request parameters

ja-http rate request parameters
Parameter Value / Pattern Example(s) Presence Description / Notes
to Destination address 20203050 Mandatory Destination address, only one address is supported per request
from Originating address 20203050, Jasmin Optional Originating address, In case rewriting of the sender’s address is supported or permitted by the SMS-C used to transmit the message, this number is transmitted as the originating address
coding 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 13 or 14 1 Optional Sets the Data Coding Scheme bits, default is 0, accepts values all allowed values in SMPP protocol [1]
username Text (30 char. max) jasmin_user Mandatory Username for Jasmin user account.
password Text (30 char. max) jasmin_pass Mandatory Password for Jasmin user account.
content Text Hello world ! Optional Content to be sent

HTTP response

Successful response:

{"submit_sm_count": 2, "unit_rate": 2.8}

Where submit_sm_count is the number of message units if the content is longer than 160 characters, content parameter is optional for requesting rate price.

Otherwise, an error is returned.

Otherwise, an error is returned:

Error "No route found"

Examples

Here is an example of how to check rate price:

# Python example
# http://jasminsms.com
import urllib2
import urllib
import json

# Check message rate price
params = {'username':'foo', 'password':'bar', 'to': '06222172'}
response = urllib2.urlopen("http://127.0.0.1:1401/rate?%s" % urllib.urlencode(params)).read()
response = json.loads(response)

print 'Unit rate price:', response['unit_rate']
print 'Units:', response['submit_sm_count']

#Unit rate price: 2.8
#Units: 1

Footnotes

[1](1, 2, 3) Billing
[2]
Data coding schemes
Bitmask Value Meaning
0 0 0 0 0 0 0 0 0 SMSC Default Alphabet
0 0 0 0 0 0 0 1 1 IA5 (CCITT T.50)/ASCII (ANSI X3.4)
0 0 0 0 0 0 1 0 2 Octet unspecified (8-bit binary)
0 0 0 0 0 0 1 1 3 Latin 1 (ISO-8859-1)
0 0 0 0 0 1 0 0 4 Octet unspecified (8-bit binary)
0 0 0 0 0 1 0 1 5 JIS (X 0208-1990)
0 0 0 0 0 1 1 0 6 Cyrllic (ISO-8859-5)
0 0 0 0 0 1 1 1 7 Latin/Hebrew (ISO-8859-8)
0 0 0 0 1 0 0 0 8 UCS2 (ISO/IEC-10646)
0 0 0 0 1 0 0 1 9 Pictogram Encoding
0 0 0 0 1 0 1 0 10 ISO-2022-JP (Music Codes)
0 0 0 0 1 1 0 1 13 Extended Kanji JIS(X 0212-1990)
0 0 0 0 1 1 1 0 14 KS C 5601