Below is a description of all Seamly initialization configuration options.

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


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

  parentElement: document.getElementById("demo"),
  namespace: 'demo',
  showDisclaimer: false,
  layoutMode: 'inline',
  api: {
    key: '....',
  context: {
    channelName: 'web',
    locale: 'en-GB',
  messages: {
    agent: {
      showName: true,
    user: {
      showName: true,
    timeIndicator: {
      enabled: true,
      threshold: 3600000,



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


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


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


A Preact component that replaces the standard Seamly UI view.


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



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



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.


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.


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: ({
  }) => {
    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.


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, {
}) => {
  // ...


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


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.


Boolean value, defaulting to true if not given, that controls display of the FAQ block in Web UI.

If set to false the block will not be shown regardless if FAQ values are being populated from the server or not.



Seamly api key


Domain to connect to. Default is

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


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


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


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.


The default api config context to use when connecting.


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


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.


The locale code to use. 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


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.


Allows setting the automatic translation of the conversation upon initialization. This must be an exact match to a locale defined in your account. See explanation above (context.locale) for allowed format.

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


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


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


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


Show name

Time Indicator Display


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


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