Unblu Agent Embedded JS API
    Preparing search index...

    Class UnbluEmbeddedAppElement

    To use the custom element, place a tag named "unblu-embedded-app" somewhere in the web page's body. By default, the element shows the agent's inbox. If a conversation-id attribute is set on the element, it shows that conversation instead.

    ...
    <body>
    ...
        <div>
            <unblu-embedded-app></unblu-embedded-app>
        </div>
    ...
    </body>
    ...

    The size and positioning depend entirely on the styles applied to it by the website that it's embedded in. The styling within the web component, on the other hand, aren't affected by the website's styles,because it uses a shadow root for its content. Unblu provides numerous configuration properties that let you customize the web component's appearance to suit your organizations requirements.

    The example above only adds the embedded app component to the DOM without initializing anything. To initialize and display content, you must create the UnbluAgentEmbeddedApi.

    The Unblu UI inside the custom element always fills the whole content of the element irrespective of the size it's given.

    Note: You can display any number of UnbluEmbeddedAppElement and UnbluConversationElement components on the same page, with the restriction that a conversation can only be displayed in one of them at a time, regardless of the component type. If a conversation is already displayed in one component, opening it in another component fails: that component shows a message dialog and reverts to its previous view.

    <!-- OK: each component displays a different conversation -->
    <unblu-embedded-app conversation-id="<CONVERSATION-A>"></unblu-embedded-app>
    <unblu-conversation conversation-id="<CONVERSATION-B>"></unblu-conversation>

    <!-- Not allowed: <CONVERSATION-A> is already displayed in the embedded app above.
         This component shows a message dialog and reverts to its previous view. -->
    <unblu-conversation conversation-id="<CONVERSATION-A>"></unblu-conversation>

    <unblu-embedded-app conversation-id="<CONVERSATION-ID>"></unblu-embedded-app>

    const embeddedApp = document.querySelector('unblu-embedded-app');
    embeddedApp.addEventListener('openConversationChanged', (event) => {
        console.log('Open conversation changed:', event.detail); // conversation ID or null
    });

    You can register an interceptor to control what happens when a conversation is opened from the embedded app's inbox view. This is useful when you want to open the conversation in a separate <unblu-conversation> component rather than within the embedded app itself.

    embeddedApp.registerOpenConversationInterceptor(async (conversationId) => {
        // return { action: 'OPEN' } to let the embedded app open the conversation
        // return { action: 'DISCARD' } to handle it yourself (e.g. open it in a separate <unblu-conversation> element)
        return { action: 'DISCARD' };
    });

    MDN Custom Element

    Hierarchy

    • HTMLElement
      • UnbluEmbeddedAppElement
    Index

    Constructors

    constructor

    Properties

    ATTR_CONVERSATION_ID

    Accessors

    conversationId

    Methods

    addEventListener copyToMessageInput getMessageInputAvailability registerOpenConversationInterceptor removeEventListener unregisterOpenConversationInterceptor

    Events

    MESSAGE_INPUT_AVAILABILITY_CHANGED OPEN_CONVERSATION_CHANGED

    Constructors

    Properties

    ATTR_CONVERSATION_ID: "conversation-id" = ...

    ID of the conversation currently open in the embedded app. If set, the conversation is opened in the embedded app.

    Accessors

    • get conversationId(): string

      Returns string

    • set conversationId(conversationId: string): void

      Opens the conversation with the given conversation ID.

      This can be set before Unblu is initialized. The conversation is then opened as soon as Unblu is initialized.

      If the conversation doesn't exist, or the user doesn't have permission to access it, a dialog is displayed with the appropriate error message. In such cases, the conversation ID is reset to null.

      Parameters

      • conversationId: string

        The id of the conversation to open

      Returns void

      UnbluEmbeddedAppElement.ATTR_CONVERSATION_ID to set this as an attribute

    Methods

    • Copies the given content (text and/or files) into the message input of the conversation currently open in the embedded app.

      The content is inserted into the current state of the message input (by default appended) so the agent can review and edit it before sending. Files are added to the pending files of the message input; the same validation as for manually selected files applies. If options.internal is set, the message input is also switched to the internal or public messaging mode. After copying, the message input receives the focus.

      If the message input isn't currently displayed, for example because a call is ongoing, the chat UI is opened automatically so the agent sees the copied content.

      Use getMessageInputAvailability to check upfront what content can be copied.

      Parameters

      Returns Promise<void>

      Resolves once the content has been copied into the message input

      UnbluApiError with type UnbluErrorType.ILLEGAL_STATE when the element isn't connected or the Agent Embedded JS API isn't initialized.

      UnbluApiError with type UnbluErrorType.INVALID_FUNCTION_ARGUMENTS if the given content or options are invalid.

      UnbluApiError if the requested content can't be copied based on the current availability, for example no conversation is open in the embedded app, the agent lacks the permission for the requested messaging mode, or the content contains files while the file upload isn't available.

    • Returns what content can currently be copied into the message input of the conversation open in the embedded app, based on the conversation permissions of the agent.

      All fields are false if no conversation is open in the embedded app or the Agent Embedded JS API isn't initialized.

      To get notified when the availability changes, listen to the MESSAGE_INPUT_AVAILABILITY_CHANGED event.

      Returns Promise<MessageInputAvailability>

      The availability of the message input for content copied via copyToMessageInput

    • Registers an open conversation interceptor that's triggered whenever a conversation should be opened from the embedded app's inbox view.

      Parameters

      • openConversationInterceptor: OpenConversationInterceptor

        The interceptor, which should resolve to an OpenConversationInterceptorResult with action OPEN if the embedded app UI should open the conversation or DISCARD if the embedded app will do nothing and the integrating page must handle the request.

        see #unregisterOpenConversationInterceptor to unregister the interceptor

      Returns Promise<void>

    • Unregisters an open conversation interceptor used previously

      Parameters

      • openConversationInterceptor: OpenConversationInterceptor

        The interceptor to unregister

        see #registerOpenConversationInterceptor to register a new interceptor

      Returns Promise<void>

    Events

    MESSAGE_INPUT_AVAILABILITY_CHANGED: "messageInputAvailabilityChanged" = ...

    Event emitted every time the availability of the message input changes, see getMessageInputAvailability.

    OPEN_CONVERSATION_CHANGED: "openConversationChanged" = ...

    Event emitted every time the currently open conversation changes in the embedded app.

    Settings

    Member Visibility

    On This Page

    This is a custom element which can be used to integrate the agent's embedded app (inbox and conversations) into a webpage at a specific location.AttributesEventsInterceptors
    Constructors
    Properties
    Accessors
    Methods
    Events