Documentation


Sending

This guide explains how to send plain text MT SMS through “Engage” and how to receive and interpret the corresponding delivery reports.

Integration

MT SMS should be submitted using HTTP POST to

http://sms.digifi.it/v1/send


Content-Type / Character Encoding

The sms should be submitted using a HTTP POST request with content-type of application/x-www-form-urlencoded. If a charset is included in the content- type e.g. “content-type: application/x-www-form-urlencoded; charset=utf-8″ then the content will be decoded with respect to that, otherwise UTF-8 is assumed by default.

In practice the characters available for use within SMS are limited to those defined in the GSM 03.38 character set. Please see Network Codes for a full description of the GSM 03.38 character set. Best efforts will be made to map characters not in GSM 03.38 to their closest equivalent. e.g. ï into i. Any characters which cannot be mapped will simply be dropped from the SMS.

Parameters

[table id=1 /]

client_id

You will have been provided with a unique client_id. This is to identify yourself across all “Engage” api calls. This takes the form of a 36 character UUID.

submission_id

Please generate a unique id for each MT SMS that you submit. This helps suppress any duplicate SMS that might be submitted when a problem occurs. The submission_id is tracked against any submission you have made with the same client_id over the last 168 hours (7 days) and a duplicate submission_id over this period will be rejected. The recommend form of this ID is as a UUID but we will accept any alphanumeric string that is unique.

submission_datetime

This should be the date and time at which submission to Engage was first attempted and should not be updated if submission fails or has to be retried for some reason unless the submission_id is also being changed at the same time.
Any MT SMS submission attempts more than 168 hours (7 days) after the submission_datetime will be rejected. The format of this parameter is yyyy-MM-dd HH:mm:ss and should be adjusted into the UTC time zone.

submission_signature

This serves to authenticate the request as coming from the correct client. Along with your client_id you will be supplied with a 40 character hexadecimal secret_key. The submission_signature is then defined as the SHA-1 Hash of a number of parameters concatenated together as follows.

submission_signature = SHA-1 Hash ( secret_key’+’client_id’+’submission_id’+’submission_datetime’+’secret_key
)

Note the input string being hashed should include the + delimiters. For example, taking the following values

client_id = c2037d7b-7c50-44f8-a338-742b2a564db3 submission_id = f9448a70-b890-4c72-8359-409e677de9b1 submission_datetime = 2010-02-13 12:15:03
secret_key = e15e3d0d3c9566cc7246228f652873525b068657

Then compute the SHA-1 hash of the string

e15e3d0d3c9566cc7246228f652873525b068657+c2037d7b-7c50-44f8-a338- 742b2a564db3+f9448a70-b890-4c72-8359-409e677de9b1+2010-02-13 12:15:03+e15e3d0d3c9566cc7246228f652873525b068657

This results in 4b470a238f9f318ae2b62748c6455954fe0012d2 when formatted as 40 character hexadecimal string.

SHA-1 hashing implementations are widely available for all major programming languages.

msg

The payload of the MT SMS to be sent.

network

A valid Engage network keyword. See Network Codes. The correct network is required to send premium SMS. To send to users using Virtual Mobile Operators you need to use the network keyword for the mobile operator providing airtime connectivity. e.g. Virgin -> TMOBILE_UK, Tesco Mobile -> O2_UK. When broadcasting to a number of destinations you should either include 1 network value for the whole broadcast or supply a comma- separated list of networks to match the count in the msisdn parameter.

msisdn

The destination phone number formatted in international format. eg. 447700900049.

from

For premium billed SMS this must be a valid shortcode. For bulk SMS either a phone number (up to 16 digits) or an alphanumeric string (up to 11 characters).

tariff

Bulk Free to end user SMS (DEFAULT)
Billed Premium billed SMS (requires a valid shortcode is used for from parameter)

split

Selects the strategy for dealing with SMS exceeding 160 GSM 03.38 characters.

0 – MT SMS above 160 characters will be rejected
1 – MT SMS will be split approximately at 160 character boundary and sent to the end user phone as separate SMS. (Not supported in broadcast mode)
2 – MT SMS will be split using SMS concatenation and sent to the phone with a UDH header such that the phone can recombine them as a single SMS.

tag

Used to split up SMS statistics from within our reporting tool. For example you may wish to group SMS by campaign or conversion route.

note

A further opportunity to record context about why and how this SMS was sent.

report

Determines if delivery reports are returned, parameter is optional defaulting to true.

Response

The response is split into the HTTP status code and response body.
HTTP Status Code

[table id=7 /]

HTTP Body
Responses that have a status of 200, 400 or 403 will also be accompanied with a body containing the outcome of the submission. This is encoded within a JSON data structure. This may have additional values added to it in the future so please decode the response using a JSON library.

200:

{“client_id”:” c2037d7b-7c50-44f8-a338- 742b2a564db3″,”submission_id”:” f9448a70-b890-4c72-8359- 409e677de9b1″,”response”:[{“aptus_id”:”30bab603-496d-469c- 8b44-181d596c1ada”,”msisdn”:”447700900049″}]}
The response array will contain an object for each part of each msisdn the MT has been submitted too.
{“client_id”:” c2037d7b-7c50-44f8-a338-742b2a564db3″, “submission_id”:” f9448a70-b890-4c72-8359-409e677de9b1″,
“response”:[{“aptus_id”:”80cd54f9-5abd-4d21-9348-
01bdfcbd212a”, “msisdn”:”447700900049″,”part”:1,”parts”:2}, {“aptus_id”:”cc62fdf7-6eb0-4860-84ca-5500c3aa04dc”, “msisdn”:”447700900049″,”part”:2,”parts”:2}, {“msisdn”:”447700900050″,”,”error_code”:10405, “error_description”:” Daily send limit to this MSISDN exceeded “}]}

400/403:

{“client_id”:” c2037d7b-7c50-44f8-a338- 742b2a564db3″,”submission_id”:” f9448a70-b890-4c72-8359- 409e677de9b1″,”error_code”:10301,”error_description”:” submission_datetime is more than 168 hours ago “}

Error Codes

Edit
HTTP Status Code
Error Code
Error Description
400 10001 – 10013 Required parameter missing
400 10101 – 10113 Bad parameter
400 10201 Invalid msisdn
400 10202 SMS too long
400 10301 submission_datetime is more than 168 hours ago
400 10302 The submission_id has already been used
403 10303 submission_signature does not match
403 10401 Destination is blacklisted
403 10402 Destination is blocked
403 10403 Credit Limit Exceeded
403 10405 Daily send limit to this MSISDN exceeded
403 10406 Reverse billing forbidden



Delivery Reports

Delivery reports will be submitted via HTTP GET to your supplied URL e.g.

http://host.yourdomain.tld/sms/dr?client_id=c2037d7b-7c50-44f8- a338-742b2a564db3&submission_id=f9448a70-b890-4c72-8359- 409e677de9b1&aptus_id=0e28adbc-530b-4136-8c80- 0b182358f1a3&msisdn=447700900049&forward_time=2010-02- 13+12%3A18%3A04&delivery_time=2010-02- 13+12%3A18%3A06&status=0

Edit
Parameter
Type
Value
client_id alphanumeric The client_id used during submission
submission_id alphanumeric The submission_id used during
submission
aptus_id alphanumeric The aptus_id returned in response to
your submission
msisdn numeric The destination number used during
submission
forward_time alphanumeric (yyyy-MM-dd
HH:mm:ss)
The date and time that the SMS was
passed onto a mobile operator for
delivery
delivery_time alphanumeric (yyyy-MM-dd
HH:mm:ss)
The date and time reported that the SMS
was delivered to the handset.
status numeric 0 – Delivered, 1- Failed

Your platform should respond with an HTTP 200 response with a non-empty body. This response must be given in a timely manner (sub 10 seconds). Any other response will result in the delivery report being retried using a back off scheme over the next 48 hours.

Additional information is available on delivery reports, detailing the reason for a particular message succeeding or failing. Additional GET parameters will be added when reports are submitted to your report URL. Both a numeric and textual description are provided.

This is enabled on an account-by-account basis. Please contact us to activate this feature. e.g.

http://host.yourdomain.tld/sms/dr?client_id=c2037d7b-7c50-44f8- a338-742b2a564db3&submission_id=f9448a70-b890-4c72-8359- 409e677de9b1&aptus_id=0e28adbc-530b-4136-8c80- b182358f1a3&msisdn=447700900049&forward_time=2010- ‐02-‐ 13+12%3A18%3A04&delivery_time=2010-02- 13+12%3A18%3A06&status=0&reason=201&information=SUCCESS&pe rmanent=true

An indication of whether this reason represents a permanent or temporary failure condition is also supplied. A permanent
failure indicates further MTs of the same type should not be submitted to the particular MSISDN.


Extended delivery reports

[table id=6 /]