Post on 23-Mar-2018
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’, )