Vonage / vonage-kotlin-sdk

Vonage Server SDK for Kotlin. API support for SMS, RCS, Messages, Voice, Text-to-Speech, Numbers, Verify (2FA), Video and more.

Vonage Server SDK for Kotlin (JVM)

This Kotlin 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
• Configuration
• Usage
• FAQ
• Contribute!

Supported APIs

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

Other SDKs

We also provide server SDKs in other languages:

• Java
• .NET
• PHP
• Python
• NodeJS
• Ruby

We also offer client-side SDKs for Android, iOS 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. They're also available from here. Release notes for each version can be found in the changelog.

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

Gradle

Add the following to your build.gradle or build.gradle.kts file:

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

Maven

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

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

Build It Yourself

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

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

git clone [e-mail]:vonage/vonage-kotlin-sdk.git
mvn install -P uberjar

The uberjar profile will create a JAR file with all dependencies included in the target directory at the root of the repo. You can then include this in your project's classpath.

Configuration

The SDK requires very little configuration to get started.

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:

import com.vonage.client.kt.Vonage

val vonage = Vonage {
    apiKey(API_KEY); apiSecret(API_SECRET)
    applicationId(APPLICATION_ID)
    privateKeyPath(PRIVATE_KEY_PATH)
}

You can also use environment variables for convenience, by setting the following:

• VONAGE_API_KEY - Your account API key
• VONAGE_API_SECRET - Your account API secret
• VONAGE_SIGNATURE_SECRET - (Advanced, optional) Signature secret for signed requests when using SMS API
• VONAGE_APPLICATION_ID - UUID of the Vonage application you want to use
• VONAGE_PRIVATE_KEY_PATH - Absolute path to the private key file for the application

and then instantiate the client with:

val vonage = Vonage { authFromEnv() }

Customization

You can configure the base URI (for example, to do integration tests) and HTTP request timeout with httpConfig during instantiation, like so:

val vonageClient = Vonage {
    authFromEnv()
    httpConfig {
        baseUri("http://localhost:8976")
        timeoutMillis(15000)
    }
}

Usage

As with our other SDKs, the architecture is based around the Vonage class, which defines the authentication credentials and optional advanced settings for the HTTP client. The class has a field for each supported API, which returns an object containing methods available on that API. Where the SDK differs from other SDKs is that it uses a resource-based approach for CRUD operations, rather than a flat list of methods. These are inner classes defined for each API resources and are always prefixed with Existing - for example, ExistingCall, ExistingSession, ExistingApplication etc. As a general rule, resources with unique identifiers have a corresponding Existing[Resource] class which is used to perform operations on that resource, rather than repeatedly passing the ID of that resource to methods on the parent class, as is the case in the Java SDK. These resource classes are constructed from a method call in the top-level API class. So, for example, to work with an ExistingSession, you would do: client.video.session(SESSION_ID), where client is an instance of Vonage and SESSION_ID is the unique identifier of the video session you want to work with.

Examples

You can find complete runnable code samples in the Code Snippets repository, including a searchable list of snippets.

Documentation

The SDK is fully documented with KDocs, so you should have complete documentation from your IDE. You may need to click "Download Sources" in IntelliJ to get the full documentation. Alternatively, you can browse the documentation using a service like Javadoc.io, which renders the documentation for you from the artifacts on Maven Central.

For help with any specific APIs, refer to the relevant documentation on our developer portal, using the links provided in the Supported APIs section. For completeness, you can also consult the API specifications if you believe there are any discrepancies.

Frequently Asked Questions

Q: Why use this SDK instead of the Vonage Java Server SDK?

A: This Kotlin SDK is actually based on the Java SDK to improve the user experience in Kotlin. It adds syntactic sugar, so you can avoid the cumbersome builder pattern in favour of a more idiomatic DSL-like syntax, optional and named parameters with default values etc. whilst still reataining the strong typing offered by the Java SDK. Furthermore, you are more partially shielded from "platform types" (the !) so you have a better idea of what is and isn't nullable when creating requests. You can read more about the differences in the v1.0.0 announcement blog post.

Q: What is your policy on thread safety?

A: As with the Java Server SDK, 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 Vonage for each thread, or use a ThreadLocal instance.

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

A: Please see this 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: Since this library uses the Java SDK underneath, which in turn uses Apache HTTP Client 4, you may be able to use system properties to configure the client, or use this SDK's httpConfig method on the Vonage class for more fine-grained control. If you believe there is an issue with the underlying client, please raise an issue with a minimal reproducible example, including details of your environment (JVM runtime version, SDK version, operating system etc.) on the Vonage Java SDK repository.

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

A: Please see our support page, including contact information.

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 also contact us through the following channels: