Skip to content
Nexmo REST API Client Library for Java. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
gradle/wrapper
src Bump version: 4.1.0 → 4.2.0 Mar 20, 2019
.bumpversion.cfg
.gitallowed Big Refactor (#44) Mar 15, 2017
.gitignore Update dependency instructions to suggest the use of implementation. Oct 30, 2018
.travis.yml
CHANGELOG.md
CONTRIBUTORS.md
LICENSE.txt
README.md
build.gradle
codecov.yml Version 2 (#36) Feb 4, 2017
gradlew
gradlew.bat Update Gradle wrapper to 4.9 Jul 20, 2018

README.md

Nexmo Client Library for Java

Maven Release Build Status codecov Codacy Badge

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

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()
}

For Gradle 3.4 or Higher:

dependencies {
    implementation 'com.nexmo:client:4.2.0'
}

For older versions:

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

Maven

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

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

Build It Yourself

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

git clone git@github.com: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

Customize the Base URI

By default, the client will use https://api.nexmo.com, https://rest.nexmo.com, and https://sns.nexmo.com as base URIs for the various endpoints. To customize these you can instantiate NexmoClient with an HttpConfig object.

HttpConfig.Builder has been created to assist in building this object. Usage is as follows:

HttpConfig httpConfig = HttpConfig.builder()
        .apiBaseUri("https://api.example.com")
        .restBaseUri("https://rest.example.com")
        .snsBaseUri("https://sns.example.com")
        .build();

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .httpConfig(httpConfig)
        .build();

If you do not specify a property, it will take on whatever the default value is. You can also set all three with a single method:

HttpConfig httpConfig = HttpConfig.builder().baseUri("http://example.com").build();

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .httpConfig(httpConfig)
        .build();

To keep the default values, you can use HttpConfig.defaultConfig():

HttpConfig httpConfig = HttpConfig.defaultConfig();

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .httpConfig(httpConfig)
        .build();;

You can also instantiate without the parameter:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();

Send an SMS

Send an SMS with the Nexmo SMS API:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();

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

Make Phone Calls

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

NexmoClient client = NexmoClient.builder()
        .applicationId(APP_ID)
        .privateKeyPath("application_key.pem")
        .build();

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.

Each of the Action items contain a Builder class that can be used for constructing various actions. These actions are then added to an Ncco object for serialization into JSON:

TalkAction intro = TalkAction.builder("At the tone, record your response and press #.")
                        .voiceName(VoiceName.KIMBERLY)
                        .build();

TalkAction outro = TalkAction.builder("Thanks, goodbye!")
                        .voiceName(VoiceName.KIMBERLY)
                        .build();

RecordAction record = RecordAction.builder()
                        .beepStart(true)
                        .endOnKey('#')
                        .build()
                        
res.type("application/json");
return new Ncco(intro, record, outro).toJson();

Make a Phone Call with an NCCO

You can combine the above examples to send an NCCO to the Voice API:

The following code initiates an outbound call which then reads the user [a message](https://nexmo-community.github.io/ncco-examples/first_call_talk.json):

```java
NexmoClient client = NexmoClient.builder()
        .applicationId(APP_ID)
        .privateKeyPath("application_key.pem")
        .build();

Ncco ncco = new Ncco(
    TalkAction.builder("Hi, this is Russell. You are listening to a text-to-speech Call made with Nexmo's Voice API")
        .voiceName(VoiceName.RUSSELL)
        .build()
);

Call call = new Call(to, from, ncco);
CallEvent event = client.getVoiceClient().createCall(call);

Send a 2FA Code

Send a 2FA code to a phone number with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
VerifyResponse 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)

Get a List of SMS Prices for a Country

Get a list of SMS prices for a country with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
PricingResponse response = client.getAccountClient().getSmsPrice("GB");
System.out.println(response.getDefaultPrice());

Get a List of Voice Prices for a Country

Get a list of voice prices for a country with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
PricingResponse response = client.getAccountClient().getVoicePrice("US");
System.out.println(response.getDefaultPrice());

Get a List of SMS Prices for a Prefix

Get a list of SMS prices for a country with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
PrefixPricingResponse response = client.getAccountClient().getPrefixPrice(ServiceType.SMS, "1");
System.out.println(response.getCountries().get(0).getDefaultPrice());

Get a List of Voice Prices for a Prefix

Get a list of voice prices for a country with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
PrefixPricingResponse response = client.getAccountClient().getPrefixPrice(ServiceType.VOICE, "1");
System.out.println(response.getCountries().get(0).getDefaultPrice());

Top-up Account

Top-up your account that has auto-reload enabled with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
client.getAccountClient().topUp("TRANSACTION_NUMBER");

Submit Conversion

Submit a request to the Conversion API when it has been enabled on your account with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
client.getConversionClient().submitConversion(ConversionRequest.Type.VOICE,
                                     "MESSAGE-ID",
                                     true,
                                     new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2014-03-04 10:11:12"));

Redact Inbound SMS

Submit a request to the Redact API when it has been enabled on your account with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
client.getRedactClient().redactTransaction(SMS_ID, RedactRequest.Product.SMS, RedactRequest.Type.INBOUND);

Redact Voice

Submit a request to the Redact API when it has been enabled on your account with:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
client.getRedactClient().redactTransaction(VOICE_ID, RedactRequest.Product.VOICE);

Create Secret

Create a secret associated with your account id:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
SecretResponse response = client.getAccountClient().createSecret(API_KEY, "Foo84RSecret");

List Secrets

List the secret id (but not content) associated with your account id:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
ListSecretsResponse response = client.getAccountClient().listSecrets(API_KEY);

Collection<SecretResponse> secrets = response.getSecrets();

Revoke Secret

Revoke a secret associated with your account id:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
client.getAccountClient().revokeSecret(API_KEY, SECRET_ID);

Retrieve Secret

Get information about a specific secret associated with your account id:

NexmoClient client = NexmoClient.builder()
        .apiKey(API_KEY)
        .apiSecret(API_SECRET)
        .build();
SecretResponse response = client.getAccountClient().getSecret(API_KEY, SECRET_ID);

Custom HTTP Configuration

If you need to configure the Apache HttpClient used for making requests, you can call NexmoClient.Builder.httpClient() 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 are always appreciated.

You can’t perform that action at this time.