Configuration

Below is a description of all Seamly initialization configuration options.

Important Not all of these configuration options are exposed in all implementations.

Example

Below is an example configuration to give a general overview of the config structure.

{
  parentElement: document.getElementById("demo"),
  namespace: 'demo',
  showDisclaimer: false,
  showSuggestions: true,
  continueChat: true,
  preChat: {
    enterDelay: 250,
    exitAfter: 5000
  },
  layoutMode: 'inline',
  connectWhenInView: true,
  api: {
    key: '....',
  },
  context: {
    channelName: 'web',
    userLocale: 'nl-informal',
    contentLocale: 'en-GB',
  },
  messages: {
    agent: {
      showName: true,
    },
    user: {
      showName: true,
    },
    timeIndicator: {
      enabled: true,
      threshold: 3600000,
    },
  },
}

Global

`parentElement`

The HTML element on the page where the chat window should be injected into.

`namespace`

Unique name to identify this session with (needed if you have multiple instances on one page).

`customComponents`

This setting enables overriding or adding components to Seamly UI. More information about the supported components can be found in the custom components documentation.

`view`

A Preact component that replaces the standard Seamly UI view.

`messages`

A JSON object showing mappings between custom events and the components that should be used to render them.

Disclaimer

`showDisclaimer`

Indicates whether the privacy disclaimer should be rendered. If the setting is absent the disclaimer will not be rendered.

Suggestions

`showSuggestions`

Boolean value, defaults to true if not given, that controls display of the suggestions in Web UI. If set to false the suggestions will not be shown regardless of values being populated from the server.

Pre-chat messages

`continueChat`

Boolean value or an object (default) with the following shape:

{
  enterDelay: 0, // Delays entering in ms
  exitAfter: 2000 // Automatically disappear after ms
}

If set to true, the continue pre-chat messages will be shown immediately and not disappear.
If set to false the continue pre-chat messages will not be shown regardless of values being populated from the server.

`preChat`

Boolean value or an object (default) with the following shape:

{
  enterDelay: 1000, // Delays entering in ms
  exitAfter: 4000 // Automatically disappear after ms
}

If set to true, the pre-chat messages will be shown immediately and not disappear.
If set to false the pre-chat messages will not be shown regardless of values being populated from the server.

Rendering

`hideOnNoUserResponse`

Indicates whether a chat should render based on the userResponded flag being set in storage for the chat namespace. This type will only render if another chat instance set userResponded to true after a user reply via the chat interface.

`layoutMode`

Defines as what kind of chat window the chat UI should be rendered can be one of:

window: As a chatbutton that needs to be opened by the user (default)
inline: Rendered inline in the page without button
app: A full-screen "window" version of the UI, without open & close functionality.

`connectWhenInView`

Will delay the initialization and creation of a conversation until the interface has scrolled into view. This is enabled by default and currently only supported in layoutMode inline.

`visibilityCallback`

If given, this callback executes each time a new visibility state of the application is requested. Either internally or via user action. The purpose of the callback is to override the standard calculation of the visibility state. for example if the chat interface should remain hidden on page start instead of render in the normal standard state of the chosen layoutMode.

The possible visibility states than can be requested are hidden, minimized, open exported from visibilityStates names export. It is also possible that a null state is requested on initialization.

If given, this callback should always return a single string value that is either hidden, minimized or open.

The callback function receives a single parameter in the form of an object of the following shape:

{
  hasConversation: <boolean>,
  hasResponded: <boolean>,
  previousVisibility: <string>,
  requestedVisibility: <string>,
  config: <object>,
}

See below for a description of each of the properties.

The callback function should be attached to the visibilityCallback property in the application config:

visibilityCallback: ({
    hasConversation,
    hasResponded,
    previousVisibility,
    requestedVisibility,
    config,
  }) => {
    return <calculatedVisbilty>
  }

Callback properties

hasConversation : This boolean value will be set to true if there is a started and connected conversation using the same namespace.
hasResponded : This boolean value will be set to true if at any time during the lifetime of the conversation, the user has responded in any started chat UI using the same namespace.
previousVisibility : This is the visibility state value of the previous calculation. This is persisted in storage, such a browser session storage, to enable seamless continue of chats between pages or refreshes. The value is stored per combination of namespace AND layoutMode. When no value is stored, usually because the chat is running for the first time, a null value is also possible.
requestedVisibility : This is the visibility state value being requested by either the Chat UI internal code or from user actions, such as closing the chat window or using the setVisibility window API action call. The purpose of this callback function is to accept or alter this requested visibility. On initialization the incoming value will always be null, as the initialization state is always a calculated value, either from the previousVisibility, the config or the default state of the layoutMode.
config : This is the complete configuration object of the current Chat UI instance containing all the data described in this document. This can be used to access, for example, the layoutMode setting. It enables calculation of visibility based on any of the config values as well.

Please note: If for some reason there is no storage to fetch the visibility state from after returning to a chat session, the visibilityCallback will be executed again once the conversation data has been fetched.

`errorCallback`

If given, this callback executes each time an error is thrown by the application, either through a user-interaction or a server-update.

The callback function receives two parameters:

error: containing the error that occurred. Generally this is an Error object, or a subclass of Error. It might occur that this is a different object, if it's an error from an internal library.
meta: an object containing information about the app-instance in the shape { namespace, api, layoutMode, conversationUrl }.

errorCallback: (error, {
  namespace,
  api,
  layoutMode,
  conversationUrl,
}) => {
  // ...
}

`appContainerClassNames`

The css class(es) that should be set on the app container <section> and on the lightbox modal container <div>. This can be an array of strings or a function returning the class(es). The default value is:

config => [`app--layout-${config.layoutMode}`, `namespace--${config.namespace}`]

All provided or calculated classes will be prefixed by the CSS_NAME (ie: cvco-).

`zIndex`

The z-index value that should be set on the app container <section> and on the lightbox modal container <div>. The z-index applied to the lightbox will be zIndex + 1. The value is applied via inline styling on the element.

API

`api.key`

Seamly api key

`api.domain`

Domain to connect to. Default is api.seamly-app.com

`api.secure`

Connect securely (enforces https:// and wss:// protocols). Default is true.

`api.sendEnvironment`

Wether or not to send user environment, set to Object to send custom environment. Default is true.

`api.storageProvider`

The storage provider for session information storage. This defaults to the built-in sessionStorageProvider. See the storage providers documentation for more information.

`api.externalId`

An externalId is an identifier pointing to a specific visitor. When an externalId is configured Seamly will try to resume a previous conversation of that specific externalId. That's why it is really important that this identifier is not guessable nor directly derivable from a user's meta data (say using a simple hash of the user's e-mail adress or account number). The externalId must be at least 32 characters long. Any value shorter than that will be silently ignored.

`api.getConversationAuthToken`

If given, getConversationAuthToken is a reference to an (async) function and will only be called once before creating a conversation and sent as payload to the server when creating a conversation occurs. The returned token must be at least 32 characters long. Any value shorter than that will throw a server error.

Context

The default api config context to use when connecting.

Example:

{
  context: {
    channelName: 'web',
    topic: 'login',
    contentLocale: 'en-GB',
    userLocale: 'nl-informal',
    variables: { event: 'question' }
  }
}

`context.channelName`

Name of the channel to be associated with new conversations (default: 'web'). Can be used to differentiate conversations on their channel in reporting, like 'web' and 'app'. These channels need to be enabled in your account.

`context.contentLocale`

The locale code to use for the language the bot or agent is in. This must be an exact match to a locale defined in your account. A locale must be formatted as following (each part separated by a dash (-)):

Lowercase language code The language code must consist of exactly two or three lowercase characters. See ISO 639-1 for a list of available codes. If no ISO 639-1 is available, you may also use a ISO 639-2 or a ISO 639-3 code.
Uppercase country code The country is optional, but when provided may only contain exactly two uppercase characters. See ISO 3166 for a list of available codes.
Variant The variant is optional and can contain at least three characters, all lowercase exept the first which may be upperase.

So for informal Brazilian Portuguese the locale would be pt-BR-informal:

pt for the Portuguese language
BR for Brazil
informal for the variant

`context.userLocale`

The locale code to use for the user side of the conversation. Setting this to a locale different from the context.contentLocale will activate automatic translations if available in your account. This locale must be an exact match to a locale defined in your account (see explanation above on the context.contentLocale).

Important If a setContext window API call has been executed before initialization, it will take precedence over the set context.userLocale in configuration.

`context.topic`

Sets the initial topic.

Important If a setTopic window API call has been executed before initialization, it will take precedence over the set context.topic in configuration.

`context.variables`

An object of variables to send to the Seamly server on startup. Will be merged with a setVariables window API call that is executed before initialization. Can be updated after initialization by the setVariables window API call. Variables set in the context will be resent in case of a restart.

Content defaults

`defaults.visible`

Choice of and initial visual state of 'hidden', 'minimized' and 'open' exported from visibilityStates names export.

Message display

User/Agent display

Agent and user side message have the same configuration options

`messages.agent/user.showAvatar`

Show avatar (true), hide avatar (false), show avatar inside message ("inline")

`messages.agent/user.showName`

Show name

Time Indicator Display

`messages.timeIndicator.enabled`

Show Time Indicators (if set to true) in between events in the conversation. Default is not to show them (set to false).

`messages.timeIndicator.threshold`

The threshold in between messages that should be exceeded to show a time indicator. Default is 1 hour in milliseconds (3600000).

Web Notifications

`notificationAudioURL`

A URL to an audio file to be played when new messages come in and the browser tab is inactive, notifications are enabled in the account config and the user did not give consent to show notifications. If omitted, a default sound will be played. If set to false, playing audio will be disabled. Default is undefined.