Repository files navigation

This Java SDK allows you to useVonage APIs in any JVM-based application.You'll need to havecreated a Vonage account.

• Supported APIs
• Other SDKs
• Installation
• Usage
• Configuration
• FAQ
• Contribute!

• Account
• Application
• Conversation
• Conversion
• Messages
• Number Insight
• Number Management
• Number Verification
• Redact
• SIM Swap
• SMS
• Subaccounts
• Verify
• Video
• Voice

We also provide server SDKs in other languages:

• Kotlin
• .NET
• PHP
• Python
• Ruby
• NodeJS

We also offerclient-side SDKs for iOS, Android and JavaScript.See all of our SDKs and integrations on theVonage Developer portal.

Releases are published toMaven Central.Instructions for your build system can be found in the snippets section.Westrongly recommend that you use a tool that supports dependency management,such asMaven,Gradle orIvy.

Release notes for each version can be found in thechangelog.

Here are the instructions for including the SDK in your project:

Add the following to yourbuild.gradle orbuild.gradle.kts file:

dependencies {    implementation("com.vonage:server-sdk:9.4.2")}

Add the following to the<dependencies> section of yourpom.xml file:

<dependency>    <groupId>com.vonage</groupId>    <artifactId>server-sdk</artifactId>    <version>9.4.2</version></dependency>

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

git clone git@github.com:vonage/vonage-java-sdk.gitmvn install -P uberjar

Theuberjar profile will create a JAR file with all dependencies required to run the SDK included,which can be found in thetarget directory. Theinstall goal will make the SDK and its dependenciesavailable in your local Maven repository (usually located under your~/.m2 directory), which can thenbe used from other projects locally on your machine. To use this in a Gradle project, you need to includethe dependency co-ordinates and addmavenLocal() to therepositories block in yourbuild.gradle file.

• For help understanding our APIs, check out our awesomedeveloper portal.
• Check theJavadoc for full reference documentation.
• There are alsomany useful code samples in ourVonage/vonage-java-code-snippets repository.
• For a searchable list of code snippets examples, seeSNIPPETS.md.
• For Video API usage instructions, seethe guide on our developer portal.

Beginning with v9.1.0, you can now make customisable requests to any Vonage API endpoint using theCustomClient class,obtained from theVonageClient#getCustomClient() method. This will take care of auth and serialisation for you.You can use existing data models from the SDK or create your own by extendingcom.vonage.client.JsonableBaseObjector implementing thecom.vonage.client.Jsonable interface. For example, you can check your account balance usingthe following code, which will send aget request to the specified URL and return aBalanceResponse object:

BalanceResponseresponse =client.getCustomClient().get("https://rest.nexmo.com/account/get-balance");

You can also parse the response into aMap<String, ?> which represents the JSON response body as a tree like so:

Map<String, ?>response =client.getCustomClient().get("https://api-eu.vonage.com/v3/media?order=ascending&page_size=50");

The same applies forPOST,PUT andPATCH requests when sending data.You can mix and match betweenjava.util.Map andcom.vonage.client.Jsonable interfaces for request and response bodies.For example, to create an application, you can use any of the following (all are equivalent):

Map<String, ?>response =client.getCustomClient().post("https://api.nexmo.com/v2/applications",Map.of("name","Demo Application"));

Applicationresponse =client.getCustomClient().post("https://api.nexmo.com/v2/applications",Map.of("name","Demo Application"));

Map<String, ?>response =client.getCustomClient().post("https://api.nexmo.com/v2/applications",Application.builder().name("Demo Application").build());

Applicationresponse =client.getCustomClient().post("https://api.nexmo.com/v2/applications",Application.builder().name("Demo Application").build());

The<R> parameter in the response type methods does not have to be aMap<String, ?> orJsonable; it can alsobe aString,byte[] (for binary types) orCollection (for JSON arrays). The following will work, for example:

Stringresponse =client.getCustomClient().get("https://example.com");

TheCustomClient provides preset methods for the supported HTTP request types and JSON-based request bodies.However, if you would like to make a request with non-JSON body (e.g. binary data), you can use themakeRequest method.This is a more convenient way of usingcom.vonage.client.DynamicEndpoint which takes care of most of the setup for you.

Whilst theCustomClient class is a powerful tool, it is not intended to be a replacement for dedicated supportwhich the SDK provides for Vonage APIs. Furthermore, you may notice your IDE giving warnings like"Unchecked generics array creation for varargs parameter". This is because all methods inCustomClient use avarargs parameter for the response type as a way to infer the response type without you having to explicitly providetheClass<R> parameter. This is a known limitation of Java generics and is not a problem with the SDK itself, it isimplemented this way for your convenience. As per the documentation, it is important to not pass any value for thisvarargs parameter — just omit it. If you do pass a value, the SDK will not be able to infer the response type.You should also always use explicit assignment for theCustomClient methods, as the SDK will not be able to infer the return type if you usevar orObject.If you do not assign the response to a typed variable explicitly,Void will be inferred and the method will returnnull.

For default configuration, you just need to specify your Vonage account credentials using API key and secret, privatekey and application ID or both. For maximum compatibility with all APIs, it is recommended that you specify bothauthentication methods, like so:

VonageClientclient =VonageClient.builder()        .applicationId(APPLICATION_ID)        .privateKeyPath(PRIVATE_KEY_PATH)        .apiKey(API_KEY)        .apiSecret(API_SECRET)        .build();

By default, the client will usehttps://api.nexmo.com,https://rest.nexmo.com,https://api-eu.vonage.com andhttps://video.api.vonage.com as base URIs for the various endpoints. To customize these you can instantiateVonageClient with anHttpConfig object.

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

HttpConfighttpConfig =HttpConfig.builder()        .apiBaseUri("https://api.example.com")        .restBaseUri("https://rest.example.com")        .apiEuBaseUri("https://api-eu.example.com")        .videoBaseUri("https://video.example.com")        .build();VonageClientclient =VonageClient.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:

HttpConfighttpConfig =HttpConfig.builder().baseUri("http://example.com").build();VonageClientclient =VonageClient.builder()        .apiKey(API_KEY).apiSecret(API_SECRET)        .httpConfig(httpConfig)        .build();

By default, the SDK has a 1-minute timeout for requests.You can change this to be longer or shorter usingHttpConfig. The following example sets this to 12 seconds:

VonageClientclient =VonageClient.builder()        .applicationId(APPLICATION_ID)        .privateKeyPath(PRIVATE_KEY_PATH)        .httpConfig(HttpConfig.builder().timeoutMillis(12_000).build())        .build();

You can set a proxy server for requests using theproxy method onHttpConfig.Builder.

VonageClientclient =VonageClient.builder()        .applicationId(APPLICATION_ID)        .privateKeyPath(PRIVATE_KEY_PATH)        .httpConfig(HttpConfig.builder().proxy("https://myserver.example.com").build())        .build();

With theHttpConfig class, you can also set custom request headers for all requests made by the SDK.

VonageClientclient =VonageClient.builder()        .applicationId(APPLICATION_ID)        .privateKeyPath(PRIVATE_KEY_PATH)        .httpConfig(HttpConfig.builder()                .addRequestHeader("X-My-Header","MyValue")                .addRequestHeader("Correlation-Id","123-456-789")                .build()        )        .build();

The SDK usesJava's built-in logging library (java.util.logging) to log requests and responses.This is primarily centralised in two places:AbstractMethodandDynamicEndpoint.For most cases, the former should provide sufficient level of detail.It can be activated by setting the logger level toFINE, like so:

LogManager.getLogManager().getLogger("com.vonage.client.AbstractMethod").setLevel(Level.FINE);

Since the logger onDynamicEndpoint is not static and based on the class name, it will only be activated if theglobal log level is set toFINE. You can set the global log level like so:

LogManager.getLogManager().getLogger("").setLevel(Level.FINE);

This will also activate the logger onAbstractMethod if you haven't already specified the desired log level onthat class, so you don't need to set it separately.

Q: What happened tocom.vonage:client?

A: To avoid confusion with our various client-side SDKs, this server-side SDK has been moved fromthecom.vonage:client coordinates tocom.vonage:server-sdk. The old artifactId (com.vonage:client) willnot receive further updates. All users should migrate to the new artifactId. Please note that the SDK is functionallythe same, it is just a namespace change on Maven Central.

Q: What is your policy on thread safety?

A: The current architecture of the SDK means that only one thread should use the client at a time.If you would like to use the SDK in a multithreaded environment, create a separate instance ofVonageClient for each thread.

Q: Does this SDK support asynchronous request / response processing?

A: Currently no, but it ison the roadmap.

Q: I'm having issues with my project when including the SDK as a dependency. How can I troubleshoot this?

A: Please seethis blog post.In short, you may have conflicting dependency versions in your project which clash with this SDK's transitive dependencies.

Q: I'm encountering HTTP request issues, such as timeouts. How can I remedy or report this?

A: This SDK usesApache HTTP Client 4 under thehood, so you may be able to use system properties to configure the client, or use this SDK'shttpConfig method ontheVonage class for more fine-grained control. If you believe there is an issue with the underlying client, pleaseraise an issue with a minimal reproducible example,including details of your environment (JVM runtime version, SDK version, operating system etc.)

Q: I'm not sure if my issue is with the SDK. How can I get help?

A: Please see oursupport page, including contact information.

Q: How do I migrate from TokBox to Vonage?

A: Seethe OpenTok migration guide.

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 thelibrary are always appreciated.