Documentation — MxChat Anywhere

MxChat Anywhere

Deploy your WordPress-hosted MxChat chatbot on any website with a single <script> tag — no WordPress required on the target site.

Overview

MxChat Anywhere takes the chatbot you've already configured in WordPress — system prompts, knowledge base, theme, popular questions, email collection, all of it — and lets it run on any external site: Shopify, Squarespace, Wix, Webflow, static HTML, a SaaS dashboard, a marketing landing page. You generate a single script snippet from your WordPress dashboard and paste it into the host site. The widget renders inside a Shadow DOM so host-page CSS can't bleed in and your widget styles can't leak out. All chat traffic is proxied through your WordPress REST API back to the MxChat core integrator, so API keys, system prompts, and model configuration stay server-side. Requires the core MxChat plugin and an active MxChat Pro license on the WordPress install that hosts the bot.

Setup

  1. Install MxChat Anywhere via the WordPress admin (Plugins → Add New → Upload, or via the MxChat add-on gallery).
  2. Activate via Plugins → Installed Plugins. The plugin requires mxchat-basic to be active and a valid MxChat Pro license.
  3. Go to MxChat → Embed Widget in the WordPress admin.
  4. Toggle the embed widget to enabled and add your target domain(s) to the Allowed Domains list.
  5. Copy the generated <script> snippet from the sidebar and paste it into the target site — either in the <head> or just before the closing </body> tag.

The script loads asynchronously, so it won't block your host page's render. Within a couple of seconds, the MxChat floating button fades into the corner of the page exactly as it appears on your WordPress site.

Settings

Embed Widget Enabled

Master on/off switch. When off, all REST endpoints under /mxchat-embed/v1/ return early — the script tag will fetch and fail gracefully. Default: off.

Allowed Domains (CORS Whitelist)

One domain per line. Requests from origins not on this list are blocked at the CORS layer. Wildcard subdomains (*.example.com) and localhost for local development are supported. Leave blank during initial testing only — production embeds should always have a populated whitelist.

Site Key

A 32-character random key generated automatically on activation, used to authenticate every REST request. You can regenerate it from the admin page — note that regenerating invalidates the old snippet, so you'll need to re-paste the new one wherever the widget is deployed. All embed snippets on the admin page update in place when you regenerate.

Default Bot ID

When the Multi-Bot add-on is active, each bot gets its own embed snippet in the sidebar. The default bot is served when the snippet has no &bot= parameter. Per-bot snippets carry &bot=BOT_ID automatically.

Features

  • One script tag, anywhere: Paste a single <script> block on any HTML page and your fully-configured chatbot appears — colors, content, behaviors, all carried over from your WordPress settings.
  • Shadow DOM style isolation: The widget renders inside an open Shadow DOM. Bootstrap, Tailwind, heavy WordPress themes, or no framework at all — the chatbot looks identical everywhere because host CSS literally cannot cascade in.
  • Multi-Bot deployment: With the Multi-Bot add-on, each bot gets its own embed snippet. Deploy a sales bot on your pricing page, a support bot in your help center, and a general bot on the homepage — all from one WordPress install.
  • CORS domain whitelisting: Configured allowed origins are validated on every request. Wildcard subdomains and localhost are supported for dev. Unauthorized sites are blocked server-side, not just in the browser.
  • No client-side secrets: API keys, system prompts, and model configuration stay on the WordPress server. The embed script only carries the public site key and your REST API base URL.
  • Streaming chat support: Full SSE streaming via /mxchat-embed/v1/stream, identical to the in-WordPress experience. Non-streaming JSON fallback at /mxchat-embed/v1/chat.
  • Email collection and quick questions: Carry through from your WordPress settings — email gating, popular question chips, send-button customization all render in the embedded widget.
  • Session persistence: Chat history persists across page loads via localStorage, so visitors can resume a conversation as they navigate between pages on the host site.
  • Lightweight vanilla JS: No jQuery, no dependencies. Loader is ~20 lines, widget is a self-contained module. Loads asynchronously so it never blocks the host page render.
  • Smooth load-in: The floating button fades in after styles are ready — no FOUC. Pre-chat messages display after CSS resolves and open the chatbot when clicked.

API & Integration

REST endpoints (all under https://yoursite.com/wp-json/mxchat-embed/v1/):

  • GET /loader.js?key=KEY — Bootstrap loader script (loaded by the snippet you paste).
  • GET /widget.js?key=KEY — Full widget JavaScript.
  • GET /config?key=KEY[&bot=ID] — Bot configuration as JSON (colors, content strings, feature flags, popular questions).
  • GET /assets/chat-style.css — Combined core + embed CSS.
  • GET /assets/theme.css?key=KEY — Dynamically generated theme CSS.
  • POST /chat — Non-streaming chat. Requires X-MxChat-Key header.
  • POST /stream — Streaming chat via SSE. Requires X-MxChat-Key header.
  • POST /email — Email collection. Requires X-MxChat-Key header.
  • POST /history — Conversation history. Requires X-MxChat-Key header.

Embed snippet format:

<script src="https://yoursite.com/wp-json/mxchat-embed/v1/loader.js?key=YOUR_SITE_KEY" async></script>

Per-bot variant (requires the Multi-Bot add-on):

<script src="https://yoursite.com/wp-json/mxchat-embed/v1/loader.js?key=YOUR_SITE_KEY&bot=BOT_ID" async></script>

CORS configuration: The MxChat_Embed_Cors class validates the Origin header against your configured allowed domains and handles OPTIONS preflight requests automatically. Allowed methods: GET, POST, OPTIONS. Allowed headers: Content-Type, X-MxChat-Key. Cache max-age: 24 hours.

JavaScript API: Once loaded, the global MxChatWidget object exposes init(), plus the queued command pattern (window.mxchat('open'), window.mxchat('close')) for programmatic open/close from host-page event handlers. Pair with the MxChat Triggers add-on for data-mxchat-trigger attributes and window.mxchatOpenAndSend('message') from any host-page element.

Requirements

  • MxChat (mxchat-basic): Required, installed and active on the same WordPress install. The host site (Shopify, Wix, etc.) does not need WordPress — only the WP install hosting the bot does.
  • MxChat Pro License: Required, activated. The plugin loads only license-active features; without an active license it shows an admin notice and stays dormant. See pricing.
  • WordPress: 5.8 or newer.
  • PHP: 7.4 or newer.
  • Target site: Must allow third-party <script> tags. Some locked-down CMSes (e.g. low-tier Squarespace plans, Wix Free) restrict custom scripts — check your plan's code-injection policy.
  • Host WordPress reachability: Your WordPress REST API must be publicly reachable from the target site visitor's browser. Sites behind IP allowlists or a private VPN will block embedded chat traffic.

Troubleshooting

CORS errors in the browser console ("blocked by CORS policy")

The host site's origin isn't in your Allowed Domains whitelist. Open MxChat → Embed Widget, add the exact origin (scheme + hostname, e.g. https://shop.example.com), save, and reload the host page. For staging and production on different domains, add both. For dev work, add http://localhost:3000 (or whichever port).

Widget doesn't appear, no console errors

Verify the Embed Widget Enabled toggle is on, and that the script src URL resolves (open it in a new browser tab — you should see JavaScript, not a 404 or a JSON error). If it returns embed_disabled or invalid_key, regenerate the site key in the admin and re-paste the snippet on the host site.

"Session expired" on the second message

This was a bug fixed in 2.0.2. Make sure you're running mxchat-embed 2.0.2 or newer — the fix keeps session ownership stable across requests where REMOTE_ADDR varies (Cloudflare, proxies, mobile carriers).

Host site CSS interfering with the chatbot

This shouldn't happen — the widget renders inside a Shadow DOM, which is a hard style boundary. If you see leakage, you may be looking at the floating button itself (which lives outside the shadow root by design, so the host page can still detect and style it for accessibility tools). Open browser DevTools and inspect: anything inside #mxchat-shadow-host should be sealed off. If host styles really are cascading in, check that your host site isn't injecting an aggressive * { ... } rule with !important on :host — extremely rare, but possible with some legacy themes.

"error processing request" on cross-origin chats

Fixed in 2.0.1 — CORS headers were missing on /chat and /history. Confirm you're on 2.0.1 or newer. If you still see it after updating, double-check that no security plugin (Wordfence, iThemes Security) is stripping CORS response headers.

Embed snippet works locally, fails in production

Almost always the allowed-domains whitelist. Production sites use a different origin than localhost — add the production domain to the whitelist. If you've migrated WordPress hostnames (staging → prod), regenerate the site key after the migration and re-paste the snippet.

Last reviewed by Sage on 2026-05-21. Spotted an issue? Open a ticket and we'll patch the doc.

Wait! Don't Miss 15% Off

MxChat Pro: $59.47 (was $69.97)
MxChat Agency: $148.69 (was $174.97)
Agency Plus: $237.97 (was $279.97)

Limited Lifetime License Offer