---
title: "Customise the chat widget with code"
description: "Every chatThingConfig option for the Chat Thing widget - position, colours, launcher label, auto-open, per-language greetings and full CSS overrides."
canonical_url: "https://chatthing.ai/docs/channels/website/customise-with-code"
last_updated: "2026-09-25"
---

# 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](https://chatthing.ai/docs/channels/website/appearance) 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](https://chatthing.ai/docs/developers/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.

```html
<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

| Option | Type | What it does |
| --- | --- | --- |
| `botId` | string | Your bot ID. An alternative to the `id` attribute on the script tag. |
| `theme` | `"dark"` or `"light"` | Colour scheme for the parts the widget adds to your page: the chat window's background, the preview bubble and the launcher label. Defaults to `"dark"`. The chat inside the window is themed from your [web channel settings](https://chatthing.ai/docs/channels/website/appearance). |
| `locale` | `"de"`, `"es"`, `"fr"`, `"it"`, `"jp"`, `"cn"`, `"el"`, `"pl"` or `"nl"` | Interface language. Leave it out for English. See [Languages](https://chatthing.ai/docs/channels/website/languages). |
| `position` | `"bottom-right"` or `"bottom-left"` | Which corner the button, window and preview bubble sit in. Defaults to `"bottom-right"`. |
| `zIndex` | number | Stacking order of the button, window and preview bubble. Defaults to a very high value (2147483000). |
| `colour` | object | `primaryColour`, `primaryColourInverted`, `widgetColour`, `widgetColourInverted`. `widgetColour` is the button background and `widgetColourInverted` its icon colour. Your `css` overrides take precedence. |
| `icon` | object | `widgetIcon`: the address of an image to use on the widget button. Takes precedence over `svg.widget`. |
| `svg` | object | `widget` and `close`: inline SVG markup for the button's open and close icons. |
| `launcherLabel` | string | A text pill beside the button, such as "Chat with us". Style it with `css.launcherLabel`. |
| `pulse` | object | An attention-grabbing pulsing outline on the button while the chat is closed: `{ enabled, color, speed }`. `speed` is seconds per pulse (default 2); `color` defaults to the primary colour. Off by default, and switched off for visitors who prefer reduced motion. |
| `unreadBadge` | object | A notification badge on the button: `{ enabled, color }`. Off by default. The chat doesn't report unread messages yet, so the badge currently never appears. |
| `autoOpenDelay` | number (milliseconds) | Opens the chat automatically after this delay. `5000` is 5 seconds. |
| `initialQuestion` | string | A question sent to the bot automatically when the chat opens. |
| `firstMessage` | string | Text for the preview bubble above the button. |
| `messagePreviewDelay` | number (seconds) | Delay before the preview bubble appears. |
| `firstMessageOverride` | string | Replaces the bot's welcome message inside the chat, for this embed only. Up to 2,000 characters; longer values are ignored. `""` starts the chat with no welcome message. |
| `exampleQuestionsOverride` | string | Replaces the bot's example questions for this embed only. `[]` hides them. |
| `closeChatButton` | boolean | Shows the close (X) button in the chat window header. Defaults to `true`. |
| `mobileFullscreen` | boolean | Opens the chat full screen on screens 640px wide or narrower. Defaults to `true`. Ignored if you set `css.window`. |
| `resize` | boolean | Lets visitors drag to resize the chat window; the size is remembered. Off by default. Ignored on mobile and if you set `css.window`. |
| `selectors` | object | `widgetTrigger`: a CSS selector for your own element to use as the button instead of ours. `widgetWindowParent`: a CSS selector for an element to put the chat window inside. |
| `css` | object | CSS overrides for each part of the widget. See [Full CSS control](https://chatthing.ai/docs/channels/website/customise-with-code#full-css-control). |
| `url` | string | The address the chat loads from. Only needed with a [custom domain](https://chatthing.ai/docs/channels/website/custom-domain); the embed code adds it for you. |

Options for developers - `context`, `chatId`, `onChatCreated`, `webMcp` and `voiceName` - are covered in the [JavaScript SDK](https://chatthing.ai/docs/developers/javascript-sdk) docs.

## Examples

### Light theme with a brand colour

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

### Open the chat after 5 seconds

```javascript
window.chatThingConfig = {
  autoOpenDelay: 5000,
};
```

### Show a preview bubble above the button

```javascript
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

```javascript
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.

```javascript
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:

```javascript
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.

| Key | Element |
| --- | --- |
| `widget` | The round button that opens the chat |
| `window` | The chat window |
| `iframe` | The chat inside the window |
| `launcherLabel` | The text pill set by `launcherLabel` |
| `messagePreviewContainer` | The container that positions the preview bubble |
| `messagePreviewBox` | The preview bubble |
| `messagePreviewText` | The text in the preview bubble |
| `messagePreviewCloseButton` | The preview bubble's close button |
| `messagePreviewCloseIcon` | The icon in that close button |
| `messagePreviewIconWrapper` | The circle around the bot icon in the preview bubble |
| `messagePreviewIconImg` | The bot icon in the preview bubble |
| `customAssistantIcon` | A custom image on the widget button |
| `bubbleCustomAssistantIcon` | A custom image in the preview bubble |

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:

```javascript
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;`,
  },
};
```

## Related

- [JavaScript SDK](https://chatthing.ai/docs/developers/javascript-sdk): Control the Chat Thing website widget with window.chatThing - open it, send messages, identify users, add page context and client-side power-ups.
- [Change how the chat widget looks and behaves](https://chatthing.ai/docs/channels/website/appearance): Set the widget's colours, light or dark mode, icons, welcome message, first message preview, link behaviour and voice input from the web channel settings.
- [Add the chat widget to your website](https://chatthing.ai/docs/channels/website/install): Copy your bot's embed code and paste it into your site as a chat widget or embedded chat, with steps for WordPress, Shopify, Webflow, Wix and more.