Maqsy: FAQ Manager and AI Chat

Description

Maqsy lets you write and organise frequently asked questions as a dedicated
post type, then place any FAQ on a page with a shortcode or a block. Each FAQ
outputs clean, accessible markup plus FAQPage JSON-LD structured data so search
engines can understand it.

It also ships an optional AI chat widget: a small floating button that, when
a visitor clicks it, lazy-loads a chat UI whose answers are grounded in your
published FAQs. The chat feature is off by default and does nothing until you add
an API key.

FAQ management

• FAQs are a private custom post type (maqsy) — not publicly browsable on their own.
• Each FAQ holds an ordered list of question/answer pairs, edited with a drag-to-reorder UI and the standard WordPress editor for answers.
• Two display templates: Simple (a definition list) and Accordion (WAI-ARIA disclosure pattern with keyboard support).

Placing a FAQ

Shortcode:

[maqsy id="123"]
[maqsy id="123" template="accordion"]

Block: insert the FAQ block, pick a FAQ, and optionally override the template.
Both render through the same code path.

Structured data

On singular views, each rendered FAQ emits schema.org/FAQPage JSON-LD built from
its question/answer text. Output is limited to singular views (not archives,
feeds or search) to follow Google’s one-FAQPage-per-URL guidance.

AI chat widget (optional)

Configure a provider and API key under FAQs → AI Chat Settings and turn on
“Enable AI chat”. The always-loaded launcher script is tiny; the chat
interface is only downloaded when a
visitor actually opens the chat. Answers are grounded in your published FAQs plus
any site/branding instructions you enter in settings, and the public endpoint is
rate-limited per IP.

The built-in provider works with any OpenAI-compatible /chat/completions API
(OpenAI, OpenRouter, or a self-hosted compatible endpoint — you choose the base
URL). Other plugins can register additional providers via the
maqsy_ai_providers filter.

External services

This plugin’s AI chat feature is optional and disabled by default. It does
not contact any external service unless a site administrator enables the AI chat
and saves an API key.

When the AI chat is enabled and a visitor sends a message, the plugin makes a
server-to-server request to the AI API endpoint you configure (“API base URL” in
settings). By default this is OpenRouter (https://openrouter.ai/api/v1); you
can change it to OpenAI (https://api.openai.com/v1) or any other
OpenAI-compatible endpoint.

What is sent, and when:

• On each visitor chat message: the visitor’s message text, the text of your published FAQ posts, and any “Site & branding instructions” you entered — sent to the configured endpoint together with your API key, so the model can generate a reply.
• When an administrator clicks “Fetch models” on the settings page: a request to the endpoint’s /models route, authenticated with the API key entered in the form.

No data is sent to the plugin’s author or to WordPress.org. The plugin does not
add analytics, tracking, or telemetry.

Because you choose the endpoint, review the terms and privacy policy of whichever
provider you configure. For the two presets:

• OpenRouter — Terms: https://openrouter.ai/terms ; Privacy: https://openrouter.ai/privacy
• OpenAI — Terms: https://openai.com/policies/terms-of-use/ ; Privacy: https://openai.com/policies/privacy-policy/

Source code and build process

Compiled assets in build/ are generated from the human-readable sources
included in this package:

• src/ — admin, front-end and block scripts/styles, built with @wordpress/scripts (webpack). See webpack.config.js.
• chat-runtime/src/ — the lazy-loaded chat UI (React 19 + TypeScript), bundled with esbuild, and its Tailwind stylesheet. See package.json and tailwind.config.js.

To build from source:

npm install
npm --prefix chat-runtime install
npm run build

Development repository: https://github.com/sijad/maqsy-faq-ai-chat

Bundled third-party libraries in the chat bundle (all MIT-licensed): React and
ReactDOM, scheduler, use-sync-external-store, @floating-ui, @shadcn/react, clsx,
tailwind-merge.