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: {
    locale: 'en',
  defaults: {
    userName: 'You'
  messages: {
    agent: {
      showName: true,
    user: {
      showName: true,



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
  • modal: a proper modal overlay "modal". When using "modal" no open button will be rendered and the modal MUST be opened via the public API.


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

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 initialisation the incoming value will always be null, as the initialisation 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.


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



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: {
    locale: "en",
    variables: { event: 'question' }


The ISO locale code to use. Can be changed after initialisation by the setLocale window API call.


An object of variables to send to the Seamly server on startup. Can be updated after initialisation 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.


Sets the url to the icon to use as chat start icon. This will override the internal default and show whenever that icon would have been displayed


Sets the agent name to display before receiving the actual name from the server.


Sets the icon to use if no agent avatar is given for a specific agent. This will override the internal default and show whenever that icon would have been displayed.


Sets the user name to display above user generated chat messages, if activated via the config setting below.

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