Nexmo Client Library for Java

You can use this Java client library to add Nexmo's API to your application. To use this, you'll need a Nexmo account. Sign up for free at nexmo.com.

• Installation
• Usage
• Tips And Tricks
• Contribute!

Installation

To use the client library you'll need to have created a Nexmo account.

Gradle

To install the Java client library using Gradle, add the following to build.gradle:

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.nexmo:client:3.3.0'
}

Maven

Add the following to the correct place in your project's POM file:

<dependency>
      <groupId>com.nexmo</groupId>
      <artifactId>client</artifactId>
      <version>3.3.0</version>
</dependency>

Build It Yourself

Alternatively you can clone the repo and build the JAR file yourself:

git clone [email protected]:nexmo/nexmo-java.git
gradle build

Download everything in a ZIP file

Note: We strongly recommend that you use a tool that supports dependency management, such as Gradle, Maven, or Ivy

We provide a ZIP file for each release, containing the client library JAR, along with all the dependencies. Download the file, unzip it, and add the JAR files to your project's classpath.

Usage

• For help understanding our APIs, check out our awesome developer portal
• Check the Javadoc for full reference documentation.
• There are also many useful code samples in our nexmo-community/nexmo-java-quickstart repository.

Send an SMS

Send an SMS with the Nexmo SMS API:

AuthMethod auth = new TokenAuthMethod(API_KEY, API_SECRET);
NexmoClient client = new NexmoClient(auth);
System.out.println(FROM_NUMBER);

SmsSubmissionResult[] responses = client.getSmsClient().submitMessage(new TextMessage(
        FROM_NUMBER,
        TO_NUMBER,
        "Hello from Nexmo!"));
for (SmsSubmissionResult response : responses) {
    System.out.println(response);
}

Make Phone Calls

The following code initiates an outbound call which then reads the user a message:

import java.nio.file.Paths;

import com.nexmo.client.NexmoClient;
import com.nexmo.client.auth.JWTAuthMethod;
import com.nexmo.client.voice.Call;
import com.nexmo.client.voice.CallEvent;

JWTAuthMethod auth = new JWTAuthMethod(application_id, Paths.get("application_key.pem"));
NexmoClient client = new NexmoClient(auth);
Call call = new Call(to, from,
                     "https://nexmo-community.github.io/ncco-examples/first_call_talk.json");
CallEvent event = client.getVoiceClient().createCall(call);

After the call is answered, you can get more information about it, including the amount it cost with:

CallInfo info = client.getVoiceClient().getCallDetails(event.getUuid());
System.out.println("This cost: " + info.getPrice() + " EUR");

You can modify an existing call in progress, for example by hanging up on the current call:

ModifyCallResponse modifyResponse = client.getVoiceClient().modifyCall(event.getUuid(), "hangup");
System.out.println(modifyResponse.getMessage());

While a call is in progress, you can send Dual-tone multi-frequency(DTMF) tones like so:

DtmfResponse dtmfResponse = client.getVoiceClient().sendDtmf(event.getUuid(), "332393");
System.out.println("Success! " + dtmfResponse.getMessage());

To stream an audio file to an active call, simply use the following method:

StreamResponse startStreamResponse = client.getVoiceClient().startStream(event.getUuid(), "https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3");
System.out.println("Success! " + startStreamResponse.getMessage());

If you'd like to stop streaming an audio file to an active call, you can do so with:

StreamResponse stopStreamResponse = client.getVoiceClient().stopStream(event.getUuid());
System.out.println("Alright. " + stopStreamResponse.getMessage());

To send a synthesized speech message to an active call, just use the following method:

TalkResponse startTalkResponse = client.getVoiceClient().startTalk(event.getUuid(), "Hello World");
System.out.println("Success! " + startTalkResponse.getMessage());

If you'd like to stop sending a synthesized speech message to an active call, you can do so with:

TalkResponse stopTalkResponse = client.getVoiceClient().stopTalk(event.getUuid());
System.out.println("Alright. " + stopTalkResponse.getMessage());

Generating NCCO Responses

Our library contains a com.nexmo.client.voice.ncco package, providing JSON-serializable objects for your NCCO webhook endpoints. You can use it like this:

TalkNcco message = new TalkNcco("Thank you for calling!");
Ncco[] nccos = new Ncco[]{message};

res.type("application/json");
return nccoMapper.writer().writeValueAsString(nccos);

Send a 2FA Code

Send a 2FA code to a phone number with:

AuthMethod auth = new TokenAuthMethod(API_KEY, API_SECRET);
NexmoClient client = new NexmoClient(auth);
VerifyResult ongoingVerify = client.getVerifyClient().verify(TO_NUMBER, "NEXMO");

Check the 2FA Code

When the user enters the code they received, you can check it like this:

client.getVerifyClient().check(ongoingVerify.getRequestId(), CODE)

Custom HTTP Configuration

If you need to configure the Apache HttpClient used for making requests, you can call NexmoClient.setHttpClient() to supply your custom configured object. This can be useful, for example, if you must use an HTTP proxy to make requests.

Tips And Tricks

Phone Calls And WebSockets

Our Voice API can connect a voice call to a websocket! An example using javax.websocket for accepting websocket connections can be found on the Oracle website. Another example using the Spark framework

License

This library is released under the MIT License

Contribute!

We ❤️ contributions to this library!

It is a good idea to talk to us first if you plan to add any new functionality. Otherwise, bug reports, bug fixes and feedback on the library is always appreciated.