Contact usRequest a demo

This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Migrating from Unblu 5 to Unblu 6

In addition to the new features introduced with Unblu 6, there are several changes that you need to be aware of when migrating from Unblu 5 to Unblu 6.

Changes to the conversation model

New engagement type

The screen-sharing feature has introduced new engagement types: SCREEN_SHARING_REQUEST, SCREEN_SHARING_PIN, SCREEN_SHARING_INVITE. New default templates for those engagement types are created if the screen-sharing feature is activated.

New conversation states

In order to cover the new life cycle cases, new states are introduced for conversations:

  • QUEUED: Depending of the engagement type of the conversation, the conversation is put in the queued state when it is inside the queue.

  • UNASSIGNED: After there is no assignee of a conversation anymore, the conversation goes to unassigned state until a message from a visitor is written to start reboarding again.

  • REBOARDING: When a message is send to an unassigned conversation, the conversation first is put into the reboarding state as long as the person in the center of the conversation is doing the reboarding.

Locale of a conversation

With Unblu 5 the locale of a conversation was managed with a configuration setting at conversation level.

Now the locale is part of the conversation model.

For conversation created with the Web-API it is possible to set the locale directly in the request-body when a conversation is created. It can also later be changed with the Web-API call:

GET <prefix>/rest/v3/conversations/<conversationId>/setLocale?locale=<string>


For the "hidden participant" and the "external messenger" features, additional attributes were added to the ParticipantData:

  • hidden : <boolean>

  • connectedViaExternalMessenger : <boolean>

When you are creating conversation with the Web-API or adding a participant with the Web-API you can set the new attributes.


The current version with Unblu 6 is the Web API version v3. The older version (v1 and v2) are kept for backward-compatibility reasons, but they will be removed with a future major version (i.e. Unblu 7).


In order to make our API more consistent we have changed the name of some endpoints.

If you would like to fetch an entity by its id, you can call the read or the readMultiple endpoint (was called getByIds with v2).

When a method is returning exactly one entity, it starts with get (like getByName, getDefaultTemplateByEngagementType, getByKey…)

All the remaining find methods are replaced by search. Likewise the getAll methods are no longer necessary, because they are the same than search without any filters.

Mapping table:

Web-API v2 Web-API v3


















/rest/v3/cannedresponses/search with filters


/rest/v3/cannedresponses/search with filters






/rest/v3/cannedresponses/search with filters


/rest/v3/contacts/search with filters






/rest/v3/conversationhistory/search with filters




/rest/v3/conversations/search with filters
























/rest/v3/persons/search with filters






/rest/v3/users/search with filters












/rest/v3/webhookcalllogs/search with filters




/rest/v3/webhookregistrations/search with filters



At object level, we have also changed the following two attributes:

Web-API v2 Web-API v3





Configuration and text properties

As with every major version of Unblu, there are several changes to the configuration and text property schema.

Some keys were removed because they are no longer used. The possible values for some keys have changed (to reflect the changes made with Unblu 6). Some keys were renamed to be more consistent or easier to understand.

Please refer to the migration tool in the global configuration page to migrate your existing configuration files.