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: {
    channelName: 'web',
    locale: '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.

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.

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.

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.

showFaq

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.

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.

Context

The default api config context to use when connecting.

Example:

{
  context: {
    channelName: 'web',
    locale: 'en-GB',
    topic: 'login',
    translationLocale: '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.locale

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

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

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.

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