{"id":19123314,"url":"https://github.com/vonage/vonage-kotlin-sdk","last_synced_at":"2026-02-28T08:10:21.264Z","repository":{"id":246063143,"uuid":"810847575","full_name":"Vonage/vonage-kotlin-sdk","owner":"Vonage","description":"Vonage Server SDK for Kotlin. API support for SMS, RCS, Messages, Voice, Text-to-Speech, Numbers, Verify (2FA), Video and more.","archived":false,"fork":false,"pushed_at":"2025-04-08T12:58:47.000Z","size":410,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-13T03:47:11.049Z","etag":null,"topics":["2fa","kotlin-sdk","messaging-api","network-api","server-sdk","text-to-speech","video-api","voice-api","vonage","vonage-api","vonage-sms","vonage-video-api","vonage-voice","whatsapp-messages"],"latest_commit_sha":null,"homepage":"https://developer.vonage.com/en/home","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vonage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-05T13:13:39.000Z","updated_at":"2025-04-08T12:56:09.000Z","dependencies_parsed_at":"2024-06-25T17:14:19.792Z","dependency_job_id":"cc436cf4-ede8-46da-849a-2689fb88c32a","html_url":"https://github.com/Vonage/vonage-kotlin-sdk","commit_stats":null,"previous_names":["vonage/vonage-kotlin-sdk"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vonage%2Fvonage-kotlin-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vonage%2Fvonage-kotlin-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vonage%2Fvonage-kotlin-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vonage%2Fvonage-kotlin-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vonage","download_url":"https://codeload.github.com/Vonage/vonage-kotlin-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248855616,"owners_count":21172606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2fa","kotlin-sdk","messaging-api","network-api","server-sdk","text-to-speech","video-api","voice-api","vonage","vonage-api","vonage-sms","vonage-video-api","vonage-voice","whatsapp-messages"],"created_at":"2024-11-09T05:25:06.287Z","updated_at":"2026-02-28T08:10:21.253Z","avatar_url":"https://github.com/Vonage.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vonage Server SDK for Kotlin (JVM)\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.vonage/server-sdk-kotlin)](https://central.sonatype.com/artifact/com.vonage/server-sdk-kotlin)\n[![Build Status](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml/badge.svg)](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml)\n![CodeQL](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/codeql.yml/badge.svg)\n[![codecov](https://codecov.io/gh/Vonage/vonage-kotlin-sdk/graph/badge.svg?token=YNBJUD8OUT)](https://codecov.io/gh/Vonage/vonage-kotlin-sdk)\n![SLOC](https://sloc.xyz/github/Vonage/vonage-kotlin-sdk?)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Vonage/vonage-kotlin-sdk/badge)](https://scorecard.dev/viewer/?uri=github.com/Vonage/vonage-kotlin-sdk)\n\u003c!--[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE.txt)--\u003e\n\nThis Kotlin SDK allows you to use [Vonage APIs](https://developer.vonage.com/api) in any JVM-based application.\nYou'll need to have [created a Vonage account](https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL\u0026utm_medium=github\u0026utm_campaign=java-client-library).\n\n* [Supported APIs](#supported-apis)\n* [Other SDKs](#other-sdks)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Usage](#usage)\n* [FAQ](#frequently-asked-questions)\n* [Contribute!](#contribute)\n\n## Supported APIs\n- [Account](https://developer.vonage.com/en/account/overview)\n- [Application](https://developer.vonage.com/en/application/overview)\n- [Conversion](https://developer.vonage.com/en/messaging/conversion-api/overview)\n- [Messages](https://developer.vonage.com/en/messages/overview)\n- [Number Insight](https://developer.vonage.com/en/number-insight/overview)\n- [Number Management](https://developer.vonage.com/en/numbers/overview)\n- [Number Verification](https://developer.vonage.com/en/number-verification/overview)\n- [Redact](https://developer.vonage.com/en/redact/overview)\n- [SIM Swap](https://developer.vonage.com/en/sim-swap/overview)\n- [SMS](https://developer.vonage.com/en/messaging/sms/overview)\n- [Subaccounts](https://developer.vonage.com/en/account/subaccounts/overview)\n- [Verify](https://developer.vonage.com/en/verify/overview)\n- [Video](https://developer.vonage.com/en/video/overview)\n- [Voice](https://developer.vonage.com/en/voice/voice-api/overview)\n\n## Other SDKs\n\nWe also provide server SDKs in other languages:\n- [Java](https://github.com/Vonage/vonage-java-sdk)\n- [.NET](https://github.com/Vonage/vonage-dotnet-sdk)\n- [PHP](https://github.com/Vonage/vonage-php-sdk)\n- [Python](https://github.com/Vonage/vonage-python-sdk)\n- [NodeJS](https://github.com/Vonage/vonage-node-sdk)\n- [Ruby](https://github.com/Vonage/vonage-ruby-sdk)\n\nWe also offer [client-side SDKs](https://developer.vonage.com/en/vonage-client-sdk/overview) for Android, iOS and JavaScript.\nSee all of our SDKs and integrations on the [Vonage Developer portal](https://developer.vonage.com/en/tools).\n\n## Installation\nReleases are published to [Maven Central](https://central.sonatype.com/artifact/com.vonage/server-sdk-kotlin).\nInstructions for your build system can be found in the snippets section.\nThey're also available from [here](https://search.maven.org/artifact/com.vonage/server-sdk-kotlin/2.1.1/jar).\nRelease notes for each version can be found in the [changelog](CHANGELOG.md).\n\nHere are the instructions for including the SDK in your project:\n\n### Gradle\nAdd the following to your `build.gradle` or `build.gradle.kts` file:\n\n```groovy\ndependencies {\n    implementation(\"com.vonage:server-sdk-kotlin:2.1.1\")\n}\n```\n\n### Maven\nAdd the following to the `\u003cdependencies\u003e` section of your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.vonage\u003c/groupId\u003e\n    \u003cartifactId\u003eserver-sdk-kotlin\u003c/artifactId\u003e\n    \u003cversion\u003e2.1.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Build It Yourself\n\n**Note**: We *strongly recommend* that you use a tool with dependency management,\nsuch as [Maven](https://maven.apache.org/) or [Gradle](https://gradle.org/).\n\nAlternatively you can clone the repo and build the JAR file yourself:\n\n```bash\ngit clone git@github.com:vonage/vonage-kotlin-sdk.git\nmvn install -P uberjar\n```\n\nThe `uberjar` profile will create a JAR file with all dependencies included in the `target`\ndirectory at the root of the repo. You can then include this in your project's classpath.\n\n## Configuration\nThe SDK requires very little configuration to get started.\n\n## Typical Instantiation\nFor default configuration, you just need to specify your Vonage account credentials using API key and secret,\nprivate key and application ID or both. For maximum compatibility with all APIs, it is recommended that you\nspecify both authentication methods, like so:\n\n```kotlin\nimport com.vonage.client.kt.Vonage\n\nval vonage = Vonage {\n    apiKey(API_KEY); apiSecret(API_SECRET)\n    applicationId(APPLICATION_ID)\n    privateKeyPath(PRIVATE_KEY_PATH)\n}\n```\n\nYou can also use environment variables for convenience, by setting the following:\n- `VONAGE_API_KEY` - Your account API key\n- `VONAGE_API_SECRET` - Your account API secret\n- `VONAGE_SIGNATURE_SECRET` - (Advanced, optional) Signature secret for signed requests when using SMS API\n- `VONAGE_APPLICATION_ID` - UUID of the Vonage application you want to use\n- `VONAGE_PRIVATE_KEY_PATH` - Absolute path to the private key file for the application\n\nand then instantiate the client with:\n\n```kotlin\nval vonage = Vonage { authFromEnv() }\n```\n\n### Customization\nYou can configure the base URI (for example, to do integration tests) and HTTP request timeout with `httpConfig`\nduring instantiation, like so:\n\n```kotlin\nval vonageClient = Vonage {\n    authFromEnv()\n    httpConfig {\n        baseUri(\"http://localhost:8976\")\n        timeoutMillis(15000)\n    }\n}\n```\n\n## Usage\nAs with our other SDKs, the architecture is based around the `Vonage` class, which defines the authentication\ncredentials and optional advanced settings for the HTTP client. The class has a field for each supported API,\nwhich returns an object containing methods available on that API. Where the SDK differs from other SDKs is that\nit uses a resource-based approach for CRUD operations, rather than a flat list of methods.\nThese are inner classes defined for each API resources and are always prefixed with `Existing` - for example,\n`ExistingCall`, `ExistingSession`, `ExistingApplication` etc. As a general rule, resources with unique identifiers\nhave a corresponding `Existing[Resource]` class which is used to perform operations on that resource, rather\nthan repeatedly passing the ID of that resource to methods on the parent class, as is the case in the Java SDK.\nThese resource classes are constructed from a method call in the top-level API class. So, for example, to work with\nan `ExistingSession`, you would do: `client.video.session(SESSION_ID)`, where `client` is an instance of `Vonage` and\n`SESSION_ID` is the unique identifier of the video session you want to work with.\n\n### Examples\nYou can find complete runnable code samples in the [Code Snippets repository](https://github.com/Vonage/vonage-kotlin-code-snippets),\nincluding [**a searchable list of snippets**](https://github.com/Vonage/vonage-kotlin-code-snippets/blob/main/SNIPPETS.md).\n\n### Documentation\n[![javadoc](https://javadoc.io/badge2/com.vonage/server-sdk-kotlin/javadoc.svg)](https://javadoc.io/doc/com.vonage/server-sdk-kotlin)\n\nThe SDK is fully documented with [KDocs](https://kotlinlang.org/docs/kotlin-doc.html), so you should have complete\ndocumentation from your IDE. You may need to click \"Download Sources\" in IntelliJ to get the full documentation.\nAlternatively, you can browse the documentation  using a service like [Javadoc.io](https://javadoc.io/doc/com.vonage/server-sdk-kotlin/2.1.1/index.html),\nwhich renders the documentation for you from [the artifacts on Maven Central](https://repo.maven.apache.org/maven2/com/vonage/server-sdk-kotlin/2.1.1/).\n\nFor help with any specific APIs, refer to the relevant documentation on our [developer portal](https://developer.vonage.com/en/documentation),\nusing the links provided in the [Supported APIs](#supported-apis) section. For completeness, you can also consult the\n[API specifications](https://developer.vonage.com/api) if you believe there are any discrepancies.\n\n### Custom Requests\nThe [Java SDK supports custom HTTP requests](https://github.com/Vonage/vonage-java-sdk?tab=readme-ov-file#custom-requests),\nwhich this SDK builds upon. This allows you to use unsupported APIs with your own data models so long as they implement\nthe `com.vonage.client.Jsonable` interface. Alternatively you can use `Map\u003cString, *\u003e` to represents the JSON structure.\nSee [Custom.kt](src/main/kotlin/com/vonage/client/kt/Custom.kt) documentation for more details.\nHere are some examples for creating an application, all of which are equivalent.\n\n#### Map request, Map response\n```kotlin\nval response: Map\u003cString, *\u003e = client.custom.post(\n        \"https://api.nexmo.com/v2/applications\",\n        mapOf(\"name\" to \"Demo Application\")\n)\n```\n\n#### Map request, Jsonable response\n```kotlin\nval response: Application = client.custom.post(\n        \"https://api.nexmo.com/v2/applications\",\n        mapOf(\"name\" to \"Demo Application\")\n)\n```\n\n#### Jsonable request, Map response\n```kotlin\nval response: Map\u003cString, *\u003e = client.custom.post(\n        \"https://api.nexmo.com/v2/applications\",\n        com.vonage.client.application.Application.builder()\n            .name(\"Demo Application\").build()\n)\n```\n\n#### Jsonable request, Jsonable response\n```kotlin\nval response: Application = client.custom.post(\n        \"https://api.nexmo.com/v2/applications\",\n        com.vonage.client.application.Application.builder()\n            .name(\"Demo Application\").build()\n)\n```\n\n#### Caveats\nThe same principle applies for all other supported HTTP methods. You can also use the `makeRequest` method for greater\nflexibility on the request and response types. In any case, you should **ALWAYS** use strong typing when assigning\nthe result of the call, otherwise the compiler will not be able to infer the correct type and you will get a runtime\nexception. If you'd like to ignore the result, use `Void` rather than `Unit` or `Any`. For example in `DELETE` requests:\n\n```kotlin\nclient.custom.delete\u003cVoid\u003e(\"https://api.nexmo.com/accounts/:api_key/secrets/:secret_id\")\n```\n\nYou can see valid usage examples in [CustomTest.kt](src/test/kotlin/com/vonage/client/kt/CustomTest.kt).\n\n## Frequently Asked Questions\n\n**Q: Why use this SDK instead of the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk)?**\n\n**A:** This Kotlin SDK is actually based on the Java SDK to improve the user experience in Kotlin. It adds\nsyntactic sugar, so you can avoid the cumbersome builder pattern in favour of a more idiomatic DSL-like\nsyntax, optional and named parameters with default values etc. whilst still reataining the strong typing\noffered by the Java SDK. Furthermore, you are more partially shielded from \"platform types\" (the `!`)\nso you have a better idea of what is and isn't nullable when creating requests. You can read more about the\ndifferences in [the v1.0.0 announcement blog post](https://developer.vonage.com/en/blog/announcing-the-vonage-kotlin-server-sdk).\n\n**Q: What is your policy on thread safety?**\n\n**A:** As with the Java Server SDK, only one thread should use the client at a time.\nIf you would like to use the SDK in a multithreaded environment, create a separate instance of\n`Vonage` for each thread, or use a ThreadLocal instance.\n\n**Q: I'm having issues with my project when including the SDK as a dependency. How can I troubleshoot this?**\n\n**A:** Please see [this blog post](https://developer.vonage.com/en/blog/one-simple-trick-for-resolving-java-runtime-dependency-issues).\nIn short, you may have conflicting dependency versions in your project which clash with this SDK's transitive dependencies.\n\n**Q: I'm encountering HTTP request issues, such as timeouts. How can I remedy or report this?**\n\n**A:** Since this library uses the Java SDK underneath, which in turn uses\n[Apache HTTP Client 4](https://hc.apache.org/httpcomponents-client-4.5.x/index.html), you may be able\nto use system properties to configure the client, or use this SDK's `httpConfig` method on the `Vonage` class\nfor more fine-grained control. If you believe there is an issue with the underlying client, please raise an issue\nwith a minimal reproducible example, including details of your environment (JVM runtime version, SDK version,\noperating system etc.) on the [Vonage Java SDK repository](https://github.com/Vonage/vonage-java-sdk/issues/new/choose).\n\n**Q: I'm not sure if my issue is with the SDK. How can I get help?**\n\n**A:** Please see our [support page](https://api.support.vonage.com/), including contact information.\n\n## Contribute!\n\n_We :heart: contributions to this library!_\n\nIt is a good idea to talk to us first if you plan to add any new functionality.\nOtherwise, [bug reports](https://github.com/Vonage/vonage-kotlin-sdk/issues),\n[bug fixes](https://github.com/Vonage/vonage-kotlin-sdk/pulls) and feedback on the\nlibrary are always appreciated. You can also contact us through the following channels:\n\n[![Email](https://img.shields.io/badge/Email-green?style=flat-square\u0026logo=gmail\u0026logoColor=FFFFFF\u0026labelColor=3A3B3C\u0026color=62F1CD)](mailto:community@vonage.com)\n[![Community Slack](https://img.shields.io/badge/Slack-4A154B?style=flat\u0026logo=slack\u0026logoColor=white)](https://developer.vonage.com/community/slack)\n[![Twitter](https://img.shields.io/badge/Twitter-000000?style=flat\u0026logo=x\u0026logoColor=white)](https://twitter.com/VonageDev)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvonage%2Fvonage-kotlin-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvonage%2Fvonage-kotlin-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvonage%2Fvonage-kotlin-sdk/lists"}