Unblu Agent Embedded JS API
    Preparing search index...

    Class UnbluConversationElement

    To use the custom element, place a tag named "unblu-conversation" somewhere in the web page's body.

    ...
    <body>
    ...
        <div>
            <unblu-conversation conversation-id="qK6GhE9fRneqrEGqjeuiTg"></unblu-conversation>
        </div>
    ...
    </body>
    ...

    The size and positioning of the element 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 organization's requirements.

    The example above only adds the conversation component to the DOM without initializing anything. To initialize and display content, you must create the UnbluAgentEmbeddedApi. Until then, the element doesn't display any content other than content the webpage itself adds inside the tag, which renders as regular DOM children.

    Once the Agent Embedded JS API is initialized and until a conversation is opened, the element displays the content provided via the no-conversation slot, or the standard loader if the slot has no content.

    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-conversation conversation-id="<CONVERSATION-ID>" access-type="GHOST"></unblu-conversation>

    Custom content while no conversation is open

    To customize what's displayed while no conversation is open, provide content via the no-conversation slot. If the slot has no content, Unblu displays the standard loader instead.

    <unblu-conversation>
        <div slot="no-conversation">Select a conversation to get started</div>
    </unblu-conversation>

    To change the conversation and access type together, use the openConversation method. This applies both values atomically without batching delay:

    const conversationElement = document.querySelector('unblu-conversation');
    const conversation = conversationElement.openConversation('<CONVERSATION-ID>', 'NORMAL');

    The conversation property gives access to the Conversation API object of the currently open conversation.

    When setting both conversation-id and access-type attributes (or properties) separately, changes are automatically batched within the same microtask to avoid unnecessary reconnections.

    const conversationElement = document.querySelector('unblu-conversation');
    conversationElement.addEventListener('conversationChanged', (event) => {
        console.log('Conversation changed:', event.detail); // conversation ID or null
    });
    conversationElement.addEventListener('accessTypeChanged', (event) => {
        console.log('Access type changed:', event.detail); // 'NORMAL' or 'GHOST'
    });

    MDN Custom Element

    Hierarchy

    • HTMLElement
      • UnbluConversationElement
    Index

    Constructors

    constructor

    Properties

    ATTR_ACCESS_TYPE ATTR_CONVERSATION_ID SLOT_NO_CONVERSATION

    Accessors

    accessType conversation conversationId

    Methods

    addEventListener copyToMessageInput getMessageInputAvailability openConversation removeEventListener

    Events

    ACCESS_TYPE_CHANGED CONVERSATION_CHANGED MESSAGE_INPUT_AVAILABILITY_CHANGED

    Constructors

    Properties

    ATTR_ACCESS_TYPE: "access-type" = ...

    Access type for opening the conversation.

    Defaults to ConversationAccessType.NORMAL if not set.

    ATTR_CONVERSATION_ID: "conversation-id" = ...

    ID of the conversation to open in the component

    SLOT_NO_CONVERSATION: "no-conversation" = ...

    Name of the slot used to provide custom content displayed when no conversation is open.

    If the slot has no content, Unblu displays the standard loader instead.

    Accessors

    • get conversation(): Conversation

      The Conversation API object for the currently open conversation.

      Returns null if no conversation is open or the agent JS API isn't initialized yet.

      The returned instance is destroyed and replaced when the open conversation or the access type changes.

      Returns Conversation

    • get conversationId(): string

      Returns string

    • set conversationId(conversationId: string): void

      The ID of the conversation to display.

      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.

      Note: When setting both conversationId and accessType, changes are batched and applied together in a single update to avoid unnecessary reconnections. For explicit control, use openConversation instead.

      Parameters

      • conversationId: string

        The id of the conversation to open

      Returns void

      UnbluConversationElement.ATTR_CONVERSATION_ID to set this as an attribute

    Methods

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

      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 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 element, 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 open conversation, based on the conversation permissions of the agent.

      All fields are false if no conversation is open in the element, the conversation is displayed as ghost, 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

    • Opens a conversation with the given ID and access type.

      This is the recommended way to programmatically change the conversation and access type together, as it applies both values in a single update without batching delay.

      The method can be called before the Agent Embedded JS API 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.

      The previously opened conversation will be closed and disconnected.

      Parameters

      • conversationId: string

        The ID of the conversation to open, or null to close the current conversation without opening another conversation

      • accessType: ConversationAccessType = ConversationAccessType.NORMAL

        The access type for the conversation. Defaults to ConversationAccessType.NORMAL

      Returns Promise<Conversation>

      The Conversation API object for the conversation being opened, or null if conversationId is null or the agent JS API isn't initialized yet

    Events

    ACCESS_TYPE_CHANGED: "accessTypeChanged" = ...

    Event emitted every time the conversation access type changes.

    CONVERSATION_CHANGED: "conversationChanged" = ...

    Event emitted every time the currently open conversation changes.

    MESSAGE_INPUT_AVAILABILITY_CHANGED: "messageInputAvailabilityChanged" = ...

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

    Settings

    Member Visibility

    On This Page

    This is a custom element which can be used to integrate a single conversation into a webpage at a specific location.AttributesCustom content while no conversation is openProgrammatic controlEvents
    Constructors
    Properties
    Accessors
    Methods
    Events