How to Receive SMS Messages with Java

Published May 31, 2017 by Mark Smith

In the last tutorial, we set up a Java web app that can send SMS messages using Nexmo’s SMS API. This tutorial builds on that, adding an endpoint that will be called by Nexmo when someone sends an SMS message to your Nexmo number.

How Does It Work?

When Nexmo receives an SMS message on a Nexmo number, it looks up the webhook endpoint (URL) associated with that number and calls that URL with a big blob of JSON describing the message that was just received.

Receiving an SMS message

What we’re going to do in this tutorial is write a Servlet that can handle the incoming SMS message. The problem is that while we’re developing on our local machine, we are likely to be firewalled from the internet, so Nexmo’s servers can’t reach us! One way around this would be to continuously deploy to a public web server, but that is a complete pain. Fortunately there is an excellent tool called Ngrok that can help us with this problem.

Developing Webhooks With Ngrok

When you run Ngrok, it creates a new subdomain of, and then it tunnels all requests to that domain name to a web service running on your machine. Handy!

So go install Ngrok (I’ll wait here). Once you’ve done that, run ngrok in your terminal:

Jetty uses the 8080 port by default, so we’ll use that to make life easier. You can see from the screenshot that Ngrok has allocated me the random URL, which is now tunneling to localhost:8080, where I’ll be running Jetty in a moment.

Ngrok output

Leave Ngrok running in a terminal window (it’ll happily run until you shut it down), and we want to keep the URL and tunnel running for a while. What we’d like to do now is to configure Nexmo to point to our Ngrok URL, but it won’t do so unless the URL is returning 200 messages. So we need to write a small stub servlet first.

A Servlet To Receive The SMS Message

In `src/main/java/getstarted/’, paste the following:

All the Servlet does is to print the received parameters to the console–useful for debugging! Now configure your web.xml with the following:

Note that I’ve reconfigured the send-sms mapping so the url-pattern is now /send instead of the wildcard mapping it was before. Now if you run gradle appRun, Jetty should start up and you’re ready to configure your Nexmo web-hook.

Configure Nexmo To Call Your Webhook

Sign into your Nexmo account and go to Your Numbers. Find the number you want to configure, hit ‘Edit’ and then enter the ngrok URL with /YOUR_PROJECT_NAME/inbound at the end.

Now, if you send a text message to the number, you should see some lines printed on your console:

And That’s It!

So now you can receive SMS messages! At the moment, all we’re doing is printing them out to the console. It’s often useful to store them in a database of some kind, but you can do anything you want with them now: build a Slack bot to post them to your Slack channel; pass them through Google Translate and then forward the messages to your phone; forward them to Twitter? The possibilities are endless!

Documentation Links

The following documentation links will be useful for working with SMS messages:

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at