Window API

The UI exposes an api on window.seamly that uses the Array replacement pattern to make sure the API can always be used.

Using the API

If you're confident/know for sure that the API has already been loaded and initialized you can call it by using the window.seamly.push(actionObject) method.

If you don't know whether or not the API has been initialized you can use the following pattern:

window.seamly = window.seamly || []
window.seamly.push(actionObject)

All actions that are pushed prior to API initialization will be run once the API has initialized. In all further examples we will omit the window.seamly = window.seamly || [] statement.

Actions

Actions are called by calling push(actionObject). The action object contains an action as String and an args array (for convenience you can skip the wrapping array if there is only one argument). An optional instance key is also available to target single instances (see Multiple instances for more information).

Available actions are:

init

initializes and renders the chat app with a configuration. The app can be re-initialized with the same configuration, or an adjusted configuration by calling init again.

The args value should be a configuration object that will be merged into the global configuration provided in the implementation:

window.seamly.push({
    action: 'init',
    args: {
        parentElement: document.getElementById('inlinebot'),
        layoutMode: 'window',
        namespace: 'window',
        ...more
    },
})

All configuration elements can be changed and overridden with this function.

As it creates a new instance, this function does not accept the instance argument.

The init action will destroy an existing instance existing on the given parentElement before creating the new instance.

If any other instances need to be cleaned up, please use the destroy action described below.

Important Use this action to start new instances. Without calling init nothing will be start/rendered.

destroy

Destroys all currently initialized instances.

window.seamly.push({
    action: 'destroy'
})

If targeted instances need to be destroyed, we set the instance property of the action object to the instance that needs to be destroyed:

window.seamly.push({
    action: 'destroy',
    instance: targetInstance
})

setVariables

Allows updating diverse variables after the app has been started.

The args value should be an object carrying the variables:

window.seamly.push({
    action: 'setVariables',
    args: {
        someVariable: 'someValue',
        someOtherVariable: 'someOtherValue'
    },
    instance: 'targetInstance',
})

askText

Sends a text string to the Seamly server as user input.

The args value should contain the string:

window.seamly.push({
    action: 'askText',
    args: 'Text to ask',
    instance: 'targetInstance',
})

setLocale

Allows updating the locale after the app has been started.

The args value should be an ISO locale code string:

window.seamly.push({
    action: 'setLocale',
    args: 'en',
    instance: 'targetInstance',
})

setVisibility

Allows updating the visibility state of the app after it has been started.

The following visibility states are available:

  • open - Opens a minimized or hidden chat window.
  • minimized - Minimizes an open or hidden chat window.
  • hidden - Hides an open or minimized chat window.

Please note: The minimized state should only be used with window and modal Seamly UI instances.

The args value should be the required visibility state:

window.seamly.push({
    action: 'setVisibility',
    args: 'open',
    instance: 'targetInstance',
})

getVisibility

Allows fetching the current visibility state.

A callback function should be provided as the args value. The current visibility state will be injected into this function when this action gets processed.

window.seamly.push({
    action: 'getVisibility',
    args: function(visibility) {
             // Use visibility value
          },
    instance: 'targetInstance',
})

sendCustomAction

Allows the transmission of custom actions to the Seamly server.

on

Subscribes a callback function to a specific event sent in the application.

The available events will be explained in the next section.

The args value should be an array with first element the event name and second element the callback function:

window.seamly.push({
    action: 'on',
    args: [
        'message',
        msg => {
        // Do something with the `msg` object
        },
    ],
    instance: 'targetInstance',
})

off

Unsubscribes from a previously subscribed event name.

The args value should be a previously subscribed event:

window.seamly.push({
    action: 'off',
    args: 'message',
    instance: 'targetInstance',
})

Events

When registering a callback function with the on event, you can listen to the events described here.

Sequence of events during intialisation

On initialisation a number of events will be broadcast, depending on the layoutMode and ui.visible. Any other events not described here are broadcast ad-hoc when the condition detailed for each is met.

For all cases the first event to be broadcast is the unreadMessageCount event, and it will always be 0 as an initialisation value.

Initial ui.visible is never sent.

inline

The inline variant is automatically started when the UI is rendered on the page.

Just before initiating the chat connection to the server, a ui.beforeStart event gets sent.

Once the chat is successfully started the ui.start event gets sent.

window and modal

The events sent when the chat starts are exactly the same as those described under inline. However, these layoutModes only start if the chat is either in the open state or it has previously been started and is minimized.

Event callbacks

action.pick_choice

The callback will be executed every time a choice prompt is selected by the user.

The full chosen choice action message will be injected into the callback:

choice => {
    // Do something with the `choice` object
}

action.navigate

The callback will be executed every time a link inside a chat bubble is clicked by the user.

The full navigate action message will be injected into the callback:

navObj => {
    // Do something with the `navigate` object
}

action.custom

Custom action objects will be injected into the callback as the related events occur. En example is the faqClick event that occurs when custom implementations implement the Faq component.

The full custom action message will be injected into the callback:

action => {
    // Do something with the `action` object
}

message

The callback will be executed for every message that is sent to the chat interface from the Seamly server or that is typed into the input and submitted by the user.

The full message object will be injected into the callback:

msg => {
    // Do something with the `msg` object
}

idleTimer.start

When the idle detach warning time starts the callback registered to this event will be called.

() => {
    // Do something when the timer starts
}

idleTimer.stop

When the idle detach warning time stops for any reason, be it from user activity or the timer running out, the callback registered to this event will be called.

() => {
    // Do something when the timer stops
}

idleTimer.selectContinue

When the user clicks the Continue conversation button when the idle detach warning displays, the callback registered to this event will be called.

() => {
    // Do something when the user clicks on continue conversation
}

idleTimer.selectEnd

When the user clicks the End conversation button when the idle detach warning displays, the callback registered to this event will be called.

() => {
    // Do something when the user clicks on end conversation
}

ui.beforeStart

The callback will be executed prior to any start event being issued. This also means when the connection is restarted after a communications failure.

The callback expects no arguments.

() => {
    // Run code before the start event
},

ui.start

The callback will be executed every time the application issues a start event. This also means when the connection is restarted after a communications failure.

The callback expects no arguments.

() => {
    // React to the start event
},

ui.inputFocus

The callback will be executed every time the input field receives focus.

The callback expects no arguments.

() => {
    // React to the inputFocus event
},

ui.visible

The callback will be executed every time the visibility state changes. The callback will receive the new visibility state as argument.

The visibility states with their meanings were defined in the previous section.

visibilityState => {
    // Do something with the visibility state
},

unreadMessageCount

Chat windows that are minimized can collect unread messages if they are pushed from the Seamly server during this time.

The callback will be called when the number of unread messages changes. It will also be called with zero when the minimized window is opened.

As described above, only window and modal chat windows can be minimized.

unreadMessages => {
    // Do something with the unread messages count
},

aria-live

This is a helper event to assist in testing screen reader functionality and should not be used in production implementations.

Seamly UI contains an ARIA live container to increase screen reader support. Due to the temporal nature of the textual content of this container it can be hard to test. Subscribing to this event will allow the user to receive all updates made to this container via the callback function.

msg => {
    // Do something with the aria-live message in your tests
},

Multiple instances

Some implementations will have an inline and a window (or a modal) implementation on the same page. In those cases you want to target specific instances. This can be done by adding the instance to the action object.

Important When no instance is specified the action will be performed on all instances, however, this should be avoided as race conditions can occur during the startup phase. It is better to redefine the action for each instance.

The instance name is derived directly from the namespace setting in the chat window configuration in the implementation.

For example:

const app = ChatUi(
    el,
    {
    namespace: 'inline',
    // other settings
    }
)

Can be targeted with:

window.seamly.push({
    action: "setVisibility",
    args: "open",
    instance: "inline"
})

If the implementation source code is unavailable, the instance name can also be derived by inspecting the browser storage used for the specific instance (either SessionStorage or Cookie depending on the chosen configuration). The related key exists as cvco.[instance name].connection.