/
Web Service - Examples

Web Service - Examples

Owned by Jan Varga (Unlicensed)
Last updated: Oct 27, 2008 by Anh Nguyen (Unlicensed)Version comment

Examples

Using the Web Services

The web services are hosted for testing on the following URL

http://test.smartmessagingservices.net:8080/gateway/services/SMSService

In order to use the SMS service you will need to be provided with a MessageCore username and password

ASP

An example using ASP to send SMS "Hello World" to 2 recipient phone numbers

Set client = Server.CreateObject("MSSOAP.SoapClient")

client.ClientProperty("ServerHTTPRequest") = True
client.MSSoapInit("http://test.smartmessagingservices.net:8080/gateway/services/SMSService?wsdl")

Dim username
Dim password
Dim recipients(1)
Dim message
Dim documentId

username = "username"
password = "password"

recipients(0) =  "0410111111"
recipients(1) =  "0410222222"

message = "Hello World"

documentId = client.send(username, password, recipients, message)

JAVA

Sending an advanced SMS document

This is an example using JAVA to send a more advanced message to the SMS gateway using the Web Service's sendDocument method.

This example sets a custom reply-to URL that has an embedded custom ID, smsid with a value of MYUNIQUEID. Such parameters may be useful for integration into existing systems and to generally keep track of custom state variables related to the SMS being sent. The reply-to URL will be stored within the system on the initial request and sent back upon SMS reply for Two-Way accounts. Addition parameters specified in this example use replacement keywords %%TEXT%% and %%FROM%% to get the reply-to SMS text body and replying address respectively for more direct access to data. The reply-to URL is as follows:

String replyToURL = "http://www.example.com/replyto.php?smsid=MYUNIQUEID&text=%%TEXT%%&from=%%FROM%%";

Rather than use a HTTP URL, it is also possible to specify a valid e-mail address as the reply-to value. The process is the same and the SMS Gateway will send the reply as an e-mail in such cases.

The code uses the mc-client.jar library, which contains useful object definitions related to the SMS Gateway's Web Services. Please refer to the sendDocument API documentation for more detailed object and options definitions that are available.

import com.amethon.mc.ws.stubs.Address;
import com.amethon.mc.ws.stubs.Body;
import com.amethon.mc.ws.stubs.Destination;
import com.amethon.mc.ws.stubs.Document;
import com.amethon.mc.ws.stubs.Message;
import com.amethon.mc.ws.stubs.Payload;
import com.amethon.mc.ws.stubs.SMSOption;
import com.amethon.mc.ws.stubs.SMSServiceServiceLocator;
import com.amethon.mc.ws.stubs.SMSServiceSoapBindingStub;
import com.amethon.mc.ws.stubs.SubmitStatus;

public class SMSServiceClient {
	public static void main(String[] args) throws Exception {
		SMSServiceServiceLocator serviceLocator = new SMSServiceServiceLocator();
		SMSServiceSoapBindingStub smsService = (SMSServiceSoapBindingStub)serviceLocator.getSMSService();

		// SMS gateway username, password and custom reply-to URL
		String username = "username@example.com";
		String password = "password";
		String replyToURL = "http://www.example.com/replyto.php?smsid=MYUNIQUEID&text=%%TEXT%%&from=%%FROM%%";

		// set SMS destination address and a empty source address
		Address destinationAddress = new Address();
		destinationAddress.setType("SMS");
		destinationAddress.setValue("61412345678");

		Address sourceAddress = new Address();
		sourceAddress.setType("SMS");
		sourceAddress.setValue("");

		// create destination object adding replyto, source and destination addresses
		SMSOption replyToOption = new SMSOption();
		replyToOption.setName("replyto");
		replyToOption.setValue(replyToURL);

		Destination destination	= new Destination();
		destination.setDestinationAddress(destinationAddress);
		destination.setOptions(new SMSOption[] {replyToOption});
		destination.setReferenceId("");
		destination.setSourceAddress(sourceAddress);

		// create message body and payload, ASCII text in this case
		Payload payload = new Payload();
		payload.setContent("This is the payload");
		payload.setEncoding("ASCII");
		payload.setType("TEXT");
		payload.setOptions(new SMSOption[] {});

		Body body = new Body();
		body.setPayloads(new Payload[] {payload});
		body.setType("TEXT");

		// create message object containing destination details
		Message message = new Message();
		message.setDestinations(new Destination[] {destination});
		message.setBody(body);
		message.setOptions(new SMSOption[] {});
		message.setReferenceId("");
		message.setSubject("This is the message subject");

		// create document object containing messages to be sent
		Document document = new Document();
		document.setUsername(username);
		document.setPassword(password);
		document.setMessages(new Message[] {message});
		document.setOptions(new SMSOption[] {});

		// documentId is returned by the SMS Gateway and can be used to query the SMS Gateway
		String documentId = smsService.sendDocument(document);
		System.out.println("documentId=" + documentId);

		// query the SMS Gateway for the status of the SMS contained within the document
		SubmitStatus[] submitStatus = smsService.query(username, password, documentId);
		for (int j=0; j<submitStatus.length; j++) {
			SubmitStatus status = submitStatus[j];
			System.out.println("  - " + status.getRecipient() + ", " + status.getStatusCode());
		}
	}
}

Application output of the above JAVA example for a successful send should look similar to the code block below. In this case the SMS addressed to 61412345678 has a state of 10 (SMS_STATE_CODE_SUBMITTED), which indicates it has been successfully submitted to the SMS Gateway.

$ java -cp .:./lib/mc-client.jar:./lib/axis.jar:./lib/jaxrpc.jar:./lib/commons-logging-1.0.4.jar:./lib/commons-discovery-0.2.jar:./lib/saaj.jar:./lib/wsdl4j-1.5.1.jar \
      SMSServiceClient

documentId=5682808080808080808080808080ECB501
  - 61412345678, 10

Once the destination handset replies to the SMS, with a message such as "This is the reply". The SMS Gateway will send a HTTP GET to the reply-to address similar to the following, which can be parsed by a web application at that URL for reply-to systems integration:

http://www.example.com/replyto.php?smsid=MYUNIQUEID&text=This is the reply&from=61412345678

Polling for SMS replies

The web services's receive method is a polling functionality used to query for SMS replies in response to out going messages that contain a reply-to value of INBOX. For example to send a out going SMS that will be used with the web service's receive method the following value needs to be substituted when creating the SMS document as in the above example,

String replyToURL = "inbox:MYUNIQUEID"

The key part of the reply-to value is that it begins with the key word 'inbox:'. It is possible to us any string there after as the destination address identifier. Preferably the string should be a sensible identifier of some form for the case where the user would like to search for reply messages based on destination address. In this example it is set to MYUNIQUEID, alternatively it is also acceptable to not pass a destination value other than 'inbox:'.

The inbox: reply-to value is only supported from the web service's API. It cannot be used or set by sending a SMS via the deprecated XML API. Doing so will result in a XML parsing error.

The following is a simple example JAVA class that shows how to use the web service's receive method to query for a SMS reply using a document-id based on the sending example above using the substituted replyToURL value prefixed with 'inbox:',

import com.amethon.mc.ws.stubs.Message;
import com.amethon.mc.ws.stubs.SMSOption;
import com.amethon.mc.ws.stubs.SMSServiceServiceLocator;
import com.amethon.mc.ws.stubs.SMSServiceSoapBindingStub;

public class SMSReceiveClient {
	public static void main(String[] args) throws Exception {
		SMSServiceServiceLocator serviceLocator = new SMSServiceServiceLocator();
		SMSServiceSoapBindingStub smsService = (SMSServiceSoapBindingStub)serviceLocator.getSMSService();

		String username = "username@example.com";
		String password = "password";
		String documentId;

		// Stop if there is no arguments supplied
		if (args.length == 0) {
			System.out.println("Required option missing: Document-Id");
			System.exit(1);
		}

		// documentId is passed as first argument to program
		documentId = args[0];

		// create a documentId option
		SMSOption documentIdOption = new SMSOption();
		documentIdOption.setName("document-id");
		documentIdOption.setValue(args[0]);
		SMSOption[] receiveOptions = {documentIdOption};

		// poll for messages received passing in the documentId option
		Message[] receivedMessages = smsService.receive(username, password, receiveOptions);

		// iterate over the received Message array
		for (Message receivedMessage : receivedMessages) {
			// Gets the source address and message body assuming its ASCII text
			String source = receivedMessage.getDestinations()[0].getSourceAddress().getValue();
			String subject = receivedMessage.getSubject();

			if (subject != null) {
				// The subject usually contains a error code if it is set
				System.out.println("Received message from " + source + " : " + subject);
			}
			else {
				// Get the message and print it out
				String message = receivedMessage.getBody().getPayloads()[0].getContent();
				System.out.println(source + " : " + message);
			}
		}

		System.exit(0);
	}
}

Running the receive application returns the following reply message that was sent back to the system from the handset 61412345678,

$ java -cp .:./lib/mc-client.jar:./lib/axis.jar:./lib/jaxrpc.jar:./lib/commons-logging-1.0.4.jar:./lib/commons-discovery-0.2.jar:./lib/saaj.jar:./lib/wsdl4j-1.5.1.jar \
      SMSReceiveClient 5682808080808080808080808080ECB501

61412345678 : this is the reply