AI FAQ Manager

1. Introduction

AI FAQ Manager turns FAQ management into a breeze. Instead of pasting shortcode snippets or hand-writing JSON-LD, you get a complete FAQ workspace inside wp-admin: a dedicated FAQ post type, per-item editing with drag & drop ordering, AI-powered question generation from your existing content, groups for organization, five display styles, a native Gutenberg block with a live preview, and automatic FAQPage schema output.

Every FAQ item receives a stable unique ID, so items can be deep-linked (…/page/#afqm-4f2a9b1c8d auto-expands the item) and referenced individually via shortcode.

2. Feature List

3. Requirements

4. Installation

Method A — WordPress admin (recommended)

1. In wp-admin go to Plugins → Add New → Upload Plugin.
2. Choose ai-faq-manager.zip and click Install Now.
3. Click Activate Plugin.

Method B — FTP

1. Unzip ai-faq-manager.zip.
2. Upload the ai-faq-manager folder to /wp-content/plugins/.
3. Activate the plugin in Plugins.

On activation the plugin registers the FAQ post type and FAQ Groups taxonomy, flushes rewrite rules and stores default settings. No data is deleted on deactivation.

5. Quick Start

1. Open FAQ Manager → Settings and paste your OpenAI or Gemini API key (see section 6).
2. Click Test Connection — you should see "Connection successful!".
3. Edit any post, page or product and use the FAQ Items meta box: add items manually or click Generate FAQs with AI.
4. Save the post — FAQs appear automatically at the bottom (Auto-display is on by default), and JSON-LD schema is output if enabled.
5. Optional: insert the FAQs Gutenberg block anywhere for full control over style, colors and source.

6. Getting an API Key

The plugin talks directly from your server to the AI provider. Your key is stored in your own WordPress database and is never sent anywhere except the provider you choose.

7. The Admin Interface

After activation you get a FAQ Manager menu in wp-admin with a dedicated, app-style UI:

• FAQs — the FAQ list table with a hero header and live stats (FAQ posts, total Q&A items, groups, content using FAQs). Columns: Shortcode (click to copy), FAQ Items (sortable), Last Modified (sortable).
• Groups — manage FAQ Groups, with the same stats dashboard and a usage tip.
• Settings — four tabs (AI Provider, Display, Generation, Advanced) with an AJAX save, an unsaved-changes guard and persistent active tab.
• A top bar with brand navigation and a Back to WordPress button; the surrounding admin chrome is hidden on plugin screens.

On regular posts/pages/products you get the FAQ Items meta box plus a dismissible notice reminding you to set an API key (admins only).

8. Creating FAQs

FAQs in this plugin are organized in two layers:

1. FAQ posts (post type afqm_faq) — containers with a title that live under FAQ Manager.
2. FAQ items — the individual question/answer pairs stored on a FAQ post (or on any post, page or product via the meta box).

Add a FAQ post

1. Go to FAQ Manager → Add New FAQ.
2. Enter a title (e.g. Shipping Questions). The title identifies the collection; it can also be the "source post" for the Gutenberg block.
3. In the FAQ Items meta box click Add FAQ Manually and fill in the question and answer. Answers accept basic HTML (links, bold, lists — sanitized with wp_kses_post).
4. Drag items by the handle to reorder. Each item shows its stable ID, e.g. afqm-4f2a9b1c8d, usable as an anchor and in the item shortcode attribute.
5. Assign FAQ Groups (optional) and publish.

Attach FAQs to a post, page or product

Open any supported content and use the same FAQ Items meta box. Items added there display on that content (via auto-display, a shortcode, or the block). To get a ready-made shortcode for the current post, use the AI FAQ Manager Gutenberg sidebar (section 13).

9. AI Generation

Where you can generate

What is sent to the AI

By default the post title + first 300 words of content are sent to the selected provider, with an instruction to return a JSON object of the form {"faqs":[{"question":"...","answer":"..."}]}. Responses are validated and sanitized before display.

Custom prompt

Settings → Generation → Custom Prompt. Available placeholders:

Reliability

• Transient API errors (e.g. 5xx/timeouts) are retried automatically up to 2 times with exponential backoff; auth errors (401/403) fail fast.
• Requests are throttled client-side to at most one per second to avoid accidental loops.
• Malformed model output is parsed defensively (raw JSON, fenced JSON, or the first JSON array/object found). Both a top-level JSON array and the {"faqs":[...]} object wrapper are accepted.

10. Settings Reference

Open FAQ Manager → Settings. Settings are saved with AJAX (a toast confirms the save) and the active tab is remembered in the URL.

Tab: AI Provider

Tab: Display

Tab: Generation

Tab: Advanced

11. Displaying FAQs

There are four ways to show FAQs on the frontend:

1. Auto-display — items stored on the current post/page/product are appended below the content (Settings → Display → Auto-display).
2. Shortcodes — [afqm_faqs] and [afqm_faq], anywhere (content, widgets, page builders that process shortcodes). See section 12.
3. Gutenberg block — the FAQs block with a live preview and per-block style/color/source controls. See section 13.
4. FAQ post pages & archives — every FAQ post has its own permalink page showing its items, and there is a FAQ archive at /faqs/ plus group archives at /faq-group/….

Behavior details

• Accordion — one item open at a time; Toggle — items open independently.
• Grid — 1–4 columns, collapses to a single column under 768px.
• Floating Bubble — fixed bottom-corner widget with live question search, outside-click-to-close and a "Powered by" footer.
• Deep links — appending an item's ID as a hash (e.g. #afqm-4f2a9b1c8d) scrolls to the item, auto-expands it, and even opens the bubble widget if the item lives inside one.
• Keyboard support — ArrowUp/ArrowDown/Home/End move focus between accordion and toggle buttons.
• Performance — CSS/JS are only enqueued on pages that actually contain FAQs (auto-display, shortcode, block, or FAQ archives).

12. Shortcode Reference

[afqm_faqs] — collection of items

Renders the items of all published FAQ posts (optionally filtered by group), merged into one display.

[afqm_faqs group="shipping" style="accordion" color="blue" columns="2" limit="-1" order="ASC" orderby="menu_order"]

If nothing matches, a localized "No FAQs found." message is shown.

[afqm_faq] — a single FAQ post (or single item)

[afqm_faq id="123"]
[afqm_faq id="123" item="afqm-4f2a9b1c8d" style="toggle"]

13. Gutenberg Block & Sidebar

The "FAQs" block (afqm/faqs)

Insert the FAQs block from the Widgets category. The editor shows a live, interactive server-rendered preview (iframe-based, compatible with modern WordPress block editors).

The "AI FAQ Manager" sidebar

Available in the block editor of every supported post type:

• AI Generation — generate FAQs from the current content, save them into the post meta, with status feedback.
• Shortcode — a click-to-copy [afqm_faq id="…"] for the current post (once saved) plus a tip about the [afqm_faqs] collection shortcode.

14. FAQ Groups

FAQ Groups are a hierarchical taxonomy — like categories — under FAQ Manager → Groups. Use them to organize FAQ posts (e.g. Shipping, Returns, Pricing) and to filter the collection shortcode:

[afqm_faqs group="shipping"]

Groups also have public archive pages at /faq-group/{slug}/ listing their FAQ posts. The Groups screen shows the same stats dashboard as the FAQ list.

15. Import / Export

Export

Settings → Advanced → Export All FAQs (JSON) downloads a file like:

{
  "version": "2.0.3",
  "exported": "2026-09-18 10:30:00",
  "faqs": [
    {
      "title": "Shipping Questions",
      "content": "",
      "faqs": [
        { "id": "afqm-4f2a9b1c8d", "question": "How long does shipping take?", "answer": "3–5 business days." }
      ],
      "groups": ["Shipping"],
      "menu_order": 0
    }
  ]
}

Import

Choose a JSON file exported by this plugin. Every entry with a title and at least one valid item becomes a new published FAQ post (groups are created and assigned as needed). The result reports how many were imported and lists any skipped entries. Items keep their stable IDs, so anchors keep working across sites.

16. SEO Schema (JSON-LD)

When enabled (default), the plugin outputs a FAQPage JSON-LD block in wp_head on singular pages of supported post types that have FAQ items:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How long does shipping take?",
      "acceptedAnswer": { "@type": "Answer", "text": "3–5 business days." }
    }
  ]
}
</script>

• Questions and answers are stripped of HTML before being added to the schema.
• The Schema Limit setting caps how many items are included (0 = all).
• The schema marks up the items attached to the page — it does not duplicate the FAQ posts' own pages' items twice.
• Validate with Google's Rich Results Test.

17. RTL & Multilingual

• RTL-ready — every item is rendered with dir="auto" so Persian, Arabic, Hebrew and mixed-language content aligns correctly regardless of the site language; the stylesheet uses logical CSS properties (padding-inline-start, inset-inline-end, …).
• Translation-ready — all strings use the ai-faq-manager text domain. A .pot template ships in /languages/; translate it with Poedit or Loco Translate.

18. WooCommerce

When WooCommerce is active, product is added to the supported post types automatically:

• Products get the FAQ Items meta box and Gutenberg sidebar.
• Product FAQs are appended below the product content when auto-display is on.
• Product FAQs are included in the FAQPage schema of the product page.

Developers can add more post types with the afqm_supported_post_types filter (section 19).

19. Developer Docs

Constants

AFQM_VERSION           // Current plugin version
AFQM_PLUGIN_DIR        // Server path to the plugin folder
AFQM_PLUGIN_URL        // URL to the plugin folder
AFQM_PLUGIN_BASENAME   // plugin_basename of the main file

Data model

Filters

Example: add a custom post type

add_filter( 'afqm_supported_post_types', function ( $types ) {
    $types[] = 'documentation';
    return $types;
} );

Example: change the schema output

add_filter( 'afqm_schema_data', function ( $schema, $post_id, $items ) {
    // e.g. cap the schema at 3 items regardless of settings
    $schema['mainEntity'] = array_slice( $schema['mainEntity'], 0, 3 );
    return $schema;
}, 10, 3 );

Frontend customization

• All frontend classes are prefixed with afqm-; the main container is .afqm-faqs.
• The Custom color scheme exposes a CSS variable: --afqm-accent. You can also set it per container to restyle any scheme:

  .afqm-color-blue { --afqm-accent: #7c3aed; }

• Display templates live in /templates/faq-*.php and render through AFQM_Helpers::render_faqs().

20. REST API

All endpoints live under the afqm/v1 namespace and require cookie authentication with a valid REST nonce (the plugin's own admin scripts handle this automatically).

21. Privacy & Data

What leaves your server, and when

• Only during explicit AI actions (single generate, bulk generate, test connection) does the plugin contact a third party: the provider configured in Settings (OpenAI or Google Gemini).
• Default payload: the post title and up to 300 words of content, wrapped in the generation prompt.
• Opt-out: enable Send only title to AI to transmit only the title, or simply don't use the AI features — nothing is transmitted without a user clicking a generate/test action.
• Provider responses are stored as FAQ items in your own database. The API key is stored in the afqm_settings option and is only used server-side in API calls.

What stays local

FAQ posts, items, groups, settings, statistics and export/import files are stored entirely in your WordPress database. The plugin has no telemetry, no tracking and no phone-home.

22. Uninstall & Cleanup

• Deactivation never deletes data — it only flushes rewrite rules and records a timestamp.
• Uninstall (delete) behavior depends on Settings → Advanced → Cleanup on Uninstall:
  • Off (default): settings timestamps are removed, but FAQ posts, items and groups are kept so you can reinstall later.
  • On: all plugin data is deleted on uninstall — FAQ posts, FAQ items attached to any content, FAQ Groups and all settings.

23. Troubleshooting

24. Changelog

1.0.0 — 2026-09

• Initial release.

2.0.0 — 2026-09

• AI generation with OpenAI & Gemini, single + bulk, custom prompt, privacy mode.
• Five display styles, seven color schemes + custom accent, floating bubble with search.
• Stable per-item IDs with deep-link auto-expand; click-to-copy shortcodes.
• Native Gutenberg block with live server-rendered preview; Gutenberg generation sidebar.
• FAQPage JSON-LD with item limit; auto-display with duplicate protection.
• FAQ Groups taxonomy, JSON import/export, opt-in uninstall cleanup.
• App-style admin UI with stats dashboard; full i18n (.pot included).

2.0.1 — 2026-10

• Fixed OpenAI response format mismatch: the API now consistently requests and parses the JSON object format {"faqs":[{"question":"...","answer":"..."}]}.
• The response parser accepts both a top-level JSON array and the {"faqs":[...]} object wrapper, so AI FAQ generation no longer fails or returns empty results.
• Test Connection now validates the test response and fails loudly instead of reporting success when no valid FAQ data was parsed.

2.0.2 — 2026-10

• Replaced retired Gemini models (1.5 Pro/Flash, 2.0 Flash) with currently supported ones: Gemini 3.5 Flash, Gemini 3.5 Flash-Lite, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite, Gemini 2.5 Pro.
• Modernized Gemini API handling: key sent via the x-goog-api-key header, proper systemInstruction, Gemini 3 sampling defaults, multi-part response extraction, and finish-reason details on empty responses.
• A saved model that is no longer supported is flagged in Settings with a prompt to choose a current one; the "Get Gemini Key" link now points to Google AI Studio.
• Product description clarified: FAQPage schema output does not imply rich-results or People Also Ask placement.
• Added the current GPT-6 family (GPT-6.1 Sol, GPT-6 Astra, GPT-6 Luna) and removed GPT models being shut down on 2026-10-23 (GPT-4 Turbo, GPT-3.5 Turbo); fresh installs now default to GPT-6.1 Sol.
• Updated the OpenAI request for reasoning models: max_completion_tokens, low reasoning effort, and no unsupported temperature, so GPT-6 generation works.

2.0.3 — 2026-10

• Fixed the shortcode copy button on the FAQ list screen: clicking it multiple times no longer copies the "Copied!" label instead of the shortcode.
• Fixed the admin toolbar overlapping the WordPress Publish controls on the FAQ edit screen: the toolbar no longer floats above WordPress publishing controls there, and the block editor offset now tracks the toolbar height continuously.

25. Support & License

Support

• Documentation: https://ascoupon.com/documentation/
• Support portal: https://ascoupon.com/support/
• Backend demo: https://ascoupon.com/demo/wp-login.php

Purchase code support covers setup help, bug fixes and questions about documented features. Customization services and third-party theme conflicts are out of scope but we'll point you in the right direction where we can.

License

Copyright © 2025 Mahmood Dabestani. This plugin is licensed under the GNU General Public License v2 or later (GPLv2+). You may use it on unlimited sites, modify it and create derivative works under the same license. OpenAI and Google Gemini are external services governed by their own terms; you are responsible for your API usage and costs.