The Unblu web API and webhooks

The Unblu web API provides an HTTP-based interface that allows other systems to perform actions on the Unblu server. It supports many of the same actions accessible through the conventional user interfaces. This enables the integration of Unblu with third-party applications. For example, the web API can be used to implement the following functions:

A customer relationship management application that pre-initializes a conversation between each relationship manager and each of their customers, based on the relationships already recorded in a CRM system.
A call center application that dispatches incoming conversation requests to the appropriate agents connecting through Unblu.
An identity management system that automatically updates the status of agents and composition of teams based on changes to its database.

Unblu webhooks enable integration in the reverse direction. They allow you to configure the Unblu server to react to internal events by triggering an HTTP request to an external system. This functionality can be used to implement features such as:

An identity management system that’s updated whenever some agent user data is updated on Unblu.
A third-party dashboard system that’s updated whenever a conversation is started or ended.
An archive of conversations that’s updated every time a conversation ends.

The Unblu web API and webhooks are fully documented in the web API reference.

Web API

The Unblu web API exposes all the major entities that make up the internal data model of the Unblu server and offers methods to create, read, update and delete these entities via HTTP GET and POST requests. The entities are represented as a JSON objects in the bodies of HTTP requests and responses.

Examples of entity types include user, team, conversation and account. Definitions of all the entity types can be found under the heading Schemas in the Unblu web API reference.

The API methods (the actions that can be performed through the API) are organized into services. Most services are associated with a specific entity type. For example, the services associated with the above entity types are, respectively, users, teams, conversations and accounts. The services are documented under the heading Operations in the Unblu web API reference.

Under each service, several methods are typically available, for example, read, getAll, create, update and so forth. The API is designed to be as consistent as possible (the same methods are offered for the different entities), but for some entities more methods are available than for others.

Structure of a request

Calls to the Unblu web API are made by sending HTTP GET, POST, or DELETE requests to the Unblu server.

The following grammar shows the structure of the request URL:

<url> ::= <serverinfo>/<pathprefix>/rest/<version>/<service>/<action>[<params>]
<serverinfo> ::= https://[<username>:<password>@]<hostname>[:<port>]
<pathprefix> ::= app | unblu  // By default
<version> ::= v4 | v3 | v2  // Depends on server version
<service> ::= // See reference documentation
<action> ::= // See reference documentation
<params> ::= // Depends on action

The significant parts of the grammar are described below:

`<username>:<password>@`

Optional. If using basic authentication, the sender can embed the username and password in the URL itself. See Basic authentication below.

`<hostname>`

The name of the server to which you are directing your request. For on-premises installations this will, of course, depend on the location of your own installation. For the Unblu Cloud, this is always unblu.cloud.

`<port>`

Optional. An on-premises installation may require a port to be specified, depending on your set up. For the Unblu Cloud, there is no port number.

`<pathprefix>`

The path prefix indicating the entry path of the request. In most cases this is unblu or app, but see Entry path below.

`rest`

The keyword rest is used to route the request to the Unblu web API handler.

`<version>`

The version of the API that you wish to use. Possible values with Unblu 7 are v2 or v3. See API versioning below.

`<service>`

Unblu web API actions are organized into services. Each service corresponds to the type of internal entity being addressed, for example accounts, users, teams, etc.

`<action>`

The action to be performed on the entity indicated by the service, for example, create, delete, getAll, etc.

`<params>`

Optional. Parameters that modify or fully specify the action. These may be either URL query parameters (the ones after the ?) or additional elements in the path. See Parameters for details.

Authentication

To make most API calls, the client must be authenticated by the server to determine whether they have sufficient permissions to perform the operation. The permission level in Unblu is defined by the client’s role: ANONYMOUS_USER, WEB_USER, REGISTERED_USER, SUPERVISOR, ADMIN, TECHNICAL_ADMIN, or SUPER_ADMIN (see User roles). For each call, the required minimum role is noted as "required-role" in the Unblu web API reference section.

There are two mechanisms available for authentication with the Unblu web API: Basic Authentication and the Authenticator Service.

Basic authentication

Basic Authentication is the standard authentication mechanism supported natively by all browsers and built-in to HTTP. To authenticate using this method the client can either:

Add the header Authorization: Basic <credentials> to the request, where <credentials> is the base64 encoding of the user ID and password joined by a single colon, :.
Prepend <userid>:<password> to the URL, as mentioned above.

If you make calls to web API endpoints from the browser, you shouldn’t use basic authentication.

Authenticator service

The Authenticator Service of the Unblu web API provides an alternative mechanism for authentication. Under this method the client uses their user name and password to request an authentication token (which can then be used to login), or to login directly. In either case, a successful login will result in a response that includes a Set-Cookie header. The client can then cache the provided cookie and include it with any subsequent requests.

See Authenticator Service reference section.

Data and types

All data sent and received via the API is in JSON format. It’s recommended that you set the Content-Type and Accept headers accordingly on each request:

Content-Type: application/json
Accept: application/json

The types of JSON objects sent and received are all documented in Unblu web API Schemas.

Entry path

The <pathprefix> segment of the web API URL is used to indicate the entry path of the request.

Unblu has two entry paths that are relevant in the context of the web API: the INTERNAL and the PUBLIC entry paths. The default INTERNAL path prefix is app, and the default PUBLIC path prefix is unblu. You can change the path prefixes with the configuration properties com.unblu.identifier.internalPathPrefix and com.unblu.identifier.publicPathPrefix, respectively.

Just as every web API call has a minimum required role, so it has a minimum required entry path:

An API call with an INTERNAL entry path can perform both INTERNAL and PUBLIC operations. INTERNAL API calls must use the INTERNAL path prefix.
An API call with a PUBLIC entry path can only perform PUBLIC operations. PUBLIC API calls may use either the INTERNAL or PUBLIC path prefix.

Each call’s required entry path is documented in the Unblu web API reference.

Example

Suppose Unblu is running on example.com and the default path prefixes haven’t been changed. A call to perform the INTERNAL operation accounts/getAll on API v4 would look like this:

GET https://example.com/app/rest/v4/accounts/getAll

A call to perform the PUBLIC operation authenticator/login could look like this:

POST https://example.com/unblu/rest/v4/authenticator/login

{
    "username" : "...",
    "password" : "..."
}

Alternatively, it could look like this:

POST https://example.com/app/rest/v4/authenticator/login

{
    "username" : "...",
    "password" : "..."
}

In the Unblu Cloud, the entry path prefix configuration is fixed to the default values.

API versioning

The Unblu web API is versioned. As shown above in the request URL structure, the version indicator can be specified as part of the path. The current possible values are v4, v3, and v2.

A new API version is introduced as soon as a breaking change is introduced in the API. When a new API version is introduced, the old version is kept for the duration of one major version life cycle of the product to ensure compatibility with existing consumers of the old API.

Adding properties to the entities transferred by the Unblu web API is not considered a breaking change. It’s up to you to ensure that the application consuming the Unblu web API can deal with unknown properties. For example, if the application that consumes the web API was written using Jackson, you should set DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES to false.

Changes between server versions

The API version and the Unblu product version are related as follows:

Unblu 8 supports API v2, v3, and v4. v2 and v3 have been deprecated and are only provided for reasons of backward compatibility.
Unblu 7 supported API v2 and v3.
Unblu 6 supported API v1, v2 and v3.
Unblu 5 supported API v1 and v2.

Parameters

Different actions may require various parameters. Some are specified as query parameters:

GET <prefix>/rest/v4/accounts/getByName?name=<accountName>

Other calls use path parameters:

GET <prefix>/rest/v4/conversations/<conversationId>/getConversationFiles

{
    ...
}

Some calls use both:

GET <prefix>/rest/v4/accounts/<accountId>/getRecordedMinutes?fromTime=<time1>&toTime=<time2>

The parameters (if any) for each call are documented in the reference section for that call.

The `expand` parameter

Many API JSON objects contain related objects within their properties. When such a subobject is shown inside a top-level object, it’s usually represented by an ID.

The expand query parameter allows you to specify that one or more properties in an object are to be represented in fully expanded form, not just as IDs. Multiple properties can be specified by using a comma-delimited list. The general form of the expand query parameter is:

expand=<prop1>[,<prop2>,...,<propN>]

Only some properties in some objects are expandable. When a property is expandable, this is noted in the Unblu web API reference.

The expand parameter can be used in three ways:

On read
On write
For the special properties configuration, metadata, and text

Expand on read

On read, the expand parameter specifies which properties in the returned object are to be in expanded form. For example, the request

GET <prefix>/rest/v3/users/getByUsername?username=johndoe

would return something like

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

whereas the request

GET <prefix>/rest/v3/users/getByUsername?username=johndoe&expand=avatar

would return something like

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": {
        "$_type": "Avatar",
        "id": "VJPN47X8Q4iVxIqQtT8DAQ",
        "creationTimestamp": 1572517579000,
        "modificationTimestamp": 1572517579000,
        "accountId": "wZvcAnbBSpOps9oteH-Oxw",
        "imageZoomFactor": null,
        "imageXPositionRatio": 0.5,
        "imageYPositionRatio": 0.5,
        "imageRotationAngle": 0,
        "imageData": "data:image/png;base64,..."
    },
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

Note that in the first object, the avatar property is an ID whereas in the second example, avatar is expanded to be an object.

Expand on write

The expand parameter can also be used on write. Write requests typically include the data to be written as a JSON object in the request body. In this context, the expand parameter can be used to specify that one or more properties of that object will be submitted in fully expanded form.

For example, the request below will update the avatar of the user johndoe. Without the expand=avatar query parameter, the avatar subobject would be ignored.

POST <prefix>/rest/v3/users/update?expand=avatar

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": {
        "$_type": "Avatar",
        "id": "VJPN47X8Q4iVxIqQtT8DAQ",
        "creationTimestamp": 1572517579000,
        "modificationTimestamp": 1572517579000,
        "accountId": "wZvcAnbBSpOps9oteH-Oxw",
        "imageZoomFactor": null,
        "imageXPositionRatio": 0.5,
        "imageYPositionRatio": 0.5,
        "imageRotationAngle": 0,
        "imageData": "data:image/png;base64,..."
    },
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

Expand for special properties

The object types

accounts
users
teams
apikeys
namedareas

have one or more the following special properties:

configuration
metadata
text

When these properties are returned in an object, they normally have a value of null. This is the case for the configuration and metadata properties in the user object shown above.

However, if one of these properties is specified in the expand parameter then it’s returned in full.

Using `expand` with `SECRET` and `MULTILINE_SECRET` configuration properties

If you make a read request with the expand=configuration query parameter, and the entity you requested includes a configuration property of the type SECRET or MULTILINE_SECRET, the value of the configuration property will be masked. This is the case for configuration properties used to store keys, secrets, and passwords.

If you update an entity and you send the expand=configuration query parameter, you must include any masked configuration properties with the mask as their values. If you omit them, the configuration properties and their values will be deleted.

CRUD examples

In general the API supports full CRUD (Create, Read, Update, Delete) operations on all the entities that it exposes, subject to the permissions of the API client, of course.

The examples below use the users service as an example. Similar patterns apply to the other services.

Create

To create a new user, the client sends a POST with a request body holding the JSON object representing the new user entity:

POST <prefix>/rest/v3/accounts/create

{
    "$_type": null,                         // ignored
    "id": null,                             // has to be 'null' for create operation
    "creationTimestamp": null,              // ignored
    "modificationTimestamp": null,          // ignored
    "version": null,                        // ignored
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",  // optional
    "avatar": null,                         // optional
    "username": "johndoe",                  // required
    "email": "johndoe@example.com",         // required
    "phone": null,                          // optional
    "teamId": null,                         // optional
    "authorizationRole": "REGISTERED_USER", // required
    "displayName": "John Doe",              // optional
    "firstName": "John",                    // required
    "lastName": "Doe",                      // required
    "configuration": null,                  // only when 'expand' is used
    "metadata": null                        // only when 'expand' is used
    }

The above object depicts the full set of properties of the user entity. In this example, comments are included for explanation. In practice comments aren’t permitted. See User Type.

Notice that you don’t have to specify every property. Some are ignored and some are optional. That leaves the required properties username, email, authorizationRole, lastName and firstName.

On a successful creation, the server responds with the JSON object of the newly created user. The returned object will have filled in the internally generated properties $_type, id, creationTimestamp, modificationTimestamp and version.

Note also that if you want to include one of the expandable properties (avatar, configuration or metadata) inline in the submitted object then you must specify that property in the expand query parameter.

Similar details involving ignored, optional, required and expandable properties apply to the other entity types. This information is documented in the reference sections for those types.

Read

Reading is straightforward: A GET request is made and a JSON object is returned that represents the requested entity. See below for an example.

Update

Writing is done by issuing a POST request with the request body containing the data to be written. Keep in mind that the API doesn’t support patch syntax. In other words, you can’t specify only the properties that you want to change on a write. You must send the entire object even if you are making a change to only one property in the object.

The best way to perform a change to an entity, therefore, is:

Request the entity.
Take the returned JSON and alter the property or properties that you wish to change.
Send back the newly updated JSON using the appropriate update call for that entity type.

For example, let’s say you want to update the phone number of a registered user, you might perform the following series of calls:

Get the object

GET <prefix>/rest/v3/users/getByUsername?username=johndoe

returning

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": "+1 416 555 0105",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

Update the object

You change the phone property from +1 416 555 0105 to +1 416 555 0162, leaving everything else the same.

Send the updated object back

And now you send back the newly updated object as the body of the POST request:

POST <prefix>/rest/v3/users/update

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": "+1 416 555 0162",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

Receive confirmation of update

Assuming you have sufficient permissions to make the change, the server should respond with the updated object:

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581010,
    "version": 10,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "johndoe@example.com",
    "phone": "+1 416 555 0162",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

What has changed

Notice that the phone number has changed. It now reflects the value you submitted in the update call. However, you also see that some other properties don’t reflect the values that you submitted:

The modificationTimestamp is different. This makes sense since the entity has indeed been updated and therefore so has the timestamp.
The version has been incremented. This is a mechanism used to avoid concurrent update conflicts. On update the server checks if the version number on its copy of the entity is the same. If it is, that means no change took place in the meantime. The change is only applied if no conflict is detected. If you receive an "out of date" error, you have to re-request the original object and attempt the update again.

Delete

To delete an entity, send a DELETE request to the delete action of the corresponding service with a query parameter holding the ID of the entity. For example, to delete as user you would do the following:

DELETE <prefix>/rest/v3/users/delete?id=VPu6G3Y0QU6Y1nRn2nPzog

Searching

The Unblu web API provides a search endpoint for many of the entities it exposes. The endpoint expects a POST HTTP request with the search criteria specified in the request body.

The body of a search request consists of

An array of one or more search filters
An optional ordering of the search results
An optional offset
An optional limit

The offset and limit can be used to paginate search results.

The examples below give you an idea of how to use the search endpoints.

Refer to the Unblu web API reference for details about the schema for the body of each search request.

Below is a complete list of the operators you can use in the body of a search request.

CONTAINS: Checks if the value contains the string provided in the operator
EQUALS: Checks if the value is equal to the one provided in the operator
NOT_EQUALS: Checks if the value isn’t equal to the one provided in the operator
GREATER_THAN: Checks if the value is greater than the one provided in the operator
LOWER_THAN: Checks if the value is lower than the one provided in the operator
IN: Checks if the value is one of the ones provided in the operator
NOT_IN: Checks if the value isn’t one of the ones provided in the operator
IS_NULL: Checks if the value is null
IS_NOT_NULL: Checks if the value isn’t null
IN_RANGE: Checks if the value is in the range of the provided values. Results equal to the provided values are included.
NOT_IN_RANGE: Checks if the value is outside the range of the provided values. Results equal to the provided values aren’t included.

Which operators are available depends on the value of the field object they refer to. For example, it would make little sense to search for a string with the IN_RANGE operator. In fact, three operators are only available with the PARTICIPANT_PERSON_ID field of the body sent to the endpoint <serverUrl>/rest/v3/conversation/search:

ALL_OF: Checks if all the values are present in the value list provided by the operator
ANY_OF: Checks if any of the values is equal to any of the values in the list provided by the operator
ALL_EQUAL: Check if the lists are of the same length and contain the same values

Again, refer to the Unblu web API reference for details about the operators available for each search request.

Example 1: Webhook log error entries

Say you want to retrieve all entries in the webhook log that logged errors. To do so, you would call the webhookcalllogs/search endpoint:

Listing 1. Call to the webhookcalllogs/search endpoint to retrieve webhook log entries

POST <serverUrl>/rest/v3/webhookcalllogs/search

The body of the call would look like this:

Listing 2. HTTP request body to retrieve error entries in the webhook log

{
  "searchFilters": [
    {
      "field": "HTTP_RESPONSE_CODE",
      "operator": {
        "type": "NOT_IN_RANGE",
        "minimum": "200",
        "maximum": "299"
      }
    }
  ],
  "orderBy": [
    {
      "field": "ID",
      "order": "ASCENDING"
    }
  ],
  "offset": 0, (1)
  "limit": 10 (2)
}

1	With the `offset` set to `0`, the call will return the first results found.
2	With the `limit` set to `10`, the search will return at most 10 results. The response will tell you whether there are more results that match your search criteria.

The response to your request will look something like this:

Listing 3. Response to call to webhookcalllogs/search with more than 10 matches

{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": true, (1)
  "nextOffset": 10, (2)
  "items": [
    {
      "$_type": "WebhookCallLog",
      "id": "wxKdh3-DSJKvMrKz8PcXaw",
      "creationTimestamp": 1610725688976, (3)
      "modificationTimestamp": 161072568898,
      // ...
    },
    // ...
  ]
}

1	`"hasMoreItems": true` tells you that there are more than 10 results matching your search criteria.
2	`"nextOffset": 10` can be used to retrieve the next n results with a new request to the same endpoint.
3	Timestamps in search filters must be provided in the UTC timezone with milliseconds.

If there are 10 or fewer log entries matching you search criteria, the beginning of the response will look like this:

Listing 4. Response to call to webhookcalllogs/search with 10 matches or fewer

{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": false,
  "nextOffset": null,
  "items": [
    {
      "$_type": "WebhookCallLog"
      // ...
    }
  ]
}

If there are no results matching your criteria, "items" will be an empty array:

Listing 5. Response to call to webhookcalllogs/search with no matches

{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": false,
  "nextOffset": null,
  "items": []
}

Example 2: All webhook log entries of a given day

Including the following body in your HTTP request to the endpoint <serverUrl>/rest/v3/webhookcalllogs/search will return all webhook log entries for 1 April 2021:

Listing 6. HTTP request body to retrieve entries in the webhook log created on 1 April 2021

{
  "searchFilters": [
    {
      "field": "CREATION_TIMESTAMP",
      "operator": {
        "type": "IN_RANGE",
        "minimum": "1617228000000", (1)
        "maximum": "1617314399999" (2)
      }
    }
  ],
  "orderBy": [
    {
      "field": "CREATION_TIMESTAMP",
      "order": "ASCENDING" (3)
    }
  ]
}

1	2021-04-01 00:00:00.000
2	2021-04-01 23:59:59.999
3	The oldest log entry will be the first result.

Example 3: Group of users

The following body returns all users in the team "Support" or "Advisory" created in March 2021 whose email address is blank.

Listing 7. HTTP request

{
  "searchFilters":  [
      {
        "field": "EMAIL"
        "operator": {
          "type": "IS_NULL"
        }
      },
      {
        "field": "TEAM_ID"
        "operator": {
          "type": "IN",
          "values": [
            "v01giHTYRvmoWClaPu3brw", (1)
            "xN7MxXZVT4ComUoHSOuijA" (2)
          ]
        }
      },
      {
        "field": "CREATION_TIMESTAMP",
        "operator": {
          "type": "IN_RANGE",
          "minimum": "1614553200000",
          "maximum": "1617227999999"
        }
      }
  ],
  "orderBy": [
    {
      "field": "TEAM_ID",
      "order": "ASCENDING" (3)
    },
    {
      "field": "CREATION_TIMESTAMP",
      "order": "DESCENDING" (4)
    }
  ]
}

1	The team ID for the "Support" team
2	The team ID for the "Advisory" team
3	The results will be grouped by team ID first
4	Within each team, the most recently created users will be shown first

The HTTP request must be sent to the endpoint <serverUrl>/rest/v3/users/search.

Example 4: Conversation participation

If you send the HTTP request body below to the endpoint <serverUrl>/rest/v3/conversations/search, you can retrieve all of the conversations in March 2021 that two particular people participated in:

{
  "searchFilters": [
    {
      "field": "PARTICIPANT_PERSON_ID",
      "operator": {
        "type" : "ALL_OF",
        "values" : ["-kQOBaTdTZ20QRqrlwOvqQ", "sPNlrHvzRQSrUm3GxCOGVg"] (1)
      }
    },
    {
      "field": "CREATION_TIMESTAMP",
      "operator": {
        "type": "IN_RANGE",
        "minimum": "1614553200000", (2)
        "maximum": "1617227999999" (3)
      }
    }
  ]
}

1	The participant person IDs of the participants you are interested in.
2	2021-03-01 00:00:00.000
3	2021-03-31 23:59:59:999

Unblu web API Java library

Since the release of Unblu 7.18.2, the Java libraries containing the web API models and the Jersey client are available on Maven Central and GitHub. For more information, refer to the project’s page on GitHub.

Calling the Unblu web API from the browser

Most of your calls to web API endpoints will come from some backend system. You can, however, make calls from the browser, provided you satisfy two requirements:

Calls to web API endpoints from the browser are only permissible in the context of an authenticated user.
You should avoid using basic authentication for calls to web API endpoints from the browser.

Even if you meet these requirements, calling the web API may not be the appropriate way to achieve your goal:

If the action you want to trigger is related to the Floating or Embedded Visitor UI, use the Visitor JS API or Embedded JS API, respectively.
If you want to trigger an action that’s completely independent of the UI, use the web API.
Any action that should be executed before Unblu is initialized, or that’s completely independent of a local Unblu UI, can be accessed through a web API endpoint. Note, however, that exposing web API endpoints to visitors' browsers may pose a security risk and should only be considered if none of the alternative solutions work for your use case.

Webhooks

While the Unblu web API is useful for making changes to the Unblu server, it isn’t always ideal for cases where the external system must respond to events generated by the server, since this would involve constantly polling the server to check for changes. The Unblu webhooks provide an alternative mechanism for such use cases.

Webhooks are user-defined HTTP callbacks. They’re usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When the event occurs, the source site makes an HTTP request to the URL configured for the webhook. Users can configure webhooks in such a way that events on one site invoke behavior on another site.

The webhook mechanism in Unblu lets you register a URL of your choosing to be called by the Unblu server when a specific event occurs. The listening system can then be configured to respond appropriately. For example, an incoming message from a customer could trigger a notification being displayed in the relationship manager’s CRM interface.

Unblu webhooks can be configured either via the Account Configuration interface or the WebhookRegistrations service of the web API. The available events that can be listened for are documented in the Webhook Events section of the Unblu web API reference. They can be grouped according to the entities they’re related to:

Agent invitation and forwarding events

Events related to the creation, revocation and redemption of invitations sent to agents, or of forwarding of a conversation to an agent.

Conversation events

Events related to when conversations are created, updated, and ended, when canned responses are used in a conversation, and new messages sent to a conversation.

CRUD events

Events triggered when an entity is edited. The entities that can trigger such events are:

account
API key
domain
named area
person
team
user

PIN events

Events related to the creation, renewal, revocation, and redemption of PIN invitations.

Push notifications

Events triggered by new messages, messages being read, incoming calls, and calls being revoked.

Queue events

Events that are triggered by creating, revoking or redeeming assignment requests in the queue.

Visitor invitation events

Events related to creating, renewing, revoking, or redeeming invitations sent to visitors.