Version 7.7.0 of the Vonage Java SDK is now available! This post describes the changes and what to expect in the near future.
Between March and August 2023, there have been seven releases of the Vonage Java SDK with over 35k lines of code changes since 2022's v7.1.1. As the semantic versioning scheme suggests, updating to the latest version should be backwards compatible. If you are using a version older than 7.0.0, refer to the v7.0.0 announcement post for a summary of changes. In this article, I hope to convince you to upgrade to the latest version of the SDK by summarising the updates since v7.0.0.
The major news for recent releases is the new APIs which have entered General Availability status and thus supported in our server SDKs. The following APIs are now fully supported in the Java SDK:
Verify v2: The new version of the Verify API adds extra channels, like WhatsApp (which can even be codeless), e-mail, and voice, as well as the traditional SMS for implementing multi-factor authentication in your application. Furthermore, verification workflows now have fallbacks, so you can add a timeout for each channel and try a different authentication method or phone number to contact as a backup.
Meetings: Low-code solution enabling you to dynamically create & manage meeting rooms. If you've ever used Vonage Business Cloud, this API allows you to programmatically provision and customise the VBC application for your organisation's needs.
Subaccounts: This API allows you to create and manage subaccounts, which can be useful for separating & tracking usage, billing, and assigned numbers according to the business unit or department. Note that this requires the feature to be enabled on your account.
Besides the new APIs, the most notable improvements are to the Messages API. Since 7.1.0, you can now use the Messages API Sandbox from the Java SDK, which enables you to test sending messages via WhatsApp, Viber, and Facebook Messenger without having to set up a business account with each of those platforms. New message types are now available:
These dedicated message types for WhatsApp make it easier to declaratively send locations, stickers, and products without having to construct a custom message type. Of course, the WhatsApp API is rich, and you can still use custom message types - for example, to send a contact.
You can now also include action buttons in your Viber text and image messages. Another notable addition is better support for inbound messages. The Messages API is not only for sending messages but also receiving them. These are done through webhooks. When you set up a listener for inbound messages, the data sent to your application server (as described in the API specification) can now be deserialised into a com.vonage.client.messages.InboundMessage object. The same is true for Message Status webhook, which can be deserialised via the com.vonage.client.messages.MessageStatus class. If you are already using webhooks for inspecting message statuses, you'll be pleased to know that deserialisation of timestamps has now been fixed.
The SDK's implementation of the Application API has been updated with improved documentation and missing fields added. In particular, the Voice capabilities have been updated with the conversations_ttl, signed_callbacks, and region fields. You can now set the connection_timeout and socket_timeout fields in Webhook - which now has a Builder for easier construction. The fallback_answer_url webhook type has also been added. For convenience, you can now easily list all applications using the new ApplicationClient::listAllApplications() method. For uniformity, any 4xx or 500 error responses from the API will now be wrapped in an ApplicationResponseException as with our other new APIs so that you can more easily inspect and investigate the details of the error.
Since users are tied to a particular application, we recently added user management endpoints to the Application API. The API itself is fairly straightforward, providing CRUD operations for managing users in your applications. Currently, these are used by the Conversation API. A user can have multiple contact channels associated with them - these are SMS, WhatsApp, Viber, Facebook Messenger, PSTN, SIP, VBC and Websocket. The Java SDK supports user management through the newly added com.vonage.client.users package.
The Voice API implementation (com.vonage.client.voice.*) received some notable changes too. This includes small fixes such as serialisation of a field (specifically, randomFromNumber in Call) and deserialisation of the app endpoint type.
The biggest change, however, is the move towards using the Builder pattern to construct objects. This is more aligned with how other APIs handle building request bodies. In particular, creating a call (via the VoiceClient#createCall(Call) method) should now be more straightforward and more declarative as the Call object now has a Builder you can use to set the properties of the call, rather than trying to remember which of the many constructors to use. It also simplifies adding new parameters and features for initial call properties. Another class that has received the Builder treatment is TalkPayload (as used in VoiceClient#startTalk). The same idea applies: rather than trying to find the method signature with the desired combination of parameters, you can now call VoiceClient#startTalk(String uuid, TalkPayload properties) using TalkPayload.builder() to define the properties of interest.
Consequently, the other variants of startTalk have been deprecated and will be removed in the next major release. Speaking of which, the setters on the Call class have also been deprecated in favour of using the Builder. To further tidy things up, some internal classes have been made package-private, and those that could potentially be used (CallModifier and ModifyCallPayload) have been deprecated.
Besides fixes and refactoring, there is new functionality as well. Most notable is Advanced Machine Detection (which can be set using the Call.Builder#advancedMachineDetection method). If specified, this feature overrides the standard machine detection feature. It is significantly more accurate at detecting voicemail and is a premium feature, so it will be chargeable per call. Another new feature is Premium Text-to-Speech, which can be selected by setting TalkPayload.Builder#premium(boolean) to true. This is also available on the TalkAction NCCO builder. These premium voices sound more natural and are chargeable based on the number of characters. Consult our developer documentation for a list of supported languages.
Finally, a couple of additions have been made which were missing from the API's implementation in the SDK. The ability to adjust the volume level of Text-to-Speech has been added to TalkPayload (available via the Builder). This can be set in a range from -1 to 1, with 0 being the default, -1 the quietest, and 1 being the loudest. The VBC endpoint has also been added to the SDK.
If you are upgrading from 7.0.0 or older, there have been some quality-of-life improvements to the classic Verify v1 API. Although we encourage users to migrate to the new Verify v2 API, the SDK still supports the classic Verify API. The latest version of the Java SDK is now more aligned with the specification. Notably, missing fields have been added, Bring Your Own PIN is now supported, and unused fields have been deprecated.
Of course, one of the benefits of upgrading to the latest version of the SDK is security. Although the Java SDK has relatively few dependencies, the main ones - Jackson and Apache HTTP Client - are particularly susceptible to CVEs, so keeping these up to date is important. Before every release of the Java SDK, every dependency version is checked to ensure it is the latest available minor or patch version. That being said, removing dependencies that are not required to reduce the risk of security vulnerabilities is also good practice.
In recent releases, javax.servlet and javax.xml.bind dependencies have been removed since the SDK did not need them. For compatibility, the jakarta.servlet dependency (which replaces javax.servlet) is optional but, in theory, should never be required. Some internal classes have an implicit dependency on javax.servlet.HttpServletRequest. However, these have been deprecated so that the dependency can be removed altogether. In particular, if you are using com.vonage.client.sms.callback.AbstractMOServlet, this has now been deprecated and will be removed in the next major version.
The next big change to the SDK will most likely be an upgrade from Apache HTTP Client 4 to 5. Before that can happen, some major internal refactoring is required. Currently, each subclient (i.e., the clients used for each API, e.g., VoiceClient) is composed of multiple endpoints. These are internal classes that handle the logic of sending your request to the correct API endpoint and returning the deserialised response. This logic is tightly coupled to the underlying HTTP client implementation, which makes migration to a different client very difficult. I am currently working on decoupling the implementation of these endpoints, which should also reduce boilerplate. Some progress has been made in v7.7.0, with several APIs migrated to this new approach. Hence, you may notice some new public-facing interfaces like Jsonable and QueryParamsRequest in some domain objects.
Once this work is done for all APIs supported by the SDK, migration will be much simpler as there will be a single place to change the underlying logic as opposed to every single API endpoint (and let's not forget tests!) in the SDK. We will then be in a position to migrate to Apache HttpClient 5. This will be good not only for security but also lays the groundwork for one of the most hotly requested features: non-blocking (asynchronous) requests.
That's all for now! If you do come across any issues or have suggestions for enhancements, feel free to raise an issue on GitHub, reach out to us on Twitter or drop by our Community Slack. I hope you have a great experience using the Vonage APIs with the latest version of the Java SDK!
){kind=small}
Sina is a Java Developer Advocate at Vonage. He comes from an academic background and is generally curious about anything related to cars, computers, programming, technology and human nature. In his spare time, he can be found walking or playing competitive video games.
