MxChat Perplexity

Real-time web search for your MxChat chatbot, powered by the Perplexity AI API. Your bot can answer questions about current events, news, and other time-sensitive topics that fall outside its training data — and cite sources when you want it to.

Overview

MxChat Perplexity Integration is a Pro add-on for the MxChat AI Chatbot plugin. It adds a Perplexity-powered web search layer to your chatbot so visitors can ask about things that happened today, last week, or any time after the underlying model's training cutoff — and get up-to-date, factual answers back. Responses can include numbered source citations (so users can verify what they're reading) or flow as natural prose (so the chatbot sounds like it just knew the answer). Web search is triggered two ways: a toolbar toggle the user controls, or intent-based phrases ("search for...", "research...") that you train. Requires MxChat (mxchat-basic), an active MxChat Pro license, and a Perplexity API key.

Setup

Upload the mxchat-perplexity folder to /wp-content/plugins/ (or install the ZIP via Plugins → Add New → Upload).
Activate MxChat Perplexity Integration under Plugins → Installed Plugins.
Go to MxChat → Perplexity in your WordPress admin menu.
Paste your Perplexity API key (grab one at docs.perplexity.ai/guides/getting-started).
Click Test API connection to confirm the key works, pick a model and a response mode, then click Save Settings.
(Optional) Enable the Perplexity Research intent under MxChat → Actions → Trigger Phrases if you want phrase-based triggering. Train it with examples like "Search for...", "Research...", "Find information about...".
(Optional) Enable the chat toolbar under MxChat → Settings → Integrations → Toolbar so the one-click web search button appears in the chatbot.

Settings

All settings live at MxChat → Perplexity in WordPress admin (or Network Admin → Settings → Perplexity on multisite).

API Key

Your Perplexity API key. The field includes a show/hide toggle so you can verify the key without copy-pasting it elsewhere. Required for the add-on to do anything.

Test API connection sends a quick test request to Perplexity to confirm the key works. Save your key first if you just entered it.

Model

Pick the Perplexity Sonar model the chatbot should use:

Sonar (lightweight web search) — the default.
Sonar Pro (deeper retrieval, more sources)
Sonar Reasoning Pro (reasoning + search)
Sonar Deep Research (long-form, source-dense) — can take several minutes per response.

From 1.0.10, a saved model that Perplexity has removed (for example the older Sonar Reasoning, pplx-* or llama-3.1-sonar-* ids) is moved to Sonar automatically, and MxChat shows a notice listing the change. Pick a different model and save if Sonar is not what you want.

Limit search to domains

Restricts Perplexity's web search to the domains you list, one per line (for example yoursite.com). Leave it blank to search the whole web. Up to 20 domains. Prefix a domain with a minus sign (-example.com) to exclude it instead. A list must be all include or all exclude; a mixed list is rejected and your previous list is kept. Add my site domain fills in your own site's domain.

Response Mode

Controls how search results are rendered in the chat:

Conversational — Natural-sounding prose, no citation numbers. The bot answers like it already knew.
Structured — Formatted content with numbered source citations and clickable links at the bottom.

Default: Conversational.

From 1.0.11, when citation links are turned off in MxChat's own settings, web search answers in either mode show no citation numbers or source addresses. Structured answers no longer have blank gaps around the intro, lists or code, and with MxChat 3.2.27 or later they stay one message after a page reload, in transcripts and in MxChat Anywhere.

Show Perplexity Logo

Toggle the Perplexity search button on or off in the chatbot toolbar. Turn it off if you want web search available only through intent matching (no visible toggle in the UI). Default: shown.

From 1.0.10, toolbar web search runs only while visitors can actually see the button: Show Perplexity Logo is on and the chat toolbar is enabled under MxChat → Settings → Integrations → Toolbar. If either is off, a message is answered as a normal chat, even if the visitor's browser still has web search switched on from an earlier visit.

Features

Real-Time Web Search: The bot pulls live information from the web, so answers about news, current events, and time-sensitive topics stay accurate rather than capped at the model's training cutoff.
Two Response Modes: Conversational delivers flowing prose with no citations; Structured returns formatted HTML with numbered source links so users can verify the answer themselves. You pick the default in settings.
One-Click Web Search Toggle: A Perplexity button in the chat toolbar routes every message through web search until the user clicks it off again. The toggle state persists across page loads via localStorage.
Intent-Based Triggering: Train the built-in "Perplexity Research" intent with phrases like "search for..." or "research..." and matching messages route to web search automatically — no toggle required.
Four Perplexity Models: Sonar (default), Sonar Pro, Sonar Reasoning Pro and Sonar Deep Research. Switch models per site from the settings page. A removed model is moved to Sonar automatically (1.0.10+).
Domain filter: Limit web search to up to 20 domains, or exclude specific domains.
Keeps your chatbot's instructions (1.0.10+): A web-search reply starts from the chatbot's own instructions (a Multi-Bot bot's own instructions where set), so it keeps the bot's persona and rules.
Counts toward chat limits (1.0.10+): Each web search counts toward MxChat's chat limits, including per-role and per-bot limits, and a visitor over the limit sees MxChat's usual limit message.
Smart Timeout Handling: Standard models get a 30-second timeout; Deep Research gets up to 5 minutes. Complex queries have time to finish without false failures.
Chain-of-Thought Cleanup: Reasoning and Deep Research models often emit internal "thinking" steps. The plugin strips those out automatically so users only see the polished final answer.
Show/Hide Perplexity Logo: Hide the toolbar button when you want web search to be intent-only and invisible to users.
Lighter page loads (1.0.11+): With MxChat's delayed chat loading, the web search script no longer loads jQuery before the visitor interacts, also when the Image Analysis add-on is active.
Multisite Compatible: Works on WordPress multisite, checking both network-wide and site-specific MxChat Pro license activation.

API & Integration

- Perplexity Sonar API — Outbound HTTPS calls to api.perplexity.ai with your API key. The plugin selects model + timeout based on your settings and sends a system prompt tuned to the chosen response mode.
- Callback registered: mxchat_handle_perplexity_search is added to mxchat_available_callbacks as a Pro-only intent labeled "Perplexity Research" under the "Search Features" group. Use it from MxChat's Intents tab to wire phrase-based triggering.
- Filters:
- mxchat_handle_perplexity_search — invoked when a message is routed to Perplexity (intent match or toggle on).
- mxchat_pre_process_message — the plugin hooks this to detect whether web search mode is active for the current message.
- mxchat_perplexity_should_show_logo — return false to hide the toolbar button programmatically.
- AJAX endpoints: wp_ajax_mxchat_perplexity_search and wp_ajax_nopriv_mxchat_perplexity_search; calls are nonce-protected (mxchat_perplexity_nonce). From 1.0.10 the endpoint answers Web search is not available on this chatbot. unless the button is shown, and checks MxChat's chat limits before calling Perplexity.
- Citation rendering — In Structured mode, source URLs are appended to the response as a numbered, clickable link list. In Conversational mode, markdown headings are flattened to bold and citations are stripped. From 1.0.11, with core's citation links setting off, citation numbers and source addresses are removed in both modes.

Requirements

MxChat (mxchat-basic): Required and active. Plugin shows an admin notice if mxchat-basic isn't detected on the site (or network on multisite).
MxChat Pro License: Required. Without an active Pro license the admin shows a warning notice and no Perplexity functionality loads. See mxchat.ai/pricing/.
Perplexity API Key: Required. Sign up at docs.perplexity.ai/guides/getting-started.
WordPress: 5.8 or newer.
PHP: 7.4 or newer.

Troubleshooting

"API quota exceeded" or 429 errors from Perplexity

You've hit your Perplexity plan's rate limit or monthly credit cap. Check usage at perplexity.ai/settings/api. If you're on Deep Research and getting quota errors fast, switch to Sonar Pro — Deep Research consumes significantly more credits per query.

Web search isn't triggering

Three things to check:
1. Is your MxChat Pro license active? If the Perplexity admin page shows a yellow "Pro required" notice, license activation is the issue — visit MxChat → Pro & Extensions.
2. Is the API key saved? Empty key = silent fallback to the normal chatbot response.
3. If you're relying on intent matching, confirm the "Perplexity Research" intent is enabled in MxChat → Actions → Trigger Phrases and that you've trained it with at least 3-5 example phrases.

Citations don't render / show as raw text

You're probably in Conversational mode, which intentionally strips citations. Switch Response Mode to Structured in settings and save. From 1.0.11 citations are also hidden in both modes when citation links are turned off in MxChat's own settings, so check that setting too. If you're already in Structured mode and citations still look broken, clear any chatbot front-end caching plugin and hard-reload the page.

Web search replies say the limit was reached

From 1.0.10 each web search counts toward MxChat's chat limits. Raise the limits in MxChat's settings if regular visitors hit them.

A structured answer splits into several messages after a reload

Update to 1.0.11 and MxChat 3.2.27 or later. Both are needed for a structured answer to stay one message after a page reload, in transcripts and in MxChat Anywhere.

Deep Research requests time out

Deep Research can legitimately take up to 5 minutes for complex prompts. The plugin sets the timeout high enough, but your hosting environment's PHP max_execution_time or front-end proxy (Cloudflare, etc.) may cut the request short. Bump server timeouts or switch to a faster Sonar model.

Make sure the MxChat chat toolbar is enabled under MxChat → Settings → Integrations → Toolbar — the Perplexity button is a toolbar item. Also confirm the Show Perplexity Logo setting is on. Both are also required for toolbar web search to run at all from 1.0.10. If the button still doesn't show, the front-end JS may have failed to enqueue; check the browser console for mxchatPerplexity and verify your theme isn't blocking front-end scripts.

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