The Visitor JS API is an optional add-on to the unblu visitor site integration. It allows JavaScript access to the local unblu integration.
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.
In general, Unblu may be integrated into a website in three different ways:
The unblu Visitor JS API can either be included as a global script or can be loaded into a bundler.
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>
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
window.unblu.api
typings
to you JavaScript projectwindow.unblu.api
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)
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)
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>
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.
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.
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.