README.md

Vonage Server SDK for Java

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

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

Supported APIs

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

Other SDKs

We also provide server SDKs in other languages:

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

We also offer client-side SDKs for iOS, Android and JavaScript. See all of our SDKs and integrations on the Vonage Developer portal.

Installation

Releases are published to Maven Central. Instructions for your build system can be found in the snippets section. We strongly recommend that you use a tool that supports dependency management, such as Maven, Gradle or Ivy.

Release notes for each version can be found in the changelog.

Build It Yourself

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

git clone [email protected]:vonage/vonage-java-sdk.git
mvn install -P uberjar

The uberjar profile will create a JAR file with all dependencies required to run the SDK included, which can be found in the target directory. The install goal will make the SDK and its dependencies available in your local Maven repository (usually located under your ~/.m2 directory), which can then be used from other projects locally on your machine. To use this in a Gradle project, you need to include the dependency co-ordinates and add mavenLocal() to the repositories block in your build.gradle file.

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 Vonage/vonage-java-code-snippets repository.
• For Video API usage instructions, see the guide on our developer portal.

Configuration

Typical Instantiation

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

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

Customize the Base URI

By default, the client will use https://api.nexmo.com, https://rest.nexmo.com, https://api-eu.vonage.com and https://video.api.vonage.com as base URIs for the various endpoints. To customize these you can instantiate VonageClient 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")
        .apiEuBaseUri("https://api-eu.example.com")
        .videoBaseUri("https://video.example.com")
        .build();

VonageClient client = 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:

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

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

Custom Timeout

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

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

Frequently Asked Questions

Q: What happened to com.vonage:client?

A: To avoid confusion with our various client-side SDKs, this server-side SDK has been moved from the com.vonage:client coordinates to com.vonage:server-sdk. The old artifactId (com.vonage:client) will not receive further updates. All users should migrate to the new artifactId. Please note that the SDK is functionally the 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 of VonageClient for each thread.

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

A: Currently no, but it is on the roadmap.

Q: How do I migrate from TokBox to Vonage?

A: See the OpenTok migration guide.

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.

Contact