SMS API User Guide

Document Reference: 8297

October 2016

Version: 6

Page 1

Version

Number

Date Author Changes

1 Apr 2015 John

Lindsay

2 Sep 2015 Sam Smith Branding updated

USSD section added

Postman updated

3 May 2016 Sam Smith Branding updated

Renamed

USSD section removed

4 Jul 2016 Sam Smith Inserted SMS MT parameter table

Moved delivery receipt into the table

5 Aug 2016 Sam Smith Updated MT Postman example

Clarified text parameter

6 Oct 2016 Sam Smith Added non-alphabet ASCII characters

Page 2

Contents

1 Introduction ......................................................................................................................................... 3

2 Preparation ......................................................................................................................................... 3

3 API location ......................................................................................................................................... 3

4 Non-alphabet ASCII characters ..................................................................................................... 4

5 Mobile Terminated SMS .................................................................................................................... 5

5.1 SMS pathways ............................................................................................................................ 5

5.2 Parameters .................................................................................................................................. 6

5.3 Example using CURL .................................................................................................................. 6

5.4 Example using Perl ..................................................................................................................... 7

5.5 Example using Postman app................................................................................................... 8

5.6 Example using PHP .................................................................................................................... 9

5.7 Example using a browser ......................................................................................................... 9

5.8 Errors ........................................................................................................................................... 10

5.8.1 ERROR 010: Invalid password supplied........................................................................ 10

5.8.2 ERROR 011: Invalid username supplied ....................................................................... 10

5.8.3 ERROR 510: API Requests from this IP Address (x.x.x.x) are not allowed ............... 10

5.8.4 ERROR 530: API Requests authentication failed! ....................................................... 10

5.8.5 ERROR 550: Invalid MSISDN (xxxxx) supplied .............................................................. 10

5.8.6 ERROR 550: Invalid Parameter text supplied .............................................................. 10

5.8.7 ERROR 550: Invalid text message the message is too long ..................................... 10

5.8.8 ERROR 550: The destination Parameter is missing ..................................................... 10

5.8.9 ERROR 570: Destination MSISDN (xxxxxxxxxx) has no credit. ................................... 10

5.8.10 ERROR 580: Please use only GSM 03.38 basic 7 bit characters .............................. 10

5.8.11 Invalid controller specified ............................................................................................ 10

5.8.12 Notice: Undefined property: stdClass::$text .............................................................. 10

5.8.13 ERROR 526: message_id must be supplied for delivery receipt ............................. 11

6 Mobile Originated SMS ................................................................................................................... 11

6.1 SMS pathways .......................................................................................................................... 11

6.2 Example MO SMS ..................................................................................................................... 12

Page 3

1 Introduction

This guide describes the functionality and use of the Eseye messaging API.

The Eseye messaging API can be used for delivery and receipt of SMS messages as well as a

number of more advanced features. This guide outlines how to interact with this API.

The process can be logically split into two sections; the SMS sending interface (Mobile

Terminated, to connected device/ AnyNet SIM card) and the receiving interface (Mobile

Originated, from connected device/ AnyNet SIM card).

2 Preparation

A user account is required for use of the API. The configuration of this user account allows a

number of parameters to be specified, customers are required to have provided the

following to Eseye:

Parameter Description

SMS whitelist The definition of a list of permissible

MSISDN’s* effective in both directions;

Mobile Originated (MO) and Mobile

Terminated (MT).

Server IP whitelist IP Address whitelist for incoming

requests

Mobile Originating (MO)

URL

URL to POST when a MO Message is

received

Eseye will provide the following information:

Parameter Description

Username API account username

Password API account password

API MSISDN Destination MSISDN routed to API

*MSISDN – The telephone number to the SIM card in a mobile/cellular phone

3 API location

The messaging API is formed of a POST interface over HTTPS.

The API is located at:

https://messaging.eseye.com/

Page 4

4 Non-alphabet ASCII characters

Character Description Encode as

[Carriage Return] carriage return %0D

[Line feed] line feed %0A

[Space] space %20

" quotation mark %22

# hash %23

% percent %25

& ampersand %26

, comma %2C

. period %2E

/ forward slash %2F

; semi-colon %3A

: colon %3B

< less than %3C

= equal %3D

> greater than %3E

? question mark %3F

¡ inverted exclamation mark %A1

£ pound %A3

¤ currency sign %A4

¥ yen %A5

§ paragraph sign %A7

Ä capital A with diaeresis %C4

Å capital A with ring %C5

à small a grave %E0

ä small a with diaeresis %E4

å small a with ring %E5

Æ capital diphthong AE %C6

Ç capital C cedilla %C7

É capital E acute %C9

è small e grave %E8

é small e acute %E9

ì small i grave %EC

Ñ capital N with tilde %D1

ñ small n with tilde %F1

ò small o grave %F2

ö small o with diaeresis %F6

Ø capital O with storke %D8

Ö capital O with diaeresis %D6

Ü capital U with diaeresis %DC

ù small u grave %F9

ü small u with diaeresis %FC

ß small s sharp %DF

Page 5

5 Mobile Terminated SMS

This section of the API allows delivery of an SMS message to an Eseye SIM card.

Eseye perform a number of checks on SMS messages to be terminated on an Eseye SIM card.

In addition to the checks described in the Security section the interface also ensures the

following checks pass.

1) Check authenticated user has access rights send an SMS

2) Check optional white list of source devices

3) Check to see if all messages to this SIM should be routed to application API

4) Check to see if this SIM is barred from receiving SMS*

*SMS barring is defined outside of the scope of this API, enabling or disabling of Mobile

Originated or Mobile Terminated Messages is linked to the SIM package.

5.1 SMS pathways

The following two diagrams display the main pathways used by a mobile terminated SMS,

with the codes for the pathway in square brackets.

Page 6

5.2 Parameters Parameter Description Optional/ Mandatory

username API account username Mandatory

password API account password Mandatory

destination Mobile number (MSISDN) of the recipient

device

Mandatory

text The SMS message contents Mandatory

message_id User generated unique message identifier Optional

receipt_url url to send the delivery receipt to Optional

source The source MSISDN, if left then it will be

sent from the API configuration

Optional

mode Leave blank for default = 7 bit

‘8’ for 8bit encoded

Optional

expiry The date-time for the message to expire if

not delivered

Optional

5.3 Example using CURL The following is an example of a basic SMS message send request using CURL with the

following parameters:

Username – “User”

Password – “Pass”

Destination – “447924939016”

Text (message content) - “Test”

curl -d "username=User&password=Pass&destination=447924939016&text=Test" https://messaging.eseye.com/

The return from this request is: "OK!"

Page 7

5.4 Example using Perl The following is an example of a basic SMS message send request using Perl with

LWP::UserAgent with the following parameters:

• Username – “User”

• Password – “Pass”

• Destination – “447924939016”

• Text (message content) - “Test”

use LWP::UserAgent; my $ua = LWP::UserAgent->new; $ua->agent('perlproc/1.0'); # Create a request my $req = HTTP::Request->new(POST => ' https://messaging.eseye.com/'); $req->content_type('application/x-www-form-urlencoded'); $req->content(' username=User&password=Pass&destination=447924939016&text=Test’); # Pass request to the user agent and get a response back my $response = $ua->request($req); if( $response->is_success ){ my $Message = $response->content; print "Return: $Message\n"; } else { print "Error " . $response->status_line . "\n"; }

The return from this request is: Return: "OK!"

Page 8

5.5 Example using Postman app For more information on this app, the Eseye Postman User Guide (url:

https://www.eseye.com/wp-content/uploads/8314-Postman-User-Guide.pdf).

The following is an example of a basic SMS message send request using Postman application

with the following parameters (use the Params button not Headers):

• Username – “User”

• Password – “Pass”

• Destination – “447924939016”

• Text (message content) - “Test”

The return from this request is “OK!”

Page 9

5.6 Example using PHP The following is an example of a basic SMS message send request using PHP POST method

with the following parameters:

• Username – “User”

• Password – “Pass”

• Destination – “447924939016”

• Text (message content) - “Test”

<?php $url = 'https://messaging.eseye.com/'; $params = array('username'=>'user', 'password'=>'pass', 'destination'=>'447924939016', 'text'=>'Test'); // use key 'http' even if you send the request to https://... $options = array( 'http' => array( 'header' => "Content-type: application/x-www-form-urlencoded\r\n", 'method' => 'POST', 'content' => http_build_query($params), ), ); $context = stream_context_create($options); $result = file_get_contents($url, false, $context); echo($result); ?>

The return from this request is:

Return: "OK!"

5.7 Example using a browser The following is an example of a basic SMS message send request using a web browser with

the following parameters:

• Username – “User”

• Password – “Pass”

• Destination – “447924939016”

• Text (message content) - “Test”

https://messaging.eseye.com/?username=User&password=Pass&destination=447924939016&text=Test

The return from this request is:

OK!

Page 10

5.8 Errors

5.8.1 ERROR 010: Invalid password supplied

This indicates that ‘password’ has been entered incorrectly.

5.8.2 ERROR 011: Invalid username supplied

This indicates that either ‘username’ has been entered incorrectly or that the account being

used does not have the privileges to use this service.

5.8.3 ERROR 510: API Requests from this IP Address (x.x.x.x) are not allowed

This indicates that the device being used is not authorised. When setting up your account

you will have agreed a Server IP whitelist, a list of IP addresses from which incoming requests

can be made, this IP address is not on the list.

5.8.4 ERROR 530: API Requests authentication failed!

This indicates that either your username or password have been entered incorrectly.

5.8.5 ERROR 550: Invalid MSISDN (xxxxx) supplied

This indicates that the MSISDN supplied is invalid. Ensure it has the appropriate country calling

code.

5.8.6 ERROR 550: Invalid Parameter text supplied

This indicates that ‘text’ has been entered incorrectly into the ‘URL Parameter Key’ box.

5.8.7 ERROR 550: Invalid text message the message is too long

This indicates that the message is too long. Messages are limited to 160 characters for

standard 7-bit delivery.

5.8.8 ERROR 550: The destination Parameter is missing

This indicates that ‘destination’ has been entered incorrectly into the ‘URL Parameter Key’

box.

5.8.9 ERROR 570: Destination MSISDN (xxxxxxxxxx) has no credit.

This indicates that there is no credit available for the destination MSISDN. This only applies

where the destination MSISDN account is charged. For instructions on adding credit to your

account, please visit Eseye's SIAM Portal, or contact Eseye for further guidance.

5.8.10 ERROR 580: Please use only GSM 03.38 basic 7 bit characters

or specify 8 bit mode

This indicates that a non-standard character is included in the message text. API SMS only

supports characters from the ETSI USSD default alphabet, as defined in GSM 03.38

(https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-

bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38).

5.8.11 Invalid controller specified

(username=ExampleUsername&password= ExamplePassoword&destination=441234336578)

This indicates that the ? from the https://messaging.eseye.com/? section of URL has been

entered incorrectly.

5.8.12 Notice: Undefined property: stdClass::$text

This indicates that an invalid parameter has been entered, this includes capitalisation of valid

parameters and additional parameters.

Page 11

5.8.13 ERROR 526: message_id must be supplied for delivery receipt

This indicates that the message_id has not been entered.

6 Mobile Originated SMS

SMS messages originating from an Eseye SIM card may be collected via this interface. By

default, messages will be delivered via this API when they are sent to the phone number

assigned to the account, but it is also possible to configure that all SMS messages from

specified Eseye SIM cards to be delivered to the API.

Eseye perform a number of checks on SMS messages from a SIM card (Mobile Originated), In

addition to checks described in the Security section the following checks are made:

1) Check to see if this SIM is barred from sending SMS*

2) Check to see if all messages from this SIM should be routed to application API

*SMS barring is defined outside of the scope of this API, enabling or disabling of Mobile

Originated or Mobile Terminated Messages is linked to the SIM package.

The HTTP POSTs will be delivered to the URL attached to your user account.

6.1 SMS pathways

The following diagram displays the main pathways used by a mobile originated SMS, with the

codes for the pathway in square brackets.

Page 12

6.2 Example MO SMS The following is an example of a basic SMS message send request using CURL with the

following parameters:

Device MSISDN – “44792498881474”

Destination – “447924864553”

Text (message content) - “Test”

Iteration 0 DateTime:2016-06-09 15:23:04 HTTP headers: Request Method:POST Request URI:/catchpost.php Server Protocol:HTTP/1.1 Host: messaging.redstation.eseye.com Accept: */* X-Forwarded-For: 81.94.198.92 Request body: array ( 'source' => '44792498881474', 'destination' => '447924864553', 'messageid' => '987650688', 'text' => ‘Test’, )