Build an SMS Web Service With Java

4 min readAug 20, 2021

We’ve built this example using JDK 11, Gradle 7.1, Gretty 3.0.5, and the Vonage Server SDK for Java v.6.4.0

The Vonage SMS API is a service that allows you to send and receive SMS messages anywhere in the world. Vonage provides REST APIs, but it’s much easier to use the Java SDK we’ve written for you.

You’ve already learned how to send SMS messages with Java. In this tutorial, we are taking it one step further and building a Web service around it!

View the source code on GitHub.

Prerequisites

Before starting, there are a few things you’re going to need to have installed on your development machine:

Java Development Kit
Gradle for building your project

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Create the Project

First, you need to set up your Gradle project and download the Vonage Java SDK.

Create a directory to contain your project. Inside this directory, run gradle init.

Create a new Gradle project:

Run gradle init --type=java-application command
Select Groovy as the script language
Select JUnit Jupiter as the testing framework
Leave default Project name
Leave default Source package

Install the Vonage Java SDK

Next, open the build.gradle file and add the following to the dependencies block:

Now, if you open your console in the directory that contains this build.gradle file, you can run:

This command will download the Vonage Java SDK and store it for later. If you had any source code, it would also compile that-but you haven’t written any yet. Let’s fix that!

Build a Web Service to Send SMS

We’re going to build a tiny HTTP service and then test it with Postman. Fortunately, Gradle makes this relatively easy.

First, apply the Gretty plugin to build.gradle file by adding this to your plugins block:

The first line tells Gradle it should build a war file, using source files in src/main/java and src/main/webapp. The second line adds the ability to fire up your web app straight from Gradle using the Jetty servlet container!

Next, let’s set the context path to / for the sake of simplicity.

Add the following block to build.gradle:

Run gradle appRun (note that you use appRun and not run to run the webserver). It'll take a while the first time around while it downloads some dependencies.

Eventually, you should see something like this:

Jetty is now running your (empty) web service. Fire up the URL you see to check it’s running OK. It should look a bit like this:

Now let’s write a servlet! Create a file called src/main/java/sms/webservice/SendSMSServlet.java.

And then we need to configure the servlet in our servlet container by creating the following at src/main/webapp/WEB-INF/web.xml:

Fill in VONAGE_API_KEY and VONAGE_API_SECRET with the values found in your Vonage API Dashboard. You'll need to replace VONAGE_BRAND_NAME with one of your Vonage virtual numbers.

Note: In some countries (US), VONAGE_BRAND_NAME has to be one of your Vonage virtual numbers. In other countries (UK), you're free to pick an alphanumeric string value-for example, your brand name like AcmeInc. Read about country-specific SMS features on the dev portal.

Next, run gradle appRun. If everything builds correctly, let's fire up Postman and make a POST request to http://localhost:8080/send-sms/, specifying message and to in the body as shown below:

I hope it worked! So now you’ve built a REST Web service for sending SMS messages! In reality, there are lots more things you’d want to do before deploying this. You could consider adding authentication (otherwise, anyone could send a message using your Vonage API account!), a nice Webform for posting to the service, and improving the error handling — but this is a good start!

References

Originally published at https://learn.vonage.com/blog/2021/07/20/buid-an-sms-web-service-with-java/