Configuration

token

required

The only required option; your organization’s widget token. you can find it in Dashboard / Widget.

language

ar | de | es | en | fr | nl | pt

default:"en"

The language of the widget’s interface.

initialMessages

string[]

default:["Hello, how can I help you?"]

Initial messages that the user sees in a new chat session. These messages will disappear once the user sends their first message.

persistentInitialMessages

string[]

default:[]

Similar to initialMessages, but these messages will persist at the top of the chat session.

initialQuestions

string[]

default:[]

Suggested initial questions that the contact sees in a new chat session. If a user clicks on one of the suggested questions, the widget will send it as the user’s first message.

initialQuestionsPosition

above-chat-input | below-initial-messages

default:"above-chat-input"

Where to display the suggested initial questions.

collectUserData

boolean

default:false

If turned on, the widget will have a login-like screen to collect user’s name and email. A non-verified contact will be created based on the provided information.

extraDataCollectionFields

string[]

default:[]

Extra data collection fields besides name and email. For this setting to take effect, collectUserData must be set to true.

prefillUserData

object

default:{}

Provide initial values for the name and email inputs in the welcome screen. For this setting to take effect, collectUserData must be set to true.

Show properties

name

string

bot

object

Name and avatar of the bot.

Show properties

name

string

default:"AI Support Agent"

The name of the bot.

avatar

string

default:""

The avatar URL of the bot.

user

object

default:{}

Verified or non-verified contact data. If no data is provided, an anonymous contact will be created.For more details and recipes, check the Authentication page.

Show verified user properties

token

string

required

A server-to-server generated token, check the API reference.

externalId

string

An optional ID to scope the sessions of a single user based on workspace. For example, if a user uses one email for multiple accounts (organizations) in your application.

Show non-verified user properties

data

object

Show properties

name

string

The name of the user. Will be marked as non_verified_name so that it can be used with caution. If there is a verified user with the same email, the non_verified_name will not override the verified user’s name.

string

avatarUrl

string

customData

Record<string, string | number | boolean>

An object containing user custom data. Will be marked as non_verified_custom_data so that it can be used with caution.

Show example

{
  "org_id": "org_185938572649",
  "vip": true,
  "loyalty_points": 1200
}

externalId

string

An optional ID to scope the sessions of a single user based on workspace. For example, if a user uses one email for multiple accounts (organizations) in your application.

assets

object

default:{}

Show properties

organizationLogo

string

A logo to show in the welcome screen.

Show properties

openIcon

string

closeIcon

string

textContent

object

default:"language-specific"

Custom text content to override the defaults in the widget.

Show properties

welcomeScreen

object

Show properties

title

string

description

string

sessionsScreen

object

Show properties

headerTitle

string

chatScreen

object

Show properties

headerTitle

string

isOpen

boolean

default:false

Whether the widget is open or not.Can be used to have the widget open by default (useful when embedded in a webview for a mobile app). Also useful to open and close the widget programmatically.

openAfterNSeconds

number

default:"undefined"

Automatically open the widget after N seconds.

cssOverrides

string

default:"undefined"

A custom vanilla stylesheet to override the default styles.You will need to use the selectors to target the elements you want to override. Inspect the DOM and look for things that look like data-component="chat/input_box/root".If you want to customize a component and it doesn’t have a selector, let us know and we’ll add it.

Show selectors

export type OpenCxComponentNameU =
  /* ------------------------------------------------------ */
  /*                         UI Lib                         */
  /* ------------------------------------------------------ */
  | 'ui_lib/btn'
  /* ------------------------------------------------------ */
  /*                         Trigger                        */
  /* ------------------------------------------------------ */
  | 'trigger/btn'
  /* ------------------------------------------------------ */
  /*                     Sessions Screen                    */
  /* ------------------------------------------------------ */
  | 'sessions/root'
  | 'sessions/header'
  | 'sessions/new_conversation_btn'
  /* ------------------------------------------------------ */
  /*                       Chat Screen                      */
  /* ------------------------------------------------------ */
  | 'chat/root'
  | 'chat/header'
  | 'chat/msgs/root'
  /* -------------------- Agent Message ------------------- */
  | 'chat/agent_msg_group/root'
  | 'chat/agent_msg_group/avatar_and_msgs/root'
  | 'chat/agent_msg_group/avatar_and_msgs/avatar'
  | 'chat/agent_msg_group/avatar_and_msgs/msgs'
  | 'chat/agent_msg_group/root/avatar'
  | 'chat/agent_msg_group/suggestions'
  | 'chat/agent_msg/root'
  | 'chat/agent_msg/msg'
  /* ------------- Persistent Initial Messages ------------ */
  | 'chat/persistent_initial_msgs/root'
  | 'chat/persistent_initial_msg/root'
  | 'chat/persistent_initial_msg/msg'
  /* -------------------- Chat Message -------------------- */
  | 'chat/user_msg_group/root'
  | 'chat/user_msg_group/avatar/root'
  | 'chat/user_msg/root'
  | 'chat/user_msg/msg'
  /* --------------------- Chat Input --------------------- */
  | 'chat/input_box/root'
  | 'chat/input_box/inner_root'
  | 'chat/input_box/textarea_and_attachments_container'
  | 'chat/input_box/textarea'
  | 'chat/input_box/attachments_container'
  /* --------------------- Chat Utils --------------------- */
  | 'chat/bot_loading/root'
  | 'chat/bot_loading/bouncing_dots_container'
  | 'chat/suggested_reply_btn'
  | 'chat/might_solve_user_issue_suggested_replies_container';

Show example

{
  "cssOverrides": `
    * {
      font-family: "Arial", sans-serif;
    }

    [data-component="ui_lib/btn"][data-variant="ghost"]:hover {
      background: rgba(68, 71, 70, 0.08);
    }

    [data-component="chat/agent_msg_group/root/avatar"] {
      border-width: 2px;
      border-color: white;
      display: initial;
    }
    [data-component="chat/agent_msg_group/avatar_and_msgs/avatar"] {
      display: none;
    }
    [data-component="chat/agent_msg_group/suggestions"] {
      padding-left: unset;
    }
  `
}

theme

object

Theme customization options.

Show properties

palette

neutral | stone | zinc | slate

default:"stone"

primaryColor

string

default:"hsl(0, 0%, 0%)"

Show properties

zIndex

number

default:10000000

offset

object

Show properties

right

number (pixels)

default:20

bottom

number (pixels)

default:20

size

object

Show properties

button

number (pixels)

default:48

icon

number (pixels)

default:24

Show properties

borderRadius

string

default:"32px"

boxShadow

string

default:"0 0px 100px 0px rgb(0 0 0 / 0.25)"

outline

string

default:"none"

outlineColor

string

default:"hsl(0 0% 50% / .5)"

transitionProperty

string

default:"all"

transitionTimingFunction

string

default:"cubic-bezier(0.16, 1, 0.3, 1)"

transitionDuration

string

default:"800ms"

zIndex

number

default:10000001

offset

object

Show properties

side

number (pixels)

default:10

align

number (pixels)

default:0

screens

object

Show properties

welcome

object

Show properties

width

string

default:"375px"

minHeight

string

default:"200px"

sessions

object

Show properties

width

string

default:"450px"

height

string

default:"600px"

chat

object

Show properties

width

string

default:"525px"

height

string

default:"700px"

router

object

Customize routing rules between screens.

Show properties

goToChatIfNoSessions

boolean

default:true

If true, the router will navigate to the chat screen instead of sessions screen if the contact has no previous sessions.

anchorTarget

_top | _blank

default:"_top"

The target attribute for all links in the AI or human agents responses.

_top opens links in the same tab.
_blank opens links in a new tab or window.

headers

Record<string, string>

default:{}

Custom headers to be sent with each AI action called.

Show example

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjN9.KwXvsvfT7Z67fdDb8JqB_34e7FekbF3PZjM4CrcK8dE",
}

queryParams

Record<string, string>

default:{}

Custom query params to be sent with each AI action called.

Show example

{
  "session_id": "9de647ba-25b9-4d9e-b51a-7ab2f4c68d9d",
}

bodyProperties

Record<string, string>

default:{}

Custom body properties to be sent with each AI action called.

Show example

{
  "preferred_language": "en",
}

context

object

default:{}

Dynamic context to be sent with each send-message request from the widget.

Show example

{
  "page": {
    "url": window.location.href
  },
  "product_id": "99836009",
  "product_name": "Ineffective painkiller",
  "product_price": 12.99,
}

messageCustomData

object

default:{}

Dynamic custom data to be sent with each contact message. This custom data is intended for human use only; the AI will not see it and it will not affect the AI’s response.

Show example

{
  "platform": "MOBILE",
  "version": "1.3.57",
}

Getting started

AI Chat Widget

AI Phone Support

AI WhatsApp Support

AI SMS Support

AI Email Support

AI Actions

Training your AI

Ticketing Systems

Other Integrations

CRMs

AI Safety

Resources

Security