Introduction
In this tutorial you will create an application that can receive phone calls using Java and the Nexmo Voice API.
Prerequisites
To work through this tutorial, you will need a Nexmo account. Sign up now if you don’t already have an account.
You will be using Gradle to manage your dependencies and run your application. Additionally, you’ll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.
Finally, you’ll need the Nexmo CLI installed. You’ll use it to purchase a phone number and configure your Nexmo account to point at your new application.
Receiving a Call with Java
This tutorial will walk you through the following steps:
- Using Gradle to setup a new Java project.
- Using the Spark framework for controlling the call.
- Purchasing a number and configuring your Nexmo account to use that number with your application.
Using Gradle to Setup a New Java Project
You will use Gradle to manage your dependencies and to create and run your Java application. From the command line, create a new Java project with the following commands:
|
1 2 3 4 |
mkdir receive-call cd receive-call gradle init --type java-application |
The gradle init --type java-application command will create all of the folders you will need as well as a sample class where you will be writing your code.
Using the Spark Framework for Controlling the Call
You will use the Spark framework to intercept the HTTP call that Nexmo uses when your number receives a call.
Adding the Dependencies
Add the following to your dependencies block in your build.gradle file:
|
1 2 3 |
compile 'com.sparkjava:spark-core:2.7.2' compile 'com.nexmo:client:4.0.1' |
Your dependencies block should look like this:
|
1 2 3 4 5 6 7 8 9 10 |
dependencies { // This dependency is found on compile classpath of this component and consumers. compile 'com.google.guava:guava:23.0' compile 'com.sparkjava:spark-core:2.7.2' compile 'com.nexmo:client:4.0.1 // Use JUnit test framework testCompile 'junit:junit:4.12' } |
Setup the Route
Gradle will create the App class in the src/main/java folder. Inside of this class is a getGreeting and a main method. You won’t need the getGreeting method, so feel free to remove it.
Replace the contents of the main method, resolving any imports, with:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
/* * Route to answer incoming call. */ Route answerRoute = (req, res) -> { String from = req.queryParams("from").replace("", " "); TalkAction message = new TalkAction .Builder(String.format("Thank you for calling from %s", from)) .build(); res.type("application/json"); return new Ncco(message).toJson(); }; /* * Route to print out call event info. */ Route eventRoute = (req, res) -> { System.out.println(req.body()); return ""; }; Spark.port(3000); Spark.get("/webhooks/answer", answerRoute); Spark.post("/webhooks/events", eventRoute); |
This code will setup a route on http://localhost:3000/webhooks/answer which will respond with the following Nexmo Call Control Object (NCCO):
|
1 2 3 4 5 6 7 |
[ { "text": "Thank you for calling from y o u r - p h o n e - n u m b e r ", "action": "talk" } ] |
The NCCO will instruct Nexmo to speak the text property back to the caller.
A route will also be setup on http://localhost:3000/webhooks/events which Nexmo will use to communicate call status changes.
Purchasing a Number
You will need a Nexmo number in order to receive phone calls. If you do not have a number you can use the Nexmo CLI to purchase one:
|
1 2 |
nexmo number:buy --country_code US |
Take note of the number that is assigned to you on purchase. You will need this number to link your application and for testing.
Exposing Your Application
In order to send an HTTP request to your application, Nexmo needs to know the URL that your application is running on.
Instead of configuring your local network or hosting your application on an external service, you can use ngrok to safely expose your application to the internet.
Download ngrok and run the following command:
|
1 2 |
ngrok http 3000 |
Take note of the forwarding address as you will need it when you configure your account. In the following picture, the forwarding address is http://99cad2de.ngrok.io.
Configure Your Nexmo Account
If you do not have an application you can use the Nexmo CLI to create one using your ngrok forwarding address:
|
1 2 |
nexmo app:create "Receive Call Demo" http://your-ngrok-forwarding-address/webhooks/answer http://your-ngrok-forwarding-address/webhooks/events --keyfile private.key |
After running this command, you will be shown an an application id. For example: notreal-1111-2222-3333-appid. You will need this application id to link your phone number to the application.
You can use the Nexmo CLI to link your phone number and application:
|
1 2 |
nexmo link:app your-nexmo-phone-number your-application-id |
This command instructs Nexmo to create a new application on your account. The application will send a request to the first URL when it receives a phone call. The application will send requests to the second URL when the call status changes.
Test Your Application
Start your application with the gradle run command inside of your receive-call directory.
Make a call to your Nexmo number and test out your application. You will hear the message, “Thank you for calling from” along with your phone number.
Conclusion
In a few lines of code you have created an application that can receive a phone call and speak a message to the caller. Experiment with other ways you can interact with them.
Check out our documentation on Nexmo Developer where you can learn more about call flow or Nexmo Call Control Objects. See our Nexmo Quickstart Examples for Java for full code examples on this tutorial and more.
Developer
