Options
All
  • Public
  • Public/Protected
  • All
Menu

unblu-visitor-js-api

API reference for the unblu Visitor JS-API

The Visitor JS API is an optional add-on to the unblu visitor site integration. It allows JavaScript access to the local unblu integration.

Concepts

The Visitor JS API allows you to load, access and control Unblu inside your website. The API directly accesses and communicates with the loaded Unblu code. Any interaction with the API is reflected in the visitor's Unblu UI. For example, if a conversation is opened via the API, it will also be visible in the Unblu UI.

For security reasons, the JS API can only ever do things the current visitor has the right to do. For example, if a visitor is allowed to end a conversation, this may be done via the API. If not, an API call to end the conversation will fail with an error.

The Visitor JS API is meant to be used for actions directly connected to the current visitor and that visitor's usage of the Unblu UI. This includes things like automatically starting a conversation or starting a call within a conversation that the visitor is already part of.

For actions that require rights beyond those the local visitor has, or that should be independent of the visitor's UI, consider using the Unblu WebAPI either directly in JS or via custom REST services provided by your own server.

Integrating unblu on a website

In general, Unblu may be integrated into a website in three different ways:

  1. Snippet only: The Unblu snippet script is added to the head of the website. In this case this API is not present and can't be used.
  2. JS API only: The API script is added to the head of the website. When the API is initialized it loads the snippet and other parts of Unblu.
  3. Snippet and JS API: Both the snippet and the Unblu API are added to the header of the website. This is great if you always want to have Unblu loaded but don't always want to use the API. Here the API connects to a loaded Unblu integration.

Installation

The unblu Visitor JS API can either be included as a global script or can be loaded into a bundler.

Global scope

Simply add the script tag to the head of your website.

<script src="<unblu-server>/unblu/js-api/v2/visitor/visitor-api.min.js"></script>
<script>
    //After the api script has been loaded it may be accessed in the global scope
    window.unblu.api.initialize().then(api -> {
        // use the api
    });
</script>

Adding type definitions to the IDE

For better integration in the IDE the unblu visitor api provides full type definitions like type safety, auto-completion (IntelliSense) and in-line documentation. The latest typedef file can be found in the public cloud under:

https://unblu.cloud/unblu/js-api/v2/visitor/visitor-api.d.ts

or from your local server at:

https://<unblu-server>/unblu/js-api/v2/visitor/visitor-api.d.ts

IDEA WebStorm
  1. Download the typedefs and store them locally
  2. Open the WebStorm Project and go to: Preferences -> Languages & Frameworks -> JavaScript -> Libraries
  3. Press Add...
  4. In the dialog, give the library a name e.g. unblu-visitor-api
  5. Add the downloaded typedefs as file using the (+) button.
  6. WebStorm will now give you all the typedef features when accessing window.unblu.api
Microsoft VSCode
  1. Download the typedefs and store them locally
  2. Add a new folder typings to you JavaScript project
  3. Copy the downloaded typedefs to the folder.
  4. VSCode will now give you all the typedef features when accessing window.unblu.api

Using the API with a Bundler like webpack

Commonjs (require)

Download the the commonjs lib at:

https://<unblu-server>/unblu/js-api/v2/visitor/visitor-api-lib.zip

extract the zip file in your local JavaScript project e.g. to <local-project>/lib/unblu-visitor-js-api In your code use it like so:

const unblu = require('lib/unblu-visitor-api');

unblu.api.initialize().then(api => {
   // use api
});

The typedefs provided with the library will automatically used by the local IDE (VSCode and WebStorm)

ES Modules (import)

Download the the ES modules lib at:

https://<unblu-server>/unblu/js-api/v2/visitor/visitor-api-lib-esm.zip

extract the zip file in your local JavaScript project e.g. to <local-project>/lib/unblu-visitor-js-api In your code use it like so:

import {api} from "lib/unblu-visitor-api";

api.initialize().then(api => {
    // use the api
});

The typedefs provided with the library will automatically used by the local IDE (VSCode and WebStorm)

Requirements

ES6 Promise

The Unblu JS-API uses ES6 Promises for all asynchronous tasks. ES6 Promises are supported by all Major Browsers except for IE11. If you plan on integrating the unblu JS-API, a polyfill for promises must be provided before the API is loaded. Unblu will work with any ES6 Promise compatible polyfill like promise-polyfill or es6-promise. Example:

<script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>
<script src="https://unblu.cloud/unblu/js-api/v2/visitor/visitor-api.min.js"></script>
<script>
    // use unblu JS-API here
</script>

Usage

Config & Initialization

Before the API can be used it must be configured (if the snippet hasn't been added to the page) and initialized. See UnbluStaticApi for more details.

Central classes

Once the api as been initialized the UnbluApi will be returned which is the central class for all high level API actions. Some methods of the UnbluApi resolve to a Conversation which gives access to the functionality specific to this conversation.

Keep in mind however, that a conversation can only be accessed as long, as it is also displayed in the UI. If the visitor decides to navigate out of the conversation, it won't be accessible by the API anymore, until it is re-opened either via API or manually by the visitor.

Error Handling

Whenever an API-call fails, the Promise returned by the API will be rejected with a UnbluApiError. Use the error's UnbluApiError.type and UnbluApiError.detail for more information on the cause of it.