Table of contents Menu

Window API

The UI exposes an api on window.seamly to interact with running Seamly Web UI instances. The Window API 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',
})

Important If you want to use this at the start of a conversation, make sure to use setTopic first so you can prevent the default start flow from being triggered. In most cases the topic to accomplish this should be question, but you can contact us to verify what it should be in your specific setup.

setVisibility

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

The args value should be the required visibility state:

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

Alternatively you can specify if the browser should focus the text input field after opening the app by passing an object.

  • visibility (required), sets the visibility state.
  • setInputFocus (optional), a boolean value to set the focus of the text input field.
window.seamly.push({
    action: 'setVisibility',
    args: {
	  visibility: 'open',
	  setInputFocus: true,
    }
    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',
})

setContext

Allows setting the context of the conversation.

The args value should be an object specifying state (userLocale: 'nl-NL'). Setting userLocale to a locale different from the contentLocale will activate automatic translations if available in your account.

These rules apply when setting the locale:

  • They must be in the correct format (lowercase language code, uppercase country code, optional lowercase modifier).
  • They must be an exact match to a locale enabled in your account.
// Enabling translations with locale 'nl-NL'
window.seamly.push({
    action: 'setContext',
    args: {
        userLocale: 'nl-NL'
    },
    instance: 'targetInstance',
})

setTopic

Allows setting a new topic (or the initial topic if called before init).

The args value should be an object specifying both the topic name and a fallback message to be displayed in case the connected service is unable to handle the new topic.

window.seamly.push({
    action: 'setTopic',
    args: {
        name: 'login',
        fallbackMessage: "Sorry, I can't help you logging in right now. Please go to https://example.com/help/login",
    },
    instance: 'targetInstance',
})

There are two optional properties:

  • userTriggered: set to true if you want to start a conversation without showing the suggestions.
  • message: send additional user input along with the topic. Contact us to verify this property is supported and required for your account. In most cases a setTopic-call followed by a askText-call should be sufficient.
// Hide suggestions based on 'userTriggered' property.
window.seamly.push({
    action: 'setTopic',
    args: {
        name: 'login',
        fallbackMessage: "Sorry, I can't help you logging in right now. Please go to https://example.com/help/login",
        userTriggered: true,
    },
    instance: 'targetInstance',
})

// Start the chat with both a topic and a question from the user
window.seamly.push({
    action: 'setTopic',
    args: {
        name: 'question',
        fallbackMessage: 'Sorry, I was not able to process your question, please ask me again',
        message: 'Where can I find my invoices?',
    },
    instance: 'targetInstance',
})

Important If a setTopic call has been executed before the init call, it will ignore all properties except the topic name itself. It will effectively set the context.topic in configuration.

setTranslation (deprecated)

Important This is deprecated. To activate automatic translation of the conversation use setContext.

Allows setting the automatic translation of the conversation.

The args value should be an object specifying state (enabled: true/false) and the locale of the translations (locale: 'nl-NL'). locale is ignored when setting enabled: false.

These rules apply when setting the locale:

  • They must be in the correct format (lowercase language code, uppercase country code, optional lowercase modifier).
  • They must be an exact match to a locale enabled in your account.
// Enabling translations with locale 'nl-NL'
window.seamly.push({
    action: 'setTranslation',
    args: {
        enabled: true,
        locale: 'nl-NL'
    },
    instance: 'targetInstance',
})

// Disabling translations
window.seamly.push({
    action: 'setTranslation',
    args: {
        enabled: false,
    },
    instance: 'targetInstance',
})

sendCustomAction

Allows the transmission of custom actions to the Seamly server.

The args value should be an array where the first element must be a string and the second a object:

window.seamly.push({
    action: 'sendCustomAction',
    args: ['custom-event-name', { customEventKey: 'custom event value' }],
})

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

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.click_cta

The event will be executed every time the call to action inside a call to action message is clicked. Usually this is the main <a> element.

An object containing data from the call to action click event will be injected into the callback function

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

The ctaClickObj has the following structure:

{
    type: 'click_cta',
    originMessage: <system ID of the related CTA message>,
    link: {
        url: <href value of the clicked anchor element>,
    }
}

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:

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

The customActionObj has the following structure:

{
    type: 'custom',
    body: <object with the custom action data>
}

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
}

system.serviceChanged (deprecated)

The callback will be executed each time there is a change of service notification sent from the Seamly server.

The new service object will be injected into the callback:

serviceObj => {
    // Do something with the `serviceObj`.
}

The serviceObj has the following structure:

{
  occurredAt: <Timestap at which the event occurred>,
  service: <Name of the service>,
  serviceSessionId: <Current session ID of the service>,
  transactionId: <The ID of the service change event>,
  type: "service_changed"
}

system.userFirstResponse (deprecated)

The callback will be executed the first time a user responds in the conversation.

The new response object will be injected into the callback:

response => {
    // Do something with the `response`.
}

The responseObj has the following structure:

{
  occurredAt: <Timestap at which the event occurred>,
  responseType: <Type of the first user-initiated response>,
  text: <Value of the first user-initiated response>,
  type: "user_first_response"
}

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 App state object will be passed as the last argument to the callback.

(appState) => {
    // 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 App state object will be passed as the last argument to the callback.

(appState) => {
    // 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 (newVisibilityState, appState) as arguments.

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

See App status object for a description of the appState argument.

(visibilityState, appState) => {
    // 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 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
},

Data definitions

App state

The app state object is used to convey information about the running application instance and has the following structure:

{
  visibility: <VisibilityState>
  hasResponded: <Boolean>
  hasConversation: <Boolean>
  unreadMessageCount: <Number>
}
  • visibility: The current visibility state of the UI.
  • hasResponded: This boolean value will be set to true if the user has sent a response in the conversation.
  • hasConversation: This boolean value will be set to true if there is a started and connected conversation
  • unreadMessageCount: Number of unread messages.

Visibility state

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 Seamly UI instances.

Multiple instances

Some implementations will have an inline and a window 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.