NetCom SMS Bedrift API Technical Documentation

Transcription

1 Version 1.2 December 2008

2 TABLE OF CONTENTS 1 INTRODUCTION SCOPE REVISION HISTORY SOLUTION OVERVIEW LIMITATIONS NUMBER OF RECIPIENTS ORIGINATING ADDRESS MAXIMUM MESSAGE LENGTH DESTINATIONS INTERFACE URL AUTHENTICATION REQUEST PARAMETERS RESPONSE USAGE EXAMPLES HTTP GET HTTP POST FAILURE SCENARIOS AUTHENTICATION FAILURE VALIDATION FAILURE SYSTEM FAILURE TROUBLESHOOTING SAMPLE JAVA CLIENT Page 2 of 13

3 1 Introduction 1.1 Scope This document describes the technical interface to the NetCom SMS Bedrift solution. A simple Java example is also included. 1.2 Revision history Date Revision Author Comments JSL Initial version SSC Added information about SSL TRU Corrected SMS destination information. International SMS is possible. Page 3 of 13

4 2 Solution overview Description: HTTP request Client application HTTP response 1. The client application issues an HTTP request (GET or POST) to a specified URL. 2. A load balancing switch distributes the requests across the web servers. Load balancing switch Web servers Message queue 3. The web server validates the request, performs any necessary character conversion and places the message in a message queue. The HTTP is generated and returned to the client. 4. At the other end of the queue, a consumer takes the message from the message queue and dispatches it to one of the SMSC s. The consumer will also create a log entry for settlement purposes. Consumer 5. The SMS message is delivered to the recipient. SMSC SMSC Page 4 of 13

5 3 Limitations 3.1 Number of recipients The current solution can only support a single recipient per message. 3.2 Originating address The SMS message can have the customer s company name as originator. This name can be a maximum of 11 characters long, and can only include small and capital letters excluded æ, ø and å, but space ( ) is allowed. The customer specifies the originator when filling out the order form. NetCom then sets the originator upon activation of the service for the customer. If no originating name is specified by the customer, 2032 is set as originator. 3.3 Maximum message length The maximum message length is 640 characters. Messages that are longer than 160 characters will be split into several parts. 3.4 Destinations The service allows sending to all GSM phones available through NetComs interconnections. Page 5 of 13

6 4 Interface 4.1 URL Protocol HTTP HTTPS URL Authentication Example: The SMS Bedrift solution relies on HTTP Basic authentication. The realm name is 'CP Authentication'. This requires that the incoming request contains the HTTP Authorization header. The authorization header is then generated by concatenating username and password and then applying base64 encoding. Authorization: Basic bmv0y69tom5ldknvbxi5eg== 4.3 Request parameters Name Description Mandatory message The message text. yes number truncate The message will be checked to ensure that all characters are supported by the SMS-C. Unsupported/illegal characters will be automatically converted to their supported counterparts. The recipient MSISDN including the international prefix. Do not include a leading +. Example: Optional parameter that can be used to truncate a message to 160 characters. truncate=1 truncate message truncate=0 no truncation Default is no truncation (0). yes no Page 6 of 13

7 4.4 Response The HTTP response is encoded as XML (content type text/xml). The basic structure of the response XML is shown below: <?xml version="1.0" encoding="iso "?> <result> <status/> <error/> </result> Status code values:- Status code Description 200 Success. The message has been accepted for delivery and will be forwarded to the recipient. 504 Validation error. The message has been rejected because of a validation error. An input parameter is either missing or incorrect. The error element will indicate which parameter is at fault. 512 System error. The message has been rejected because of a system failure. Page 7 of 13

8 5 Usage examples 5.1 HTTP GET Request GET /sms/send?number= &message=hei HTTP/1.1 Authorization: Basic bmv0y89tom3ldjnvbxh5eg== User-Agent: Java1.3.1_01 Host: localhost:8080 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Response Comments HTTP/ OK Content-Type: text/xml Date: Sat, 16 Mar :03:09 GMT Transfer-Encoding: chunked Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) <?xml version="1.0" encoding="iso "?> <result> <status>200</status> <error/> </result> The fully qualified URL is: e=hei Page 8 of 13

9 5.2 HTTP POST Request Response POST /sms/send HTTP/1.1 Authorization: Basic bmv0y89tom3ldjnvbxh5eg== content-type: application/x-www-form-urlencoded User-Agent: Java1.3.1_01 Host: localhost:8080 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-length: 36 number= &message=hei på deg HTTP/ OK Content-Type: text/xml Date: Sat, 16 Mar :03:09 GMT Transfer-Encoding: chunked Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) <?xml version="1.0" encoding="iso "?> <result> <status>200</status> <error/> </result> Page 9 of 13

10 6 Failure scenarios 6.1 Authentication failure Response The web server will return 401 Unauthorized if authentication fails. An example is show below: - HTTP/ Unauthorized Content-Type: text/html Date: Sat, 16 Mar :13:16 GMT Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) Connection: close WWW-Authenticate: Basic realm="login required" <html><head><title>...<u>this request requires HTTP authentication (Unauthorized).</u></p><HR size="1" noshade></body></html> 6.2 Validation failure Response The web server will return 200 OK when a validation error is encountered. The status element of the response XML will have the value 504 The error element of the response XML will indicate the parameter in error. An example is shown below:- HTTP/ OK Content-Type: text/xml Date: Sat, 16 Mar :19:15 GMT Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) Connection: close <?xml version="1.0" encoding="iso "?> <result> <status>504</status> <error>number</error></result> Page 10 of 13

11 6.3 System failure Response The web server will return 200 OK when a system failure is encountered. The status element of the response XML will have the value 512 The error element of the response XML will indicate the reason. An example is shown below:- HTTP/ OK Content-Type: text/xml Date: Sat, 16 Mar :19:15 GMT Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) Connection: close <?xml version="1.0" encoding="iso "?> <result> <status>512</status> <error>number</error></result> Page 11 of 13

12 7 Troubleshooting Test the service by accessing the URL from a web browser: For service without SSL certificate: For service with SSL certificate: Page 12 of 13

13 8. Sample Java client //****************************************************************************** //** //** Module name : SmsSendClient.java //** Author : NetCom //** Created : Mar 2002 //** Version : 1.0 //****************************************************************************** import java.net.*; import java.io.*; import org.w3c.tools.codec.base64encoder; //** //** Class : SmsSendClient //** Extends : None //** Implements : None //** Visibility : Public //** Description : A simple application demonstrating SMS send function //** public class SmsSendClient { //** //** Constants ** //** private static final String suser = "netcom"; private static final String spassword = "fgsds42k"; private static final String surl = " private static final String susage = "Usage: SmsSendClient <number> <message>"; //** //** main() //** //** Send SMS using HTTP GET request. //** public static void main(string sargs[]) { if (sargs.length!= 2) { System.out.println(sUsage); System.exit(0); } } try { // prepare request String snumber = sargs[0]; String smessage = sargs[1]; String srequest = surl + "?" + "number=" + snumber + "&" + "message=" + URLEncoder.encode(sMessage); URLConnection conn = new URL(sRequest).openConnection(); // set authorization header Base64Encoder enc = new Base64Encoder(sUser + ":" + spassword); String sauthheader = "Basic " + enc.processstring(); conn.setrequestproperty("authorization",sauthheader); // issue request BufferedReader reader = new BufferedReader( new InputStreamReader((InputStream)conn.getContent())); // read response String sline = null; while ((sline = reader.readline())!= null) System.out.println(sLine); } catch (Exception e) { e.printstacktrace(); } } // class SmsSendClient Page 13 of 13