MxChat Core

The free MxChat plugin — the AI chatbot itself, plus everything that powers it: setup, AI models, the knowledge base, behavior, actions, display, and the REST API. Add-ons extend this core; this page documents the core itself.

Overview

MxChat turns any WordPress site into an AI chatbot that answers from your content. It runs on your server, connects to the AI provider of your choice, and answers visitor questions using a knowledge base you control — no per-message fees, no data leaving your stack except the calls you make to your chosen AI provider.

Core capabilities:

Bring-your-own AI — OpenAI, Anthropic Claude, Google Gemini, xAI Grok, DeepSeek, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, Azure OpenAI).
RAG knowledge base — index your pages, posts, PDFs, and custom text so the bot answers from your real content.
A guided setup wizard that walks you from "just installed" to "live on my site."
Actions — let the bot do things (capture emails, search the web, generate images, hand off to a human) not just answer.
A REST API for headless access to transcripts and knowledge.

Getting Started

When you first open MxChat in your WordPress admin, you land on the Onboarding wizard. It walks you through setup one step at a time:

Chat model — pick your AI provider and model, and paste your API key inline.
Behavior — tell the chatbot how to act (its role, tone, and the topics it should stick to). Optional — you can use the AI's defaults and refine later.
Embedding model — pick the model used to index your knowledge base. If it's the same provider as your chat model, your key is reused automatically.
Knowledge base — optionally add your first content so the bot has something to answer from. You can skip this and build it later.
Actions — optionally enable Actions (see below). Skippable.
You're set up — test the bot in your dashboard, turn it on for your site, or grab an embed shortcode.

You can reopen the setup guide any time from Settings → Tutorials.

AI Models & Providers

Choose your chat model under Settings → AI Models → Select AI Model. MxChat supports:

OpenAI — the GPT-5 family (including GPT-5.5, GPT-5.4, and the GPT-5.x Chat models).
Anthropic Claude — the Opus, Sonnet, and Haiku families, including Claude Fable 5 (the newest flagship, added in 3.2.9) and Claude Opus 4.8.
Google Gemini — the Gemini 3.x lineup (3.5 Flash, 3.1 Pro, and more) plus Gemini 2.5.
xAI Grok — Grok 4 and Grok 3 families.
DeepSeek and Custom (OpenAI-compatible) endpoints for local or self-hosted models.

Add your API key for each provider you use under Settings → API Keys. MxChat detects a saved key and confirms it inline. You can switch models at any time; the model you pick is the one used for live chat answers.

The model list refreshes as providers ship new models. If a provider retires a model you had selected, MxChat automatically falls back to a current, working model on your next admin load — you're never stranded on a dead model.

Custom & Azure OpenAI endpoints. Point MxChat at any OpenAI-compatible endpoint — Ollama, LM Studio, vLLM, llama.cpp, or Azure OpenAI — under Settings → API Keys → Custom Provider. Set the Base URL, API key, and auth scheme (Azure also takes an API version), then use the one-click Test Connection button to confirm it works; a built-in Azure OpenAI quick-start lists the exact values to paste. You can also route your knowledge-base embeddings through the same endpoint by enabling "use custom provider for embeddings" — indexing and live queries then use your endpoint's embedding model.

The Knowledge Base (RAG)

The knowledge base is what makes your chatbot know your stuff. Under Settings → Knowledge you can:

Auto-sync your posts and pages so published content is indexed automatically.
Upload PDFs and Word documents to extract and index their text.
Add manual entries — paste any text you want the bot to know.
Index content from a sitemap.

By default MxChat stores embeddings in your WordPress database. For larger knowledge bases you can switch to Pinecone or OpenAI Vector Store under the Knowledge page.

If you ever change your embedding model — including enabling a custom provider for embeddings — re-index your whole knowledge base (Knowledge → Process Selected) so your stored vectors and your query vectors come from the same model. A model mismatch between indexing and querying is the most common reason the bot seems to "ignore" content you've added.

Tune retrieval under Settings → Behavior: the Similarity Threshold controls how strict content matching is, and the RAG Sources / Chunks limits control how much context is sent to the AI per answer.

Behavior & System Instructions

Under Settings → Behavior, the AI Instructions field is the chatbot's "job description" — the instructions it follows on every reply (its role, tone, and guardrails). This is the highest-leverage setting for making the bot sound like your brand.

Other behavior controls:

Contextual Awareness — let the bot reference the current page's content for more relevant answers.
Citation Links — allow the bot to include source links from your knowledge base.
Satisfaction Rating — show a 👍 / 👎 prompt after a conversation so you can measure answer quality.
Message limits — cap how many messages visitors can send per hour, day, week, or month. Set a limit per user role (including logged-out visitors), or a single total cap across everyone, each with a live usage readout ("10 of 200 used · 190 left · resets in ~6 hours") and a one-click reset. Limits accept any whole number, not just the presets; the default is Unlimited, so existing sites are unchanged until you set one.

Actions

Actions let your chatbot do things, not just answer. When a visitor's message matches phrases you set up, the bot can run an Action instead of generating a plain reply. The free core includes:

Loops Email Capture — collect a visitor's email into your Loops mailing list.
Brave Web Search and Brave Image Search — search the web and images from chat.
Generate Image — create an image with OpenAI (GPT Image) or Google (Imagen).
Chat with PDF — answer questions about an uploaded PDF.
Live Agent Handoff — transfer the conversation to a human on Slack or Telegram, and hand it back to the bot when done.

Configure Actions under Settings → Actions. Many add-ons (WooCommerce, Forms, Perplexity, and more) register additional Actions.

Slack Live Agent Handoff

The Live Agent Handoff Action lets a visitor escalate from the AI to a real person. When it fires, MxChat spins up a dedicated Slack channel for that conversation, invites your agents, and posts the chat so far. Your team replies inside Slack and every reply is relayed straight back to the visitor's chat window — there's no separate agent dashboard to watch.

How it works: a visitor's message matches a trigger phrase, so MxChat creates a public Slack channel named after the chat session and invites your agent User IDs. It posts a New Live Agent Request with the session ID and the last few messages of context. Agents reply in that channel, and MxChat relays each reply back to the visitor through /wp-json/mxchat/v1/slack-messages. The session stays in live-agent mode until it's handed back to the AI.

Step 1 — Download the Slack app manifest

Download the ready-made app manifest. It pre-fills the bot user, permission scopes, and request URLs so you don't have to configure them by hand:

Download website-to-slack.txt

Step 2 — Create the Slack app from the manifest

Go to api.slack.com/apps and click Create New App → From a manifest.
Choose your workspace, open the YAML tab, and paste the contents of website-to-slack.txt.
Replace both https://example.com placeholders with your own domain, so the URLs read https://YOUR-SITE.com/wp-json/mxchat/v1/slack-messages and https://YOUR-SITE.com/wp-json/mxchat/v1/slack-interaction.
Click Create, then Install to Workspace and approve the permissions.

Step 3 — Copy your Bot Token

Open OAuth & Permissions and copy the Bot User OAuth Token — it starts with xoxb-. While you're in the app settings, also grab the Signing Secret from Basic Information → App Credentials.

Step 4 — Connect Slack in WordPress

In your WordPress admin, go to Settings → Integrations → Slack and fill in:

Live Agent Status — turn it On.
Slack Bot OAuth Token — the xoxb-… token from Step 3.
Slack Agent User IDs — the member ID of each agent who should be pulled into chats, one per line (e.g. U1234567890). In Slack, open a profile, then More → Copy member ID.
Slack Secret Key — your app's Signing Secret; it verifies that incoming requests really came from Slack.
Slack Webhook URL — your Incoming Webhook URL, used for agent notifications.
Notification Message — what the visitor sees once an agent has been pinged.
Away Message — shown when Live Agent is off, so the bot keeps helping on its own.

Then click Test Slack Connection to confirm the token authenticates and can create channels.

Step 5 — Turn on the handoff Action

Go to Settings → Actions, enable Slack Live Agent, and add the trigger phrases that should escalate a chat — for example "talk to a human", "speak to an agent", or "live support". Save, and the handoff is live.

Required OAuth scopes

The manifest already grants everything the integration needs. If you ever build the app by hand instead, add these Bot Token Scopes under OAuth & Permissions → Scopes, then reinstall the app:

channels:manage · channels:read · chat:write · chat:write.public · groups:write · users:read

The manifest grants a slightly wider set — it also adds commands, im:write, incoming-webhook, app_mentions:read, channels:history, and groups:read — so every handoff feature works out of the box. When in doubt, use the manifest.

Troubleshooting Slack handoff

Nothing happens when a visitor asks for an agent — confirm Live Agent Status is On, the Bot OAuth Token is saved, and the Slack Live Agent Action has trigger phrases. Run Test Slack Connection.
Agents aren't added to the channel — make sure the Agent User IDs are member IDs (they start with U), one per line, and that the app has the channels:manage and channels:read scopes.
Agent replies don't reach the visitor — in Slack, check that the Event Subscriptions request URL points to https://YOUR-SITE.com/wp-json/mxchat/v1/slack-messages and shows as Verified.

Displaying the Chatbot

Turn the chatbot on for your whole site under Settings → Display → Auto-Display Chatbot, or place it manually with a shortcode:

[mxchat_chatbot floating="yes"] — a floating widget in the bottom corner.
[mxchat_chatbot floating="no"] — an inline embedded chat anywhere on a page.

The Display tab also controls chat persistence, link behavior, the chat window's text and labels, and appearance. To deploy the same chatbot on a non-WordPress site, see the MxChat Anywhere add-on.

Visitors can save a conversation with the Download Transcript item in the chat window menu. Show or hide it under Settings → Display → Visibility → Show Download Transcript Button (on by default). While the bot is streaming an answer, the send button becomes a Stop control — click it to end the stream and keep the partial reply.

The floating launcher button is fully keyboard-operable: Tab to focus it, Enter or Space to open the chat, and Esc to close it — focus returns to the launcher on close (WCAG 2.1 Level A).

REST API

MxChat exposes a bearer-token-authenticated REST API for headless access. Generate and manage your token under Settings → API Access. Endpoints cover reading and deleting chat transcripts, pushing knowledge, and a health check. The chat widget itself also fetches a fresh per-request security token from /wp-json/mxchat/v1/nonce, which keeps the first message reliable even behind full-page caches.

For a Model Context Protocol (MCP) interface to your install — so Claude, ChatGPT, and other agents can talk to MxChat natively — see the MxChat MCP Server add-on.

Troubleshooting

"Invalid API key" / no replies — re-check the key under Settings → API Keys; make sure it matches the provider of your selected chat model.
Bot doesn't know my content — confirm the content is indexed under Settings → Knowledge, and that an embedding model + key are configured. Lower the Similarity Threshold if good content isn't being matched.
"Access denied" on the first message behind a cache — make sure you're on the current version; MxChat fetches a per-request nonce that resolves this for WP Rocket, LiteSpeed, FlyingPress, W3 Total Cache, and Cloudflare APO.
A model shows an error after a provider change — MxChat auto-recovers retired models on the next admin load; if a specific model errors, re-select a current one under Select AI Model.
An occasional dropped or failed reply — MxChat automatically retries on transient provider errors (5xx, rate-limit, and overload responses) for both streaming and standard chat, so brief provider hiccups usually recover on their own without a visible error.

Still stuck? Ask the Documentation Bot — it has access to the full MxChat source and every plugin's docs — or open a ticket.

Last reviewed 2026-06-17 (MxChat core 3.2.9) — added the Slack Live Agent Handoff setup guide. Spotted an issue? Open a ticket and we'll patch the doc.