The agent embedded JS API allows you to embed Unblu agent side in your site with various web components instead of having e.g. a full Agent Desk as an iframe integrated.
To initialize the JS API see UnbluStaticAgentEmbeddedApi.
See UnbluAgentEmbeddedApi for the API instance which you retrieve after initialization.
The typical scenario for the using the Unblu Agent Embedded JS API is to extend and existing CRM system used by the agents. The idea is to integrate various aspects of the agents work seamlessly into the UI by building custom UIs based on the API or use provided components.
The UnbluStaticAgentEmbeddedApi provides APIs for the current agent himself and additional areas like inbox, conversations and notification.
For security reasons, the API of the web component can only ever do things the current agent has the right to do. For example, if a agent 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 current version of the Unblu Agent Embedded JS API expects that the user is already authenticated in some way against the backend server. Typically this is achieved by having some kind of SSO setup that ensures the authentication.
The Unblu Agent Embedded 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>/app/js-api/v8/agent-embedded/agent-embedded-js-api.min.js"></script>
<script>
//After the api script has been loaded it may be accessed in the global scope
window.unblu.agentEmbedded.api.configure({}); //Check AgentEmbeddedJsApiConfiguration for possible options
window.unblu.agentEmbedded.api.initialize().then(api => {
// use the api
});
</script>
The configuration parameter AgentEmbeddedJsApiConfiguration may is completely empty if the collaboration server is hosted behind the same domain where the unblu internal entry path is routed to the collaboration server.
For better integration with your IDE, the Unblu Agent Embedded JS API provides full type definitions for IDE features such as type safety, auto-completion (IntelliSense), and in-line documentation. The latest typedef file can be found in the Unblu public cloud:
https://unblu.cloud/app/js-api/v8/agent-embedded/agent-embedded-js-api.d.ts
The file is also included with your local Unblu server at the following location:
https://<unblu-server>/app/js-api/v8/agent-embedded/agent-embedded-js-api.d.ts
Now, WebStorm will offer you all the typedef features when you access an window.unblu.agentEmbedded.api.
typings folder to your JavaScript projecttypings folderNow, VSCode will provide you with all of the typedef features when you access an window.unblu.agentEmbedded.api.
Install the agent-embedded-js-api as a dependency using node package manager (npm).
In your project, execute the following command which will install the agent-embedded-js-api and add it to the package.json file as a dependency.
npm install --save @unblu/agent-embedded-js-api
The agent-embedded-js-api's version is synchronized with the Collaboration Server version.
To guarantee compatibility between the two, use the latest JS library version that is either equal to or smaller than the Collaboration Server version you are using.
Once installed you can use it like so:
import { api } from "@unblu/agent-embedded-js-api";
api.configure({})
const unbluApi = await api.initialize();
// use the API
The typedefs provided with the library will automatically be used by the local IDE (VSCode and WebStorm).
The Unblu Agent Embedded JS API provides two custom web components that can be placed at desired locations on your web page:
<unblu-embedded-app> — Displays the agent's embedded app (inbox by default, or a specific conversation when conversation-id is set).<unblu-conversation> — Displays a single conversation.These components are custom elements that use a shadow root for their content, so the styling within the web component can't be influenced by the website's styles. The size and positioning fully depends on the styles applied to the element by the website it is embedded into. The Unblu UI inside the custom element will always fill the whole content of the element independent of what size it is given.
Unblu provides a large list of configuration properties to integrate the web component's visual appearance with the website it is embedded into.
Important: A conversation can only be displayed in one component at a time. This applies across all component types — for example, if a conversation is already open inside the <unblu-embedded-app>, it cannot simultaneously be displayed in a <unblu-conversation> element, and vice versa. Make sure to close the conversation in one component before opening it in another.
The <unblu-embedded-app> component displays the agent's embedded app. By default it shows the inbox with the list of conversations; when a conversation-id attribute is set, it shows that conversation instead.
It supports opening conversations inline, listening for conversation changes, and registering interceptors to control open behavior.
<unblu-embedded-app></unblu-embedded-app>
See UnbluEmbeddedAppElement for the full API reference including attributes, events, and interceptors.
The <unblu-conversation> component displays a single conversation.
It supports setting the conversation via attribute or programmatically, and offers two access types: NORMAL (default) and GHOST.
<unblu-conversation conversation-id="<CONVERSATION-ID>"></unblu-conversation>
See UnbluConversationElement for the full API reference including attributes, events, and the openConversation method.
A typical integration pattern is to use the embedded app to list conversations and a separate conversation component to display the selected conversation:
<div style="display: flex; height: 600px">
<unblu-embedded-app id="my-embedded-app" style="display: block; width: 300px"></unblu-embedded-app>
<unblu-conversation id="my-conversation" style="display: block; flex: 1"></unblu-conversation>
</div>
<script>
const embeddedAppElement = document.getElementById('my-embedded-app');
const conversationElement = document.getElementById('my-conversation');
// Intercept conversation opening in the embedded app element and show it in the conversation component instead
embeddedAppElement.registerOpenConversationInterceptor(async (conversationId) => {
conversationElement.openConversation(conversationId, 'NORMAL');
return { action: 'DISCARD' }; // prevent the embedded app element from opening the conversation itself
});
</script>
You must configure and initialize the API before you can use it. See UnbluStaticAgentEmbeddedApi for more details.
If the Unblu Collaboration Server isn't located in the same domain as the website it is integrated into, the property AgentEmbeddedJsApiConfiguration.serverUrl must be set. If that isn't the case the configuration object can be empty.
Once the configuration is done it can be initialized.
Once the API has been initialized, the UnbluAgentEmbeddedApi will be returned. This is the central class for all high level API actions.
Important parts of it are
As many fields are properties, they directly throw errors of type UnbluApiError.
Some properties, however, trigger asynchronous actions, such as the initialization.
Where this is the case, we recommend you add a listener for the element's general error event.