This class represents the initialized Unblu Visitor JS API.

There is only ever one instance of this api which can be retrieved via unblu.api.initialize(). See UnbluStaticApi for more details on configuring and initializing the UnbluApi.

The API connects to the integrated version of Unblu. All actions performed via the UnbluApi are executed in the name of and with the rights of current visitor and may have direct effect on the displayed Unblu UI.

For example if a conversation is started from the UnbluApi, the Unblu UI will navigate to it. If a conversation is closed via the API, it will also be closed on the Unblu UI of the visitor. For more information on UI side effects please check the documentation for each method call.

For programmatic administrator access and configuration of Unblu please use the Unblu WebAPI.

Hierarchy

  • UnbluApi

Implements

  • InitializedUnbluApi

Properties

Access the UI functionality over the UI property.

Methods

  • De-initializes the API. It will destroy the UI, all connections and will release all resources (as far as it is technically possible).

    Afterwards the API can be initialized again via [window.unblu.api.initialize()]UnbluStaticApi.initialize

    Returns Promise<void>

  • Returns the currently active conversation or null if no conversation is active.

    NOTE: calling this method twice while the same conversation is active, will result in two individual conversation API instances being returned. destroying one of them will not cause the other one to also be destroyed. If however the active conversation is closed, all returned Conversation instances will be destroyed.

    Returns Promise<Conversation>

    A promise that either resolves to the currently active conversation or null if no conversation is open.

  • Returns the current availability state for the current named area and language.

    Returns Promise<AgentAvailabilityState>

    Promise that resolves to the current availability state.

    See

    isAgentAvailable for a simpler check.

  • Returns all conversations of the current visitor. If no conversation is present, an empty array is returned.

    Returns Promise<ConversationInfo[]>

    A promise that resolves to an array of [ConversationInfo]ConversationInfo.

  • Returns the number of unread messages.

    Returns Promise<number>

    A promise that resolves to the current number of unread messages.

  • Returns information about the visitor.

    Returns Promise<PersonInfo>

    A promise that resolves to the current visitors person info.

  • Checks if the current visitor is authenticated.

    Returns Promise<boolean>

    A promise that resolves to a boolean if the visitor is authenticated

  • Returns Boolean

  • Joins an existing conversation with a given PIN.

    NOTE: calling this method will NOT automatically open the Unblu UI if it is collapsed. Use [ui.openIndividualUi()]UnbluUiApi.openIndividualUi if this is needed.

    Parameters

    • pin: string

      The PIN retrieved from the Unblu Agent Desk.

    • Optional visitorName: string

      The name the local visitor should have. This is only taken into account if the visitor is not already authenticated.

    Returns Promise<Conversation>

    A promise that resolves to the conversation object giving API access to the joined conversation.

  • Logs the current visitor in using the authenticator/loginWithSecureToken web API endpoint. Depending on the configuration, existing conversation may will be transferred to the authenticated user.

    Parameters

    • accessToken: string

      The access token (JWT) to authenticate the visitor with

    Returns Promise<void>

    A promise that resolves empty if the login succeeds or is rejected if it fails

  • Logs the visitor out. The user will not have access to conversations from the authenticated visitor he was before anymore. He needs to be authenticated again for that.

    Returns Promise<void>

    A promise that resolves empty when the logout succeeds or is rejected if it fails

  • Removes a previously registered listener

    Parameters

    • event: MetaEventType | AgentAvailabilityEventType | GeneralEventType

      The event to unregister from.

    • listener: Listener

      The listener to remove.

    Returns boolean

  • Registers an event listener for the given event.

    Parameters

    • event: "activeConversationChange"

      The activeConversationChange event.

    • listener: ConversationChangeListener

      The listener to be called.

    Returns void

  • Registers an event listener for the given event.

    Parameters

    Returns void

  • Registers an event listener for the given event.

    Parameters

    Returns void

  • Registers an event listener for the given event.

    Parameters

    • event: "personChange"

      The personChange event.

    • listener: PersonChangeListener

      The listener to be called.

    Returns void

  • Registers an event listener for the given event.

    Parameters

    • event: "personActivity"

      The personActivity event.

    • listener: PersonActivityListener

      The listener to be called.

    Returns void

  • Registers an event listener for the given event.

    Parameters

    Returns void

  • Registers an event listener for the given event.

    Parameters

    Returns void

  • Registers an event listener for the given event.

    Parameters

    • event: "deinitializing"

      The deinitializing event.

    • listener: DeinitializationListener

      The listener to be called.

    Returns void

  • Registers an event listener for the given event.

    Parameters

    • event: "deinitialized"

      The deinitialized event.

    • listener: DeinitializationListener

      The listener to be called.

    Returns void

  • Opens the existing conversation with the given conversation ID.

    NOTE: calling this method will NOT automatically open the Unblu UI if it is collapsed. Use [ui.openIndividualUi()]UnbluUiApi.openIndividualUi if this is needed.

    Parameters

    • conversationId: string

      The id of the conversation to be opened.

    Returns Promise<Conversation>

    A promise that resolves to the conversation object giving API access to the opened conversation.

  • Set a custom interceptor which will be triggered when a new conversation is started (initiated from UI or JavaScript).

    Parameters

    Returns Promise<void>

    A promise that resolves when the interceptor is successfully applied and active.

  • Sets the current visitor's nickname. This could be set before or during a conversation.

    Parameters

    • nickname: string

    Returns Promise<void>

    A promise that resolves empty when the operation is done

  • Starts a new Conversation and places it into the inbound conversation queue.

    Starting a new conversation involves an agent availability check. For ConversationType.OFFLINE_CHAT_REQUEST conversations, the check proceeds as follows:

    • If an agent is available, the conversation type will be changed to ConversationType.CHAT_REQUEST.
    • If no agents are available, it will start an offline conversation provided offline chat requests are enabled in the Unblu server's configuration.
    • if offline chat requests aren't enabled, the request will be rejected.

    For all online conversation types, the check works as follows:

    • If an agent is available, the conversation will be started.
    • If no agents are available, the request will be rejected.

    You should therefore always check agent availability before starting a new conversation. If no agents are available, only start conversations of the type ConversationType.OFFLINE_CHAT_REQUEST.

    NOTE: calling this method will NOT automatically open the Unblu UI if it is collapsed. Use [ui.openIndividualUi()]UnbluUiApi.openIndividualUi if this is needed.

    Parameters

    • type: ConversationType

      The conversation type that shall be started.

    • Optional visitorName: string

      The name the local visitor should have. This is only taken into account if the visitor is not already authenticated.

    • Optional visitorData: string

      Custom data for the visitor in any format. NOTE: The data which is passed here could be used in [NewConversationCallback]NewConversationInterceptor

    • Optional recipient: ConversationRecipient

      The team or agent recipient of the conversation. This will overwrite any named area that might be set for this web page. NOTE: The data which is passed here could be used in [NewConversationCallback]NewConversationInterceptor

    Returns Promise<Conversation>

    A promise that resolves to the conversation object giving API access to the started conversation.

Events

ACTIVE_CONVERSATION_CHANGE: "activeConversationChange" = 'activeConversationChange'

Event emitted every time the active conversation changes.

This may happen due to a UI-navigation or an API-call.

activeConversationChange

See

AGENT_AVAILABILITY_CHANGE: "availabilityChange" = 'availabilityChange'

Event emitted every time the agent availability state changes for the current named area and locale.

availabilityChange

See

AGENT_AVAILABLE_CHANGE: "availableChange" = 'availableChange'

Event emitted every time the agent availability changes for the current named area and locale.

availableChange

See

CONVERSATIONS_CHANGE: "conversationsChange" = 'conversationsChange'

Event emitted every time one of the conversations accessible to the current user changes or one is added or removed.

conversationsChanged

See

DEINITIALIZED: "deinitialized" = 'deinitialized'

Event emitted when this instance got de-initialized and has to be initialized again.

deinitialized

See

  • on for listener registration
  • DeinitializationListener
DEINITIALIZING: "deinitializing" = 'deinitializing'

Event emitted when this instance gets de-initialized and is not usable at the time until it fully got de-initialized.

deinitializing

See

  • on for listener registration
  • DeinitializationListener
NOTIFICATION_COUNT_CHANGE: "notificationCountChange" = 'notificationCountChange'

Event emitted every time the notification count (unread messages) changes.

notificationCountChange

See

PERSON_ACTIVITY: "personActivity" = 'personActivity'

Event emitted every time the local person has some activity inside Unblu. This may be i.e. an interaction with the chat, a call, opening a conversation or interacting with a co-browsing layer.

The event can be used to reset the logout timer inside an authenticated area, for example.

The configuration property com.unblu.conversation.activity.activityCategoriesToTrack specifies which categories of activity trigger the event.

personActivity

See

PERSON_CHANGE: "personChange" = 'personChange'

Event emitted every time the local person changes. This may be i.e. due to the person setting its name.

personChange

See