SMS API User Guide Document Reference: 8297 October 2016 Version: 6
Version Date Author Changes Number 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 1
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 2
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 Server IP whitelist Mobile Originating (MO) URL The definition of a list of permissible MSISDN s* effective in both directions; Mobile Originated (MO) and Mobile Terminated (MT). IP Address whitelist for incoming requests URL to POST when a MO Message is received Eseye will provide the following information: Parameter Description Username Password API MSISDN API account username API account password 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 3
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 4
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 5
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 mode expiry The source MSISDN, if left then it will be sent from the API configuration Leave blank for default = 7 bit 8 for 8bit encoded The date-time for the message to expire if not delivered Optional Optional 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 6
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 7
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 8
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-formurlencoded\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=4479 24939016&text=Test The return from this request is: OK! Page 9
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 10
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 11
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, Page 12