Skip to content
Message24Message24 Docs

Website chat for developers

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

Markdownllms.txt

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 instead.

How it works

Section titled “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

Section titled “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

Section titled “Allowed origins”

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

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"}.

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.

Channel settings that affect the widget

Section titled “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 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

Section titled “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

Section titled “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.

Next steps

Section titled “Next steps”