NetCom SMS Bedrift API
- - -
Technical Documentation
Version 1.2 December 2008
TABLE OF CONTENTS
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... 53.3 MAXIMUM MESSAGE LENGTH... 5
3.4 DESTINATIONS... 5 4 INTERFACE ... 6 4.1 URL ... 6 4.2 AUTHENTICATION... 6 4.3 REQUEST PARAMETERS... 6 4.4 RESPONSE... 7 5 USAGE EXAMPLES ... 8 5.1 HTTPGET ... 8 5.2 HTTPPOST... 9 6 FAILURE SCENARIOS... 10 6.1 AUTHENTICATION FAILURE... 10 6.2 VALIDATION FAILURE... 10 6.3 SYSTEM FAILURE... 11 7 TROUBLESHOOTING ... 12
Page 3 of 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.
2 Solution
overview
Client application
Load balancing switch HTTP request
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. SMSC Consumer HTTP response Web servers Message queue SMSC 1 2 3 4 5 6 7 8 9
Page 5 of 13
3 Limitations
3.1 Number of recipients
The current solution can only support a singlerecipient 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.
4 Interface
4.1 URL
Protocol URL HTTP http://firebolt.netcom.no:8080/sms/send HTTPS https://firebolt.netcom.no/sms/send4.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
parameters
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).
Page 7 of 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.
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
Page 9 of 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/>
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"?>
Page 11 of 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"?>
7 Troubleshooting
Test the service by accessing the URL from a web browser: For service without SSL certificate:
Page 13 of 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(); } }
