Customise the chat widget with code

The chat widget reads a window.chatThingConfig object when it loads. Use it to change things the web channel settings don't cover, such as the widget's position, a text label beside the button, or completely custom CSS. For most colour and icon changes, use the web channel settings instead - no code needed.

To control the widget while the page is running (open it, send messages, register client-side power-ups), use the JavaScript SDK.

How to add configuration

Define window.chatThingConfig in a script before the widget script. If the code you copied from Embed already has a window.chatThingConfig = {...} line, add your options to that object rather than creating a second one.

<script>
  window.chatThingConfig = {
    position: "bottom-left",
    launcherLabel: "Chat with us",
  };
</script>
<script src="https://chatthing.ai/chat-widget.js" type="text/javascript" id="YOUR_BOT_ID" async defer></script>

Options

Options for developers - context, chatId, onChatCreated, webMcp and voiceName - are covered in the JavaScript SDK docs.

Examples

Light theme with a brand colour

window.chatThingConfig = {
  theme: "light",
  colour: {
    widgetColour: "#2563eb",
    primaryColour: "#2563eb",
  },
};

Open the chat after 5 seconds

window.chatThingConfig = {
  autoOpenDelay: 5000,
};

Show a preview bubble above the button

window.chatThingConfig = {
  firstMessage: "Need help? Ask me anything.",
  messagePreviewDelay: 3,
};

firstMessage only sets the bubble above the button. To change the welcome message inside the chat, use firstMessageOverride.

Use your own image for the button

window.chatThingConfig = {
  icon: {
    widgetIcon: "https://example.com/chat-icon.png",
  },
};

Translate the greeting and example questions

Use firstMessageOverride and exampleQuestionsOverride to show the welcome message and suggested questions in the visitor's language. They change this embed only; the bot's saved settings stay the same.

window.chatThingConfig = {
  locale: "es",
  firstMessageOverride: "¡Hola! ¿En qué puedo ayudarte?",
  exampleQuestionsOverride: [
    "¿Cuál es vuestro horario?",
    "¿Hacéis envíos internacionales?",
  ],
};

If your site switches language without reloading the page, update the config and reload the widget:

window.chatThingConfig.locale = "fr";
window.chatThingConfig.firstMessageOverride = "Bonjour ! Comment puis-je vous aider ?";
window.chatThingConfig.exampleQuestionsOverride = [
  "Quels sont vos horaires ?",
  "Livrez-vous à l'international ?",
];
window.chatThing.reload();

The greeting override only applies to the start of a new conversation. It doesn't change a conversation that's already in progress. Leave an option out entirely to keep the bot's own welcome message or example questions.

Full CSS control

For complete control over the widget's look, give CSS for each part in css. Each value is a string of CSS declarations.

Things to know:

• Setting a key replaces all of our default CSS for that element, so include every property you need, including positioning.
• position and zIndex don't apply to an element whose CSS you've replaced.
• Replacing css.window turns off mobileFullscreen and resize.

This example replaces the button's CSS with a square button, 80px from the bottom:

window.chatThingConfig = {
  css: {
    widget: `position: fixed;
z-index: 2147483000;
height: 60px;
width: 60px;
border-radius: 12px;
bottom: 80px;
right: 20px;
background: #111827;
color: #ffffff;
box-shadow: 0px 4px 19px rgba(0,0,0,0.2);
border: none;
display: flex;
align-items: center;
justify-content: center;
cursor: pointer;
overflow: hidden;
padding: 0px;`,
  },
};