Contact information Tel +46 8 504 55 000

Fax +46 8 5044 55 001 Stureplan 8, Stockholm Sweden SE-106 63 Stockholm Sweden

SMS Bedrift API Technical Documentation

Date Page 2011-12-02 2 (13)

Table of Content 1 Introduction ........................................................................................................................... 3

1.1 Scope ....................................................................................................................... 3

1.2 Revision history ......................................................................................................... 3

2 Solution overview .................................................................................................................. 4

3 Limitations ............................................................................................................................. 5

3.1 Number of recipients ................................................................................................. 5

3.2 Originating address ................................................................................................... 5

3.3 Maximum message length ........................................................................................ 5

3.4 Destinations .............................................................................................................. 5

4 Interface ................................................................................................................................ 6

4.1 URL .......................................................................................................................... 6

4.2 Authentication ........................................................................................................... 6

4.3 Request parameter ................................................................................................... 6

4.4 Response .................................................................................................................. 7

5 Usage examples ................................................................................................................... 8

5.1 HTTP GET ................................................................................................................ 8

5.2 HTTP POST .............................................................................................................. 9

6 Failure scenarios ................................................................................................................... 10

6.1 Authentication failure ................................................................................................ 10

6.2 Validation failure ....................................................................................................... 10

6.3 System failure ........................................................................................................... 11

7 Troubleshooting .................................................................................................................... 12

8 Sample Java client ................................................................................................................ 13

Date Page 2011-12-02 3 (13)

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

16.03.2002 1.0 JSL Initial version

15.05.2002 1.1 SSC Added information about SSL

18.12.2008 1.2 TRU Corrected SMS destination information. International SMS is possible

Date Page 2011-12-02 4 (13)

2 Solution overview Description: 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. 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. 5. The SMS message is delivered to the recipient.

Date Page 2011-12-02 5 (13)

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.

Date Page 2011-12-02 6 (13)

4 Interface

4.1 URL

Protocol URL

HTTP http://firebolt.netcom.no:8080/sms/send

HTTPS https://firebolt.netcom.no/sms/send

4.2 Authentication 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. Example: Authorization: Basic bmV0Y69tOm5ldKNvbXi5eg== 4.3 Request parameter

Name Description Mandatory

message The message text. 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.

yes

number The recipient MSISDN including the international prefix. Do not include a leading ‘+’. Example: ‘4793224070’

yes

truncate 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).

no

Date Page 2011-12-02 7 (13)

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-8859-1" ?> <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.

Date Page 2011-12-02 8 (13)

5 Usage examples 5.1 HTTP GET Request GET /sms/send?number=4793224070&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 HTTP/1.1 200 OK Content-Type: text/xml Date: Sat, 16 Mar 2002 14:03:09 GMT Transfer-Encoding: chunked Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) <?xml version="1.0" encoding="ISO-8859-1" ?> <result> <status>200</status> <error/> </result> Comments The fully qualified URL is: http://firebolt.netcom.no:8080/sms/send?number=4793224070&messag e=hei

Date Page 2011-12-02 9 (13)

5.2 HTTP POST Request 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=4793224070&message=hei på deg Response HTTP/1.1 200 OK Content-Type: text/xml Date: Sat, 16 Mar 2002 14:03:09 GMT Transfer-Encoding: chunked Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) <?xml version="1.0" encoding="ISO-8859-1" ?> <result> <status>200</status> <error>

Date Page 2011-12-02 10 (13)

6 Failure scenarios 6.1 Authentication failure The web server will return ‘401 Unauthorized’ if authentication fails. An example is show below: Response HTTP/1.1 401 Unauthorized Content-Type: text/html Date: Sat, 16 Mar 2002 14: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 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: Response HTTP/1.1 200 OK Content-Type: text/xml Date: Sat, 16 Mar 2002 14:19:15 GMT Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) Connection: close <?xml version="1.0" encoding="ISO-8859-1"?> <result> <status>504</status> <error>number</error></result>

Date Page 2011-12-02 11 (13)

6.3 System failure 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: Response HTTP/1.1 200 OK Content-Type: text/xml Date: Sat, 16 Mar 2002 14:19:15 GMT Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector) Connection: close <?xml version="1.0" encoding="ISO-8859-1"?> <result> <status>512</status> <error>number</error></result>

Date Page 2011-12-02 12 (13)

7 Troubleshooting Test the service by accessing the URL from a web browser: For service without SSL certificate:

For service with SSL certificate:

Date Page 2011-12-02 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 = "http://localhost:8080/sms/send"; 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