Bot Options

This page documents all available sections and properties that may be passed into the options prop of the ChatBot. For an example on how to structure your options, please refer to the default bot options in the dropdown below.

Click to view default bot options

const defaultOptions = {
  // Configurations Category
  theme: {
    primaryColor: "#42b0c5",
    secondaryColor: "#491d8d",
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', " +
        "'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', " +
        "sans-serif",
    showHeader: true,
    showFooter: true,
    showInputRow: true,
    actionDisabledIcon: actionDisabledIcon,
    embedded: false,
    desktopEnabled: true,
    mobileEnabled: true,
    flowStartTrigger: "ON_LOAD",
  },
  tooltip: {
    mode: "CLOSE",
    text: "Talk to me! 😊",
  },
  chatButton: {
    icon: chatIcon,
  },
  header: {
    title: (
        <h3 style={{cursor: "pointer", margin: 0}} onClick={
            () => window.open("https://github.com/tjtanjin/")
        }>Tan Jin
        </h3>
    ),
    showAvatar: true,
    avatar: botAvatar,
    closeChatIcon: closeChatIcon,
  },
  notification: {
    disabled: false,
    defaultToggledOn: true,
    volume: 0.2,
    icon: notificationIcon,
    sound: notificationSound,
    showCount: true,
  },
  audio: {
    disabled: true,
    defaultToggledOn: false,
    language: "en-US",
    voiceNames: ["Microsoft David - English (United States)", "Alex (English - United States)"],
    rate: 1,
    volume: 1,
    icon: audioIcon,
  },
  chatHistory: {
    disabled: false,
    maxEntries: 30,
    storageKey: "rcb-history",
    viewChatHistoryButtonText: "Load Chat History ⟳",
    chatHistoryLineBreakText: "----- Previous Chat History -----",
    autoLoad: false,
  },
  chatInput: {
    disabled: false,
    allowNewline: false,
    enabledPlaceholderText: "Type your message...",
    disabledPlaceholderText: "",
    showCharacterCount: false,
    characterLimit: -1,
    botDelay: 1000,
    sendButtonIcon: sendButtonIcon,
    blockSpam: true,
    sendOptionOutput: true,
    sendCheckboxOutput: true,
    sendAttachmentOutput: true,
  },
  chatWindow: {
    showScrollbar: false,
    autoJumpToBottom: false,
    showMessagePrompt: true,
    messagePromptText: "New Messages ↓",
    messagePromptOffset: 30,
  },
  sensitiveInput: {
		maskInTextArea: true,
		maskInUserBubble: true,
		asterisksCount: 10,
		hideInUserBubble: false,
	},
  userBubble: {
    animate: true,
    showAvatar: false,
    avatar: userAvatar,
    simStream: false,
    streamSpeed: 30,
    dangerouslySetInnerHtml: false,
  },
  botBubble: {
    animate: true,
    showAvatar: false,
    avatar: botAvatar,
    simStream: false,
    streamSpeed: 30,
    dangerouslySetInnerHtml: false,
  },
  voice: {
    disabled: true,
    defaultToggledOn: false,
    language: "en-US",
    timeoutPeriod: 10000,
    autoSendDisabled: false,
    autoSendPeriod: 1000,
    icon: voiceIcon,
  },
  footer: {
    text: (
      <div style={{cursor: "pointer"}} 
        onClick={() => window.open("https://react-chatbotify.tjtanjin.com")}
      >
        <span>Powered By </span>
        <span style={{fontWeight: "bold"}}>
          <img style={{width: 10, height: 10}} src={logo}></img>
          <span> React ChatBotify</span>
        </span>
      </div>
    ),
  },
  fileAttachment: {
    disabled: false,
    multiple: true,
    accept: ".png",
    icon: fileAttachmentIcon,
  },
  emoji: {
    disabled: false,
    icon: emojiIcon,
    list: ["😀", "😃", "😄", "😅", "😊", "😌", "😇", "🙃", "🤣", "😍", "🥰", "🥳", "🎉", "🎈", "🚀", "⭐️"]
  },
  advance: {
    useCustomMessages: false,
    useCustomBotOptions: false,
    useCustomPaths: false,
  },

  // Styles Category
  tooltipStyle: {},
  chatButtonStyle: {},
  notificationBadgeStyle: {},
  chatWindowStyle: {},
  headerStyle: {},
  bodyStyle: {},
  chatInputContainerStyle: {},
  chatInputAreaStyle: {},
  chatInputAreaFocusedStyle: {},
  chatInputAreaDisabledStyle: {},
  userBubbleStyle: {},
  botBubbleStyle: {},
  botOptionStyle: {},
  botOptionHoveredStyle: {},
  botCheckboxRowStyle: {},
  botCheckboxNextStyle: {},
  botCheckMarkStyle: {},
  botCheckMarkSelectedStyle: {},
  sendButtonStyle: {},
  sendButtonHoveredStyle: {},
  characterLimitStyle: {},
  characterLimitReachedStyle: {},
  chatHistoryButtonStyle: {},
  chatHistoryButtonHoveredStyle: {},
  chatHistoryLineBreakStyle: {},
  chatMessagePromptStyle: {},
  chatMessagePromptHoveredStyle: {},
  footerStyle: {},
  loadingSpinnerStyle: {},
}

Info

Default values for icons, avatars and JSX Elements may not be reflected in the tables below due to space constraints. If you would like information on those, you may refer to the source code containing the default options here.

Configurations

Below is the list of sections available for configurations.

Name	Type	Default	Description
isOpen	boolean	false	Boolean indicating if chat window is open
advance	object		Advanced configurations.
audio	object		Configuration for chatbot audio.
botBubble	object		Configuration for bot chat bubbles.
chatButton	object		Configuration for the chatbot button.
chatWindow	object		Configuration for the chatbot window.
chatHistory	object		Configuration for chatbot chat history.
chatInput	object		Configuration for chatbot input.
emoji	object		Configuration for chatbot emojis.
fileAttachment	object		Configuration for chatbot file attachments.
footer	object		Configuration for the chatbot footer.
header	object		Configuration for the chatbot header.
notification	object		Configuration for chatbot notifications.
sensitiveInput	object		Configuration for chatbot sensitive input.
theme	object		Configuration for the chatbot theme.
tooltip	object		Configuration for the chatbot tooltip.
userBubble	object		Configuration for user chat bubbles.
voice	object		Configuration for chatbot voice.

Advance

These properties are only recommended for advanced use cases. You may refer to the examples here for more details.

Name	Type	Default	Description
useCustomMessages	boolean	false	Specifies whether to use custom messages in the chatbot (audio and message streaming will not work for messages that are directly added).
useCustomBotOptions	boolean	false	Specifies whether to use custom bot options in the chatbot.
useCustomPaths	boolean	false	Specifies whether to use custom paths in the chatbot.

Audio

Properties here handle the playing of audio for messages sent by the bot. When toggled on, messages sent by the bot will be read out. Note that audio is not supported for messages sent in real-time stream.

Name	Type	Default	Description
disabled	boolean	true	Specifies whether chatbot audio is disabled.
defaultToggledOn	boolean	false	Specifies whether chatbot audio is toggled on by default.
language	string	"en-US"	The language for chatbot audio, set by a string representing a BCP 47 language tag.
voiceNames	string[]	"Google US English Male"	An array of voice names for the chatbot audio. Voices are based off what is provided in SpeechSynthesis - you can provide as many voices as you wish (the first voice matched will be used).
rate	number	1	The rate (between 0.1 to 10) at which chatbot audio is played.
volume	number	1	The volume (between 0 to 1) at which chatbot audio is played.
icon	string	-	Image import or URL for the audio icon to be displayed in the chatbot interface.

BotBubble

Properties here handle the chat bubble for messages sent by the bot.

Name	Type	Default	Description
animate	boolean	true	Specifies whether the bot chat bubbles should be animated.
showAvatar	boolean	false	Specifies whether the avatar should be displayed for bot chat bubbles.
avatar	string	-	Image import or URL for the avatar to be displayed for bot chat bubbles.
simStream	boolean	false	Specifies whether to simulate text messages from the bot as a stream.
streamSpeed	number	30	Specifies the interval in milliseconds between streaming each character (ignored if simStream is false).
dangerouslySetInnerHtml	boolean	false	Specifies whether to allow setting of raw HTML content within a bot message bubble (if true, do sanitize input strings and use with caution).

ChatButton

Properties here handle the chat button that is used to toggle chat window. Note that the chat button does not show if chat window is embedded.

Name	Type	Default	Description
icon	string	-	Image import or URL for the chatbot button.

ChatWindow

Properties here handle the UI/UX in the chat window. Note that it is recommended to stick to default values for this section as they have been optimized for the ideal experience.

Name	Type	Default	Description
showScrollbar	boolean	false	Specifies whether scrollbar will be shown when chat messages overflow the window.
autoJumpToBottom	boolean	false	Specifies whether new messages will always send the user to the bottom of the chat window (recommended to keep false as this can be disruptive).
showMessagePrompt	boolean	true	Specifies whether to show a message prompt when new messages are received while a user is scrolling the window.
messagePromptText	string	"New Messages ↓"	The text to be displayed on the message prompt shown.
messagePromptOffset	number	30	The offset (in pixels) that the user must be from the bottom of the chat window to be considered scrolling and thus see the message prompt (recommended to keep at 30 or higher).

ChatHistory

Properties here handle the viewing of chat history.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether chatbot chat history is disabled.
maxEntries	number	30	The maximum number of chat history entries to display.
storageKey	string	"rcb-history"	The key to use for storing chat history. Can be ignored if you only have a single instance of the chatbot on your website. Otherwise, if multiple chatbots share the same storage key, their chat history will overlap.
viewChatHistoryButtonText	string	"Load Chat History"	The text to be displayed on the view chat history button.
chatHistoryLineBreakText	string	"----- Previous Chat History -----"	The text to be displayed as a line break in the chat history.
autoLoad	boolean	false	Specifies whether to automatically load chat history on start (requires disabled to be set to false as well)

ChatInput

Properties here handle the chat input sent by the user. Note that when chatbot input is disabled, emoji picker and voice will also be disabled.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether chatbot input is disabled (can be overriden by the chatDisabled attribute within a Block).
allowNewline	boolean	false	Specifies whether newline is allowed in chatbot input.
enabledPlaceholderText	string	"Type your message..."	The placeholder text to display in the chat input when it is enabled.
disabledPlaceholderText	string	""	The placeholder text to display in the chat input when it is disabled.
showCharacterCount	boolean	false	Specifies whether to show the character count and limit (note that this value is ignored if characterLimit is not set to 0 or more).
characterLimit	number	-1	The maximum number of characters allowed in the chat input, defaults to -1 (no limit).
botDelay	number	1000	The delay in milliseconds before chatbot responses are displayed (minimum value of 500).
sendButtonIcon	string	-	Image import or URL for the send button to be displayed in the chat input.
blockSpam	boolean	true	Specifies whether user input should be blocked while the bot is processing its next action (highly recommended to keep this true as spamming messages can result in unexpected behaviors).
sendOptionOutput	boolean	true	Specifies whether to send user option as a message to the bot.
sendCheckboxOutput	boolean	true	Specifies whether to send user selection(s) as a message to the bot.
sendAttachmentOutput	boolean	true	Specifies whether to send a message with name(s) of file attachments as a message to the bot.

Emoji

Properties here handle the emoji picker. Note that this feature will be disabled if chat input is disabled.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether emoji picker is disabled.
icon	string	-	Image import or URL for the emoji icon to be displayed in the chatbot footer.
list	string[]	["😀", "😃", "😄", "😅", "😊", "😌", "😇", "🙃", "🤣", "😍", "🥰", "🥳", "🎉", "🎈", "🚀", "⭐️"]	An array of emojis available for selection in the emoji picker.

FileAttachment

Properties here handle the file attachment button.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether chatbot file attachments are disabled.
multiple	boolean	true	Specifies whether multiple file attachments are allowed.
accept	string	*	The accepted file types for file attachments (e.g. ".png, .jpg" to restrict file types or * to accept all file types).
icon	string	-	Image import or URL for the file attachment icon to be displayed in the chatbot footer.

Footer

Properties here handle the chat footer.

Name	Type	Default	Description
text	string | JSX.Element	-	The text or JSX element to be displayed in the chatbot footer.

Header

Properties here handle the chat header.

Name	Type	Default	Description
title	string | JSX.Element	-	The title to be displayed in the chatbot header.
showAvatar	boolean	true	Specifies whether the avatar should be displayed in the chatbot header.
avatar	string	-	Image import or URL for the avatar to be displayed in the chatbot header.
closeChatIcon	string	-	Image import or URL for the close chat icon to be displayed in the chatbot header.

Notification

Properties here handle the message notification sent to the user. When toggled on, a notification sound will be played when a message is sent while the chat window is closed or while the user is alt-tab. For embedded chatbots, notification will be played if chatbot is scrolled out of view.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether chatbot notifications are disabled.
defaultToggledOn	boolean	true	Specifies whether chatbot notifications are toggled on by default.
volume	number	0.2	The volume (between 0 to 1) at which notification sound is played.
notificationSound	string	-	The sound to be played for chatbot notifications.
icon	string	-	Image import or URL for the notification icon to be displayed in the chatbot header.
showCount	boolean	true	Specifies whether unread message count is shown on the top right corner of the chat bot button (this option is ignored if notification is disabled).

SensitiveInput

Properties here handle sensitive chat input sent by the user.

Name	Type	Default	Description
maskInTextArea	boolean	true	Specifies whether to mask sensitive text with asterisks within the chat input textarea that users type in (if hideInUserBubble is set to true, it will override this option).
maskInUserBubble	boolean	true	Specifies whether to mask sensitive text with asterisks within the user message bubble sent to chat.
asterisksCount	number	true	Specifies the number of asterisks used to mask the sensitive text in chat bubbles.
hideInUserBubble	boolean	true	Specifies whether to completely hide user message bubbles containing sensitive text when sent to chat.

Theme

Properties here handle the chatbot theme.

Name	Type	Default	Description
primaryColor	string	"#42b0c5"	The primary color for the chatbot's interface.
secondaryColor	string	"#491d8d"	The secondary color for the chatbot's interface.
fontFamily	string	"-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif"	The default font family to be used for the chatbot's text.
showHeader	boolean	true	Specifies whether the header should be shown in the chat window.
showFooter	boolean	true	Specifies whether the footer should be shown in the chat window.
showInputRow	boolean	true	Specifies whether the chat input row should be shown in the chat window.
actionDisabledIcon	string	-	The cursor image to display when hovering over an action that is disabled.
embedded	boolean	false	Specifies whether the chatbot is embedded in the webpage or accessed through a floating button. Note that notifications feature will not work for embedded chat windows.
desktopEnabled	boolean	true	Specifies whether the chatbot is enabled for users on desktop.
mobileEnabled	boolean	true	Specifies whether the chatbot is enabled for users on mobile.
flowStartTrigger	string	"ON_LOAD"	The trigger for starting chatbot flow which includes: ON_LOAD: Flow begins on chatbot load ON_CHATBOT_INTERACT: Flow begins when user interacts with chatbot ON_PAGE_INTERACT: Flow begins when user interacts with page

Tooltip

Properties here handle the tooltip shown beside the chat button.

Name	Type	Default	Description
mode	string	"CLOSE"	The mode of the tooltip which includes: ALWAYS: Tooltip is always shown CLOSE: Tooltip is shown when chat window is closed START: Tooltip is shown once on page load NEVER: Tooltip is never shown
text	string	"Talk to me! 😊"	The text to be displayed in the tooltip.

UserBubble

Properties here handle the chat bubble for messages sent by the user.

Name	Type	Default	Description
animate	boolean	true	Specifies whether the user chat bubbles should be animated.
showAvatar	boolean	false	Specifies whether the avatar should be displayed for user chat bubbles.
avatar	string	-	Image import or URL for the avatar to be displayed for user chat bubbles.
simStream	boolean	false	Specifies whether to simulate text messages from the user as a stream.
streamSpeed	number	30	Specifies the interval in milliseconds between streaming each character (ignored if simStream is false).
dangerouslySetInnerHtml	boolean	false	Specifies whether to allow setting of raw HTML content within a user message bubble (if true, do sanitize input strings and use with caution).

Voice

Properties here handle the voice to text feature (feature is available only on desktop). Note that this feature will be disabled if chat input is disabled.

Name	Type	Default	Description
disabled	boolean	false	Specifies whether chatbot voice is disabled.
defaultToggledOn	boolean	false	Specifies whether chatbot voice is toggled on by default.
language	string	"en-US"	The expected language from the user, set by a string representing a BCP 47 language tag.
timeoutPeriod	number	10000	The timeout period in milliseconds for chatbot voice before it automatically toggles off.
autoSendDisabled	boolean	false	Specifies whether auto-sending of voice messages into the chat is disabled.
autoSendPeriod	number	1000	The period in milliseconds after which voice messages are automatically sent.
icon	string	-	Image import or URL for the voice icon to be displayed in the chatbot interface.

Styles

Tip

Before diving into styling, note that if you merely wish to change the color theme of the chatbot to suit your website, you are advised to modify the primaryColor and secondaryColor properties within the theme section. Often times, this is enough to complement your website theme.

If you wish to make further changes to the chatbot styles, then below is the list of sections available.

Name	Type	Default	Description
bodyStyle	object		Styles for the chatbot body.
botBubbleStyle	object		Styles for bot chat bubbles.
botCheckboxNextStyle	object		Styles for the next bot checkbox.
botCheckboxRowStyle	object		Styles for bot checkbox rows.
botCheckMarkSelectedStyle	object		Styles for the selected bot checkmark.
botCheckMarkStyle	object		Styles for the bot checkmark.
botOptionHoveredStyle	object		Styles for hovered bot options.
botOptionStyle	object		Styles for bot options.
characterLimitStyle	object		Styles for the character limit display.
characterLimitReachedStyle	object		Styles for the character limit display when limit is reached.
chatButtonStyle	object		Styles for the chatbot button.
chatHistoryButtonHoveredStyle	object		Styles for the hovered chat history button.
chatHistoryButtonStyle	object		Styles for the chat history button.
chatHistoryLineBreakStyle	object		Styles for the chat history line break.
chatInputContainerStyle	object		Styles for the chatbot input text area.
chatInputAreaStyle	object		Styles for the chatbot input container.
chatInputAreaFocusedStyle	object		Styles for the chatbot input container when it is focused.
chatInputAreaDisabledStyle	object		Styles for the chatbot input container when it is disabled.
chatMessagePromptStyle	object		Styles for the new message prompt.
chatMessagePromptHoveredStyle	object		Styles for the new message prompt when it is hovered.
chatWindowStyle	object		Styles for the chatbot window.
footerStyle	object		Styles for the chatbot footer.
headerStyle	object		Styles for the chatbot header.
loadingSpinnerStyle	object		Styles for the loading spinner.
notificationBadgeStyle	object		Styles for the chatbot notification badge.
sendButtonHoveredStyle	object		Styles for the hovered send button.
sendButtonStyle	object		Styles for the send button.
tooltipStyle	object		Styles for the chatbot tooltip.
userBubbleStyle	object		Styles for user chat bubbles.

The utilization of styles is remarkably simple, as each section readily accepts inline React styles. For instance, you can customise the headerStyle with headerStyle: {backgroundColor: "red"}.

Tip

If you wish to customise the chatbot appearance with even more granularity, you may also overwrite the CSS classes directly. Class names for this library are appended with rcb and you may find the relevant classes through inspect element or by combing through the CSS files within the components in the code repository.