Please see our important announcement.

Setting up an Inbound SMS Event Listener - Java example

1. Set up your application server

In this example, the messaging event listener is a Java Servlet, which requires a Web Container or Application Server. This example will use Apache Tomcat, but you are free to use any Application Server.

Make a note of the port that your application server is listening on (Tomcat will prompt for the port number during installation). This example will use port 7070.

2. Look at source code and build WAR file

We'll now look at the example listener code. Find attached a zip file containing the Example Inbound Event Listener source code.

Unzip this onto your machine.

If you look under InboundEventing/src/com/bt/sdk/messaging/inboundEvent you will see an InboundEventServlet.java file. This is a simple example servlet listener to help you get started. You can adapt this code later to suit your individual needs but for the time being we will leave this untouched. The default example code accepts messaging events and simply echoes them back in a response. (This will be useful to test it has deployed correctly later on).

To build the WAR file, you will need Apache Ant installed.

Navigate to the top level InboundEventing directory above and open a command prompt here. Then type in "ant"

eg: C:\InboundEventing>ant

(click image to see full size)

This will now open the already written build.xml and run this to turn your java code into a deployable WAR file. The WAR file should be called BTSDKMessagingInboundEventSample.war and found in InboundEventing/dist directory.

3. Deploy your generated WAR file

To deploy your WAR file you will need Tomcat started. Open up your web browser and enter http://localhost:<port number noted in step 2>

eg. http://localhost:7070

This should display a Tomcat front page as seen below:

(click image to see full size)

Now navigate to the "Tomcat Manager" link (found on the left-hand navigation bar). You may have to enter the username and password you set up. Now click the "Browse" button at the bottom of the loaded page where the caption reads "WAR file to deploy".

(click image to see full size)

Navigate to the InboundEventing/dist directory where the WAR was created in step 2. Then click the Deploy button. This will deploy the WAR in the tomcat web container automatically for you. If successfull you should see the deployed application in the Applications Section.

(click image to see full size)

4. Manually Test the Listener

You can test the deployment by opening a web browser and typing in a sample event to the query string.

eg: http://localhost:7070/BTSDKMessagingInboundEventSample/InboundEventServlet?message_id=12345&message_text=Well%20Lad%20hows%20the%20form!&message_recipient=me&message_date=09/10/2007%2015:47:00&message_key=Well&message_sender=tel:7712345678"

You should get back a short response in the browser echoing what you sent in. It should look something like:

(click image to see full size)

Your listening URL is made up of http://<host>:<port>/<war_name>/InboundEventServlet/

You can make use of this service if you are signed up for inbound SMS (either dedicated/shared). Just email us details of your URL (sdkportal@bt.com) with title "Inbound Events URL", it should resemble the following: http://youripaddress:7070/BTSDKMessagingInboundEventSample/InboundEventServlet/"

5. Manipulate your Inbound Event Listener

Ok - you now have a simple listener deployed which accepts event requests. Now you need to decide what you would like to do with the events you. For example: you could populate a database with your messages, and then access them via a web site. You could write them out to a textfile or blog. To do these things you simply edit the java file and repeat step 3 to step 5.

6. Extra Security

You can increase security by using secure HTTP (HTTPS) see How to Configure Tomcat to Allow SSL Requests. You can also make the service even more secure by adding your own unique key in the URL that you used to register for inbound events

eg: http://youripaddress:7070/BTSDKMessagingInboundEventSample/InboundEventServlet?someParam=myUn1queParam

This parameter will be sent back to you in the body of each HTTP POST event that BT sends to you. Your application can check this parameter to confirm it came from us.