# Website chat for developers

> How the Message24 website chat widget works, what the channel key is, and how allowed origins protect a channel.

Source: https://docs.message24.net/developers/website-chat/overview/

The website chat widget puts a chat bubble on your site. Visitors' messages land in the business's Message24 inbox next to Instagram, WhatsApp and the other channels, and replies from the team or the AI agent appear in the widget in real time. This section covers embedding the widget, configuring it from your page, and building your own chat client on the same HTTP API.

If you are the business owner setting up the channel, start with [Website chat](/owners/channels/website-chat/) instead.

## How it works

1. A business admin creates a Web Chat channel in Message24. The channel gets a **channel key** and an embed snippet.
2. You add the snippet to your site. It loads `https://message24.net/widget.js`, which reads `data-channel-key` from its own `<script>` tag.
3. The widget fetches the channel's configuration (colour, position, welcome message, pre-chat form). If that request fails, for example because the key is wrong or your origin is not allowed, no bubble is shown.
4. When the visitor opens the chat for the first time, the widget creates a visitor session and stores a random visitor ID and the session token in `localStorage`. If the channel has a visitor details form, the visitor fills it in first.
5. The visitor's first message creates the contact and the conversation in the inbox. Every message carries the current page path, title and any page data you provide.
6. Replies arrive over a server-sent events stream, with polling as a backstop. The conversation survives page reloads and stays in sync across tabs of the same browser.

The widget renders inside a Shadow DOM attached to a `<div id="m24-widget-root">` appended to `<body>`, so your site's CSS does not affect it and its CSS does not leak into your page.

## The channel key

The channel key is a UUID that identifies one Web Chat channel. It is a **public identifier, not a secret**: it sits in your page source and anyone can read it. Message24 signs and validates visitor session tokens on its side, so there are no secrets for you to manage.

An admin can rotate the key from the channel's settings with **Regenerate key**. The old key stops working immediately, so every page that embeds it must be updated with the new snippet.

If the channel is disconnected, every widget endpoint for that key returns `404` and the widget does not appear.

## Allowed origins

Each channel has an **Allowed Origins** list in its settings, one origin per line, for example:

```text
https://example.com
https://shop.example.com
```

Every widget request is checked against this list:

- The request's origin is taken from the `Origin` header, or from the `Referer` header when `Origin` is missing.
- An origin matches when its scheme and host (including any port) are the same as a list entry, compared case-insensitively. `https://example.com` does not allow `https://www.example.com` or `http://example.com`; list each one.
- **An empty list allows every origin.** This is convenient while testing, but set the list before going live.
- A request with no `Origin` or `Referer` is rejected when the list is non-empty, unless **Allow requests with no Origin header (native apps / strict webviews)** is checked.

A rejected request gets `403` with `{"error": "Origin not allowed"}`.

:::caution
The origin check stops other websites from embedding your channel in a browser. It is not authentication: a non-browser client can send any `Origin` header it likes. Note also that the channel's configuration, including the allowed origins list, is returned by the public config endpoint.
:::

Only check **Allow requests with no Origin header** for a channel that serves a native mobile app or a webview that strips the header. See [Build a custom chat client](/developers/website-chat/custom-chat-client/).

## Channel settings that affect the widget

These are set by a business admin in the channel's Web Chat settings. You read them back from the [config endpoint](/developers/website-chat/custom-chat-client/#get-the-channel-configuration) if you build your own client.

| Setting | Config field | Effect |
|---|---|---|
| Primary Color | `primaryColor` | Launcher and accent colour. Default `#000000`. |
| Widget Position | `position` | `bottom-right` (default) or `bottom-left`. |
| Launcher Motion | `launcherMotion` | `none` or `bounce`. Bounce stops once the visitor opens the chat. |
| Input Placeholder | `placeholder` | Placeholder text in the message box. |
| Header & Welcome: Business Name | `businessName` | Header title. Defaults to the channel name. |
| Header & Welcome: Business Logo URL | `businessLogo` | Header image. Without it the header shows the name's initials. |
| Header & Welcome: welcome text | `welcomeMessage` | Shown before the first message. Default "Hi! How can we help?". |
| Visitor Details Form | `visitorFields` | `nameRequired`, `phoneEnabled`, `phoneRequired`. Enforced by the server when a session is created. |
| Allowed Origins | `allowedOrigins` | See above. |
| Allow requests with no Origin header | `allowNoOrigin` | See above. |

## Test a channel

Message24 hosts a test page that loads the widget for any key: `https://message24.net/webchat-test.html?channelKey=YOUR_CHANNEL_KEY`. It sets sample page data so you can see page context reach the inbox. If the channel has an allowed origins list, add `https://message24.net` to it while testing.

## Troubleshooting

- **The bubble does not appear.** Check that `data-channel-key` is correct and that the script `src` is `https://message24.net/widget.js`. The browser console shows `[m24] No data-channel-key found on script tag` when the attribute is missing. A `404` on `/config` means the key is wrong or the channel is disconnected.
- **`403 Origin not allowed`.** Add your site's exact origin, scheme included, to Allowed Origins.
- **Messages send but nobody answers.** Confirm the channel is active in the inbox. If you expect the AI agent to reply, confirm the business has turned AI on for this channel.
- **"You are sending messages too quickly."** The visitor hit a rate limit. See [rate limits](/developers/website-chat/custom-chat-client/#rate-limits).

## Next steps

- [Embed the widget](/developers/website-chat/embed-widget/) in plain HTML, React or Next.js.
- [Configure it from your page](/developers/website-chat/javascript-api/): visitor identity, page context and custom product cards.
- [Build a custom chat client](/developers/website-chat/custom-chat-client/) or a mobile app on the widget HTTP API.
