Release notes

Channel API version 2 has been finalized and is no longer in beta.

This also marks version 1 as deprecated. Please upgrade before January 15th 2026!

A beta of the Channel API version 2 had been released with release 20240229-1 and has since received several new features. In the release notes of release 20240229-1 more details can be found regarding the most important changes, which are mostly related to translations. If you currently do not make use of this feature, upgrading should be fairly straightforward.

The following changes should be made when upgrading to version 2:

• Change v1 in the API URL to v2.
• Update the OpenApi and AsyncApi specifications to their latest versions if you keep a local copy.
• The Context message of the Async API now supports "contentLocale" and "userLocale" to set or switch the locales.
• The Action message "set_translation" has been removed in favor of using the Context message from the previous item.
• The section translation in ConversationResponse has been removed in favor of a context section with details about the conversation's context (such as the current content locale and the user locale).
• The deprecated value features.sendTranscript.period has been removed from the getAccountConfig response.
• The value defaultLocale has been renamed to defaultUserLocale in the getAccountConfig response.

A few other changes and additions have been made as well. You can find them in the Channel API release notes.

When calling the getAccountConfig operation on the REST Api the properties "contentLocale" and "userLocale" are no longer required in the "context" object of the POST body. This allows clients to make use of the default content locale that is configured in the account.

A new Channel API version (v2) is introduced changing the way translation is handled. This version is a beta release and may change until it is finalized.

In v1 there's a locale and an optional translationLocale; the locale used to indicate the requested language of the conversation (meaning the locale the user interface is present in and the language the user and the bot/agent speak in). However when the user wants to talk in a different language an optional translationLocale can be set. This can be preset programmatically by the web/app client implementing the Channel API and/or it can be set and changed by the user by selecting a different language. Whenever a translationLocale was set the interface changed to that language and sentences from and to Seamly were automatically translated to enable the user to completely talk in his preferred language.

Channel API version 2 changes this concept to be more explicit about what languages to work with and as a result be less explicit about translating. We've introduced a contentLocale, which is effectively the old locale. It indicates the requested locale of the services Seamly communicates with; so the language of the bot or the agent(s). Besides that locale the translationLocale is replaced by a userLocale; indicating the locale the user wants to communicate in (so both the user interface labels and the text inputted and shown in the conversation should be presented in that language). The user can no longer explicitly start translating. Now he just indicates his preferred locale. In case the contentLocale and the userLocale end up differently, Seamly will automatically translate messages.

To sum up the changes that should be made when upgrading to the new v2:

• Change v1 in the API URL to v2.
• When calling the getAccountConfig operation on the REST Api the properties "contentLocale" and "userLocale" are now required in the "context" object of the POST body.
• The Context message of the Async API now support "contentLocale" and "userLocale" to set or switch the locales.
• The Action message "set_translation" has been removed in favor of using the Context message from the previous bullet.
• The section translation in ConversationResponse has been removed in favor of a context section with details about the conversation's context (such as the current content locale and the user locale).
• The deprecated value features.sendTranscript.period has been removed from the getAccountConfig response.
• The value defaultLocale has been renamed to defaultUserLocale in the getAccountConfig response.

For a complete set of updated documentation and API specifications have a look at https://developers.seamly.ai/server/apis/channel/index.html.

The properties translatedBody and translatedIntroduction as used in various messages used to contain both information about how the message was translated as well as the translated body (or introduction) itself. This has now been split up. The translatedBody and translatedIntroduction properties will now only contain the translated body or introduction and will have the same structure as body or introduction. A translation property has been added with meta information about the translation. In case you did not use the translation feature, the translatedBody and translatedIntroduction properties were already null, and you will only notice a new translation property (also with a null value).

The new structure has been implemented in the current version of the Channel API, and in a new version of the Web API (v3).