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,
  layoutMode: 'inline',
  api: {
    key: '....',
  },
  context: {
    locale: 'en',
  },
  defaults: {
    userName: 'You'
  },
  messages: {
    agent: {
      showName: true,
    },
    user: {
      showName: true,
    },
  },
}

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.

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

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

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

API

api.key

Seamly api key

api.domain

Domain to connect to. Default is api.seamly.ai

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.

Context

The default api config context to use when connecting.

Example:

{
  context: {
    locale: "en",
    variables: { event: 'question' }
  }
}

context.locale

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

context.variables

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

defaults.visible

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

defaults.startChatIcon

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

defaults.agentName

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

defaults.agentIcon

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.

defaults.userName

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

messages.agent/user.showAvatar

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

messages.agent/user.showName

Show name