SMS API User Guide - Eseye.com

542kB Size 6 Downloads 56 Views

Oct 6, 2016 ... Sam Smith Inserted SMS MT parameter table .... Example using PHP . ..... of a basic SMS message send request using PHP POST method.
SMS API User Guide Document Reference: 8297 October 2016 Version: 6

Version Number 1

Date

Author

Apr 2015

2

Sep 2015

John Lindsay Sam Smith

3

May 2016

Sam Smith

4

Jul 2016

Sam Smith

5

Aug 2016

Sam Smith

6

Oct 2016

Sam Smith

Changes

Branding updated USSD section added Postman updated Branding updated Renamed USSD section removed Inserted SMS MT parameter table Moved delivery receipt into the table Updated MT Postman example Clarified text parameter 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

6

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

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

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 3

4 Non-alphabet ASCII characters Character

Description

Encode as

[Carriage Return] [Line feed] [Space] " # % & , . / ; : < = > ? ¡ £ ¤ ¥ § Ä Å à ä å Æ Ç É è é ì Ñ ñ ò ö Ø Ö Ü ù ü ß

carriage return line feed space quotation mark hash percent ampersand comma period forward slash semi-colon colon less than equal greater than question mark inverted exclamation mark pound currency sign yen paragraph sign capital A with diaeresis capital A with ring small a grave small a with diaeresis small a with ring capital diphthong AE capital C cedilla capital E acute small e grave small e acute small i grave capital N with tilde small n with tilde small o grave small o with diaeresis capital O with storke capital O with diaeresis capital U with diaeresis small u grave small u with diaeresis small s sharp

%0D %0A %20 %22 %23 %25 %26 %2C %2E %2F %3A %3B %3C %3D %3E %3F %A1 %A3 %A4 %A5 %A7 %C4 %C5 %E0 %E4 %E5 %C6 %C7 %C9 %E8 %E9 %EC %D1 %F1 %F2 %F6 %D8 %D6 %DC %F9 %FC %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) 2) 3) 4)

Check authenticated user has access rights send an SMS Check optional white list of source devices Check to see if all messages to this SIM should be routed to application API 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

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 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”

'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 5.8.1

Errors 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_7bit_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

Comments