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.
Before starting, there are a few things you’re going to need to have installed on your development machine:
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
Create a new Gradle project:
gradle init --type=java-applicationcommand
Groovyas the script language
JUnit Jupiteras the testing framework
- Leave default
- Leave default
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
The first line tells Gradle it should build a war file, using source files in
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
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
And then we need to configure the servlet in our servlet container by creating the following at
Note: In some countries (US),
VONAGE_BRAND_NAMEhas 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.
gradle appRun. If everything builds correctly, let's fire up Postman and make a POST request to
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!
Originally published at https://learn.vonage.com/blog/2021/07/20/buid-an-sms-web-service-with-java/