Contact usRequest a demo

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 could 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

Introduction

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 in the Unblu web API Reference, under Schemas.

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 in the Unblu web API Reference, under Operations.

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> ::= v2 | v3  // 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 v3 would look like this:

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

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

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

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

Alternatively, it could look like this:

POST https://example.com/app/rest/v3/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. Current possible values are v2 and v3.

A new API version is introduced as soon as a breaking change is introduced into 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 5 supported API v1 and v2

  • Unblu 6 supported API v1, v2 and v3

  • Unblu 7 supports API v2 and v3. v1 has been removed.

Parameters

Depending on the action, various parameters may be required. In some cases these are to be specified as query parameters, as in

GET <prefix>/rest/v3/accounts/isAccountNameAvailable?name=<name>&accountId=<accountId>

or as additional path segments, as in

POST <prefix>/rest/v3/conversations/<conversationId>/setRecipient

{
    ...
}

The parameters for each call (if any) 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.

Starting with Unblu 7.1.0, if you include a property in the expand parameter that can’t be expanded, Unblu considers the request invalid and returns a 4xx response. Previously, Unblu simply ignored the invalid property.

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, such as com.unblu.storage.database.auth.password.

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.

Search filter operators

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.

See also

For more information on using webhooks with Unblu, see Webhooks technical details.

The web API and a complete list of webhooks are fully documented in the Unblu web API reference.

The same information is also served from your installed Unblu server and can be found at <unblu-server>/unblu/servicesdocumentation. This server-bundled documentation is, of course, aligned with the version of Unblu that you are running.

Additionally, the Unblu web API specification is available in the Open API format to allow for easier integration with third party software. The OpenAPI Specification is a standard way to describe REST web services in a machine-readable format (JSON or YAML).

The Unblu OpenAPI file can be used with other tools supporting this standard, to visualize the endpoints, to perform calls on the Unblu Server or to generate code that can be integrated into your calling application.

The Unblu Server provides one specification file per API version corresponding to the Unblu version that’s running. Those are available at this location:

  • <unblu-server>/rest/v2/openapi

  • <unblu-server>/rest/v3/openapi

The documents are dynamic and display only the endpoints available to the user currently logged in, depending on the entry path used. They’re also available either in YAML (default) or JSON format depending on the Accept header or an optional format query parameter (with value JSON or YAML).