NetCom SMS Bedrift API Technical Documentation

NetCom SMS Bedrift API- - - - -Technical DocumentationVersion 1.2December 2008

NetCom SMS Bedrift APITechnical DocumentationTABLE OF CONTENTS1 INTRODUCTION ...................................................................................................... 31.1 SCOPE................................................................................................................ 31.2 REVISION HISTORY .............................................................................................. 32 SOLUTION OVERVIEW........................................................................................... 43 LIMITATIONS........................................................................................................... 53.1 NUMBER OF RECIPIENTS...................................................................................... 53.2 ORIGINATING ADDRESS........................................................................................ 53.3 MAXIMUM MESSAGE LENGTH................................................................................ 53.4 DESTINATIONS .................................................................................................... 54 INTERFACE ............................................................................................................. 64.1 URL ................................................................................................................... 64.2 AUTHENTICATION ................................................................................................ 64.3 REQUEST PARAMETERS....................................................................................... 64.4 RESPONSE.......................................................................................................... 75 USAGE EXAMPLES ................................................................................................ 85.1 HTTP GET ......................................................................................................... 85.2 HTTP POST....................................................................................................... 96 FAILURE SCENARIOS.......................................................................................... 106.1 AUTHENTICATION FAILURE ................................................................................. 106.2 VALIDATION FAILURE ......................................................................................... 106.3 SYSTEM FAILURE............................................................................................... 117 TROUBLESHOOTING ........................................................................................... 128. SAMPLE JAVA CLIENT ........................................................................................ 13Page 2 of 13

NetCom SMS Bedrift APITechnical Documentation1 Introduction1.1 ScopeThis document describes the technical interface to the NetCom SMS Bedrift solution.A simple Java example is also included.1.2 Revision historyDate Revision Author Comments16.03.2002 1.0 JSL Initial version15.05.2002 1.1 SSC Added information about SSL18.12.2008 1.2 TRU Corrected SMS destination information.International SMS is possible.Page 3 of 13

NetCom SMS Bedrift APITechnical Documentation2 Solution overviewDescription:HTTP requestClient applicationHTTP response1. The client applicationissues an HTTPrequest (GET orPOST) to a specifiedURL.2. A load balancingswitch distributes therequests across theweb servers.Load balancing switchWeb serversMessage queue3. The web servervalidates the request,performs anynecessary characterconversion and placesthe message in amessage queue. TheHTTP is generatedand returned to theclient.4. At the other end of thequeue, a consumertakes the messagefrom the messagequeue and dispatchesit to one of theSMSC’s. Theconsumer will alsocreate a log entry forsettlement purposes.Consumer5. The SMS message isdelivered to therecipient.SMSCSMSC1 2 34 5 67 8 9Page 4 of 13

NetCom SMS Bedrift APITechnical Documentation3 Limitations3.1 Number of recipientsThe current solution can only support a single recipient per message.3.2 Originating addressThe 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 smalland 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 lengthThe maximum message length is 640 characters. Messages that are longerthan 160 characters will be split into several parts.3.4 DestinationsThe service allows sending to all GSM phones available through NetComsinterconnections.Page 5 of 13

NetCom SMS Bedrift APITechnical Documentation4 Interface4.1 URLProtocolHTTPHTTPSURLhttp://firebolt.netcom.no:8080/sms/sendhttps://firebolt.netcom.no/sms/send4.2 AuthenticationExample: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 usernameand password and then applying base64 encoding.Authorization: Basic bmV0Y69tOm5ldKNvbXi5eg==4.3 Request parametersName Description Mandatorymessage The message text.yesnumbertruncateThe message will be checked to ensure that allcharacters are supported by the SMS-C.Unsupported/illegal characters will be automaticallyconverted to their supported counterparts.The recipient MSISDN including the internationalprefix. Do not include a leading ‘+’.Example: ‘4793224070’Optional parameter that can be used to truncate amessage to 160 characters.truncate=1 truncate messagetruncate=0 no truncationDefault is no truncation (0).yesnoPage 6 of 13

NetCom SMS Bedrift APITechnical Documentation4.4 ResponseThe HTTP response is encoded as XML (content type text/xml).The basic structure of the response XML is shown below:Status code values:-Status code Description200 Success.The message has been accepted for delivery and will beforwarded to the recipient.504 Validation error.The message has been rejected because of a validationerror. 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 systemfailure.Page 7 of 13

NetCom SMS Bedrift APITechnical Documentation5 Usage examples5.1 HTTP GETRequestGET /sms/send?number=4793224070&message=hei HTTP/1.1Authorization: Basic bmV0Y89tOm3ldJNvbXh5eg==User-Agent: Java1.3.1_01Host: localhost:8080Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2Connection: keep-aliveResponseCommentsHTTP/1.1 200 OKContent-Type: text/xmlDate: Sat, 16 Mar 2002 14:03:09 GMTTransfer-Encoding: chunkedServer: Apache Tomcat/4.0.1 (HTTP/1.1 Connector)200The fully qualified URL is:http://firebolt.netcom.no:8080/sms/send?number=4793224070&message=heiPage 8 of 13

NetCom SMS Bedrift APITechnical Documentation6.3 System failureResponseThe 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/1.1 200 OKContent-Type: text/xmlDate: Sat, 16 Mar 2002 14:19:15 GMTServer: Apache Tomcat/4.0.1 (HTTP/1.1 Connector)Connection: close 512 numberPage 11 of 13

NetCom SMS Bedrift APITechnical Documentation7 TroubleshootingTest the service by accessing the URL from a web browser:For service without SSL certificate:For service with SSL certificate:Page 12 of 13

NetCom SMS Bedrift APITechnical Documentation8. 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 ";//** -------------------------------------------------------------------------//** 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 requestString sNumber = sArgs[0];String sMessage = sArgs[1];String sRequest = sUrl + "?" + "number=" + sNumber +"&" + "message=" + URLEncoder.encode(sMessage);URLConnection conn = new URL(sRequest).openConnection();// set authorization headerBase64Encoder enc = new Base64Encoder(sUser + ":" + sPassword);String sAuthHeader = "Basic " + enc.processString();conn.setRequestProperty("Authorization",sAuthHeader);// issue requestBufferedReader reader = new BufferedReader(new InputStreamReader((InputStream)conn.getContent()));// read responseString sLine = null;while ((sLine = reader.readLine()) != null)System.out.println(sLine);}catch (Exception e) { e.printStackTrace(); }} // class SmsSendClientPage 13 of 13