• Installing FAQ

• Installing Hyvä Theme Compatibility Module

• Uninstalling FAQ

• Extension Compatibility 

• Introducing to Magento 2 FAQ

• Using Magento 2 FAQ 

   

  • Extension Configuration

  • Content Management

    • FAQ Categories

    • FAQ Articles

      • Create New/Edit Article

  • Chatbot Configuration

    • Backend Setup

    • Frontend Experience

   

• FAQ Storefront Experience

  • • FAQ on Landing Page 

    • FAQ on Product Pages

Installing FAQ

Command Line Installation

1. Backup your web directory and store database

2. Download the FAQ installation package

3. Upload contents of the FAQ installation package to your store root directory

4. In SSH console of your server navigate to your store root folder:

cd path_to_the_store_root_folder

run the following command:

php bin/magento module:enable Aheadworks_Faq

php bin/magento module:enable Aheadworks_FaqGraphQl

php bin/magento module:enable Aheadworks_ChatBot

php bin/magento module:enable Aheadworks_FaqSearch

then:

php bin/magento setup:upgrade

after:

php bin/magento setup:static-content:deploy -f

5. Flush store cache; log out from the backend and log in again

Composer Installation

If you are installing an extension from Aheadworks for the first time, you need to add our composer repository to your Magento store:

     1. Login to your ssh console and navigate to your store folder:

cd path_to_the_store_root_folder

Run the following command:

composer config repositories.aheadworks composer https://dist.aheadworks.com/

After the command was executed successfully, you can use the composer to install the products.

To install the extension:

     2. Login to your ssh console and navigate to your store folder:

cd path_to_the_store_root_folder

      3. Run the following command to install the latest version of the extension:

composer require aheadworks/module-faq

if you need to install a specific version, run this command:

composer require aheadworks/module-faq:<version>

composer require aheadworks/module-chat-bot

composer require aheadworks/module-chat-bot: <version>

composer require aheadworks/module-faq-search

composer require aheadworks/module-faq-search: <version>

When prompted, enter Public Key (Username) and Private Key (Password):

Both Public Key (Username) and Private Key (Password) can be found in My Projects and Licenses in your personal account on our site:

     4. Enable the extension:

php -f bin/magento module:enable Aheadworks_Faq

php -f bin/magento module:enable Aheadworks_FaqGraphQl

php -f bin/magento module:enable Aheadworks_ChatBot

php -f bin/magento module:enable Aheadworks_FaqSearch

Next, register the extension:

bin/magento setup:upgrade

Recompile your Magento store if you are in the Production mode:

bin/magento setup:di:compile

To verify that the extension is enabled, run this command:

bin/magento module:status

Clean store cache, by running the following command:

bin/magento cache:clean

Log out and Log in the backend again.

To upgrade the extension:

Download the updated extension file from Marketplace or another extension developer. Take note of the module-name and version.

Export the contents to your Magento root.

Run one of the following with the composer:

Update per module name:

composer update aheadworks/module-faq

Updater per version:

composer require aheadworks/module-faq:<version>

composer update aheadworks/module-chat-bot

composer update aheadworks/module-chat-bot:<version>

composer update aheadworks/module-faq-search

or

composer update aheadworks/module-faq-search:<version>

Run the following commands to upgrade, deploy, and clean the cache.

php bin/magento setup:upgrade --keep-generated
php bin/magento setup:static-content:deploy
php bin/magento cache:clean

Installing Hyvä Theme Compatibility Module

Starting from FAQ version 1.8.0 , extension is compatible with Hyvä Theme Module version 1.1.0, the Hyvä Compatibility Module is available via the Aheadworks Composer repository.

Installing Hyvä-compatibility module 

To install Hyvä Compatibility Module via Aheadworks Composer, run the following command:

composer require aheadworks/module-faq-hyva 

Hyvä-compatibility Modules with CSP Compliance 

Starting from Hyvä Compatibility Module version 1.1.0, all Hyvä compatibility modules are CSP compliant. Older versions remain non-CSP compliant.

Note: The CSP-compliant modules may not be compatible with older versions of Hyvä Theme (1.3.9 and older). Before updating, please verify which version of the Hyvä Theme your store is using.

Uninstalling FAQ

Since Magento introduced declarative Database you need to be very carefull when uninstalling or disabling the module.

Manual Removal

1. Disable the module by executing the following commands:

php bin/magento module:disable Aheadworks_Faq php bin/magento setup:upgrade

2. Remove the extension files from the following folder:

app/code/Aheadworks/Faq

Automatic removal

To uninstall the extension, run the following command:

php bin/magento module:uninstall Aheadworks_Faq

Please note: uninstall script works correctly only if the module was previously installed via Composer

php bin/magento module:uninstall Aheadworks_ChatBot

Note for a developer:

To use the uninstall script in the standard workflow, see Magento\Setup\Console\Command\ModuleUninstallCommand::validate(). The function should return an empty array for further correct processing. You can simply comment out the lines 319-338.

Compatibility

The PHP version depends on your current Magento version. Please, refer to your Magento version release notes.

Introducing to Magento 2 FAQ

Extension Overview

Magento 2 FAQ extension introduces to the storefront the FAQ page of most frequent questions and answers. The extension helps customers find the information they need in a matter of a few clicks.  

Key Features

• Answer helpfulness rating

• Customer group restriction to access FAQ

• Search field for quick navigation around the FAQ articles

• Multi-column adjustable design of the FAQ page

• SEO instruments: meta data, canonical URLs, sitemap, FAQ article URLs

• Interactive Chat-bot with anti-spam protection

Using Magento 2 FAQ

Extension Configuration 

Proceed to Stores > Configuration > Aheadworks extensions > FAQ to configure the extension. The settings come in three sections: General, SEO and Article Helpfulness.

General settings

The General Settings section controls the behavior, layout, metadata, and availability for particular customer groups within the present extension. The following settings are available within the section:

• FAQ Name – the name of the FAQ index page to be displayed at the storefront;

• FAQ Route – the URL path to the FAQ index page and all the categories and articles;

• FAQ Main Page Meta Title – the meta title of the FAQ main page as it will appear in a search list of a web-crawler (for SEO purposes);

• FAQ Main Page Meta Keywords - the meta keywords of the FAQ main page as it will appear in a search list of a web-crawler (for SEO purposes);

• FAQ Main Page Meta Description – the meta description of the FAQ main page as it will appear in a search list below the meta title (for SEO purposes);

• Default Number of Columns on FAQ Main Page – allows adjusting FAQ category layout to 1, 2, or 3 columns;

• Enable search in articles – Yes/No to enable/disable search for FAQ pages (may not be required considering the number of available articles);

• Display Link to FAQ in the Top Menu – defines if the Storefront FAQ Name is to be displayed in the top menu along with account sign-in options;

• Display Link to FAQ in the Main Navigation – defines if the Storefront FAQ Name is to be displayed in the main navigation menu;

• Display Link to FAQ in Footer Links – defines if the Storefront FAQ Name is to be displayed at the store footer;

• Enable Ask a Question form on the article pages – defines if the Ask a Question form is to be available on an article page;

• Who can view FAQ content - a list of customer groups to specify the target audience of the FAQ (by default - ALL GROUPS).

Articles helpfulness

The Articles Helpfulness section controls the behavior of the extension with regard to the article helpfulness rating. The following settings are available within the section:

• Who Can View Helpfulness – defines customer groups that are eligible to rate articles for helpfulness;

• Display Helpfulness Rate Before Voting – defines if helpfulness rating should be displayed to all customers before they cast a vote;

• Display Helpfulness Rate After Voting – defines if helpfulness rating should still be displayed to all customers after they cast a vote.

Search Engine Optimisation (SEO)

This is where you optimize your FAQ for the best search outcomes with modern search engines. The SEO section features the following sections:

• Article URL Suffix - the character(s) to close a URL of an article page  (usually a '/', '.html' or empty);

• Category URL Suffix - the character(s) to close a URL of a category page (usually a '/', '.html' or empty);

• Create Permanent Redirect for URLs if URL Key Changed -the redirection of the preferred URLs, do not prevent showing multiple results to the visitors;

• Page Title Separator - the symbols, punctuation, and other characters used to distinguish between various parts of the page title;

• Title Prefix - the text line to start the title of a FAQ page (as included into the <title> tag);

• Title Suffix - the text line to close the title of a FAQ page (as included into the <title> tag);

• Meta Title Suffix For All Pages - the meta title suffix that can be for all pages;

• Use Canonical Link Meta Tag For Categories - decide whether you are using canonical link meta tag for category pages;

• Use Canonical Link Meta Tag For Articles - decide whether you are using canonical link meta tag for article pages.

The settings above echo those in Stores->Config->Catalog->Catalog->Search Engine Optimization. For more details on SEO practices in Magento 2 refer to the official Magento 2 use guide.

Content Management

FAQ Categories

Categories Grid 

To populate FAQ with question categories, navigate to Content > FAQ by Aheadworks > Categories. 

The page features a grid to aggregate all categories available for the FAQ. The grid shows the following columns:

• ID - the identification number of a category;

• Category Name - the name of a category (as it will appear on the storefront);

• URL Key - the closing tag of a category URL;

• Status - the status of a category (enabled/disabled);

• Store view - the store view to feature the category;

• Sort Order - a whole numeric to indicate the order of a category in the category tree on the storefront.

To add a new category, click on the Add New Category button at the top of the page. To edit a category, click on the name of the category in the grid. To delete or change the status of a category, tick the checkbox to the left of the category name and apply action from the Actions folding list above the grid (bulk action is supported too).

Create New/Edit Category

Categories represent a thematic unit of FAQ extension. Categories are suggested to contain a set of articles on a particular theme.

Category settings are split into two sections: General Settings and SEO:

• General Settings come as a list of the following parameters:

• Enable category – defines if the category is enabled on the storefront;

• Category name – defines the category name;

• URL Key – defines the category URL;

• Store View – defines the store views the category should be displayed at;

• Sort Order – defines the order in which categories are displayed at the FAQ index page;

• Number articles to display on FAQ main page – defines the number of articles displayed under the category (additional articles will be cropped by the 'Read <number of extra articles> more articles' link);

• Category icon – allows uploading an icon that will define the category;

• Article list icon – allows uploading images to be used as list points to highlight a particular category in color;

• Show Subcategories and Articles on the Category page - allows showing subcategories and articles on the category page, to disable this function untick the Use Config Settings. 

In the Content area your Admin can edit category description. The content area provides a text-box with a WYSIWYG editor to type-in and format a reply to a question, or to provide information on the topic. 

• SEO Settings come as a list of the following parameters:

• Meta Title - the title of the FAQ category page as it will appear in a search list of a web-crawler;

• Meta Keywords - the keywords (that describe your store) of the FAQ category page as it will appear in a search list below the meta title, each keyword separated by a comma;  

• Meta Description - the description of the FAQ category page will appear in a search list below the meta title. 

Click Save Category in the top right to finalize category configuration.

FAQ Articles 

Articles Grid 

To populate FAQ with articles, navigate to Content > FAQ by Aheadworks > Articles. 

The page features a grid to aggregate all articles available for the FAQ. The grid shows the following columns:

• ID - the identification number of an article;

• Category Name - the name of an article (as it will appear on the storefront);

• URL Key - the closing tag of an article url;

• Status - the status of an article (enabled/disabled);

• Store view - the store view to feature the article;

• Sort Order - a whole numeric to indicate the order of an article on the storefront;

• Number of helpful votes - the whole digital to tell the number of votes given by customers to the article to mark its helpfulness; 

• Number of total votes - the whole digital to tell the total number (negative and positive) of votes given to the article;

• Helpfulness Rate - the %-ratio between the above two values to tell the helpfulness of an article.

To add a new article, click on the Add New Article button at the top of the page. To edit an article, click on the name of the article in the grid. To delete or change the status of an article, tick the checkbox to the left of the article name and apply action from the Actions folding list above the grid (bulk action is supported too).

Create New/Edit Article

Article settings are organized into three tabs: General Settings, Content, and Statistics.

General Settings

• Enable Article – toggle to display the article on the storefront.

• Show the whole article in the Chatbot – (available if Chatbot is installed) set to Yes to display the full text in the chat window.

• Note: If set to No, a Short Content field appears. Use it to provide a brief summary specifically for the Chatbot. This text is only visible in the chat window.

• Article Title – the name of the article.

• URL Key – the relative URL of the article page.

• Store View – select the store views where the article will be available.

• Category – the category the article belongs to.

• Tags – keywords for content filtering. Press Enter or use a comma to separate multiple tags.

• Sort Order – the display priority within the category.

• SEO Settings (Meta Title, Keywords, Description) – configure these fields to manage how the article appears in search engine results.

Content

Use the WYSIWYG editor or Page Builder to format the article text.

Statistics

Track and manage article helpfulness ratings:

• Number of Helpful Votes — the count of "Yes" responses to the "Was this helpful?" prompt.

• Total Votes — the total number of responses received. By default, these values are 0. You can manually adjust these numbers during editing if necessary.

Click Save Article to apply changes.

Chatbot Configuration

To use the FAQ Chatbot (v.1.3.0+), ensure the FAQ Chatbot and BUP patches (included in the installation package) are installed via Composer.

Backend Setup

Navigate to Stores > Configuration > Aheadworks Extensions > Chatbot.

• Enable Chatbot – activates the bot on the frontend.

• Email for notifications – the address for receiving bot-related alerts.

• Title – the text displayed at the top of the chat window (e.g., "We're here to help").

• Welcome Message (Customer/Guest) – personalized greeting for logged-in users and guests.

• Confirmation ticket message – the text shown after a customer submits a ticket via the bot.

• Chat window auto-appearing (sec) – delay before the window opens automatically. Set to 0 or leave empty to disable.

• Chat window auto-minimizes (sec) – delay before the window minimizes due to inactivity. Set to 0 or leave empty to disable.

• Images (Avatar/Topper) – upload a Chatbot Image for the avatar and a Topper image for the header. The topper remains visible even when minimized.

• Number of Categories/Articles to Display – the number of items shown when the session starts.

• Chatbot window location – choose Left or Right alignment on the page.

• Anti-spam protection – select None, reCaptcha, or Honeypot. If using reCaptcha, provide your Google site key.

• Chat window auto-appearing (sec) – the time Chat-bot waits to auto-open on load of the store page

• Chat window auto-minimizes (sec) – the time Chat-bot waits to auto-minimize when no interaction happens it

• ChatBot Image – Chat-bot avatar to be displayed in the Chat window

• ChatBot Topper – additional image to be displayed on top of the Chat window to attract customers' attention. ChatBot Topper remains visible both when the chat window is minimized and when open.

• Number of Categories/Articles to Display – specify the number of FAQ categories for the Chat window to display on the start of the session with the Customer 

• Chatbot window location –  set to Right to display the Chat window on the right of the page, set to Left to display on the left

• Anti-spam protection mode – select the spam-protection mechanism: None, reCaptcha, Honeypot

• ReCaptcha site key (available when reCaptcha is selected above) – enter your Google reCaptcha key. Refer to the official Magento 2 guide to learn more on enabling and configuring reCaptcha.

Frontend Experience

Appearance and Navigation

• Automatic Display – the chat window appears after a preset delay and remains on the screen as the user navigates.

• Auto-Minimize – the window minimizes automatically after a period of inactivity. When minimized, only the Chatbot Image and Title are visible.

• Manual Controls – customers can click the "—" icon to minimize the window or click the minimized bar to expand it.

• Navigation – users can scroll through the interaction history or use the Back button to return to the previous step in the dialogue.

Visibility and Content

• Access Control – chatbot visibility is restricted to specific customer groups configured in Stores > Configuration > FAQ > Who can view FAQ content.

• Categories and Articles – on load, the bot displays a welcome message and a list of categories.

• If the list exceeds the Number of Categories/Articles to Display setting, a Show more button appears.

• Clicking a category displays its articles as a bot reply.

• Note: The chatbot ignores the Sort Order defined in backend settings for categories and articles.

Search Functionality

• Search Field – customers can type queries directly into the "Type here to search FAQ" field.

• Matching Logic – the bot searches by article titles and tags. It will not display the article title if the user's query exactly matches the title or a specific tag.

Ticket Submission

If the bot cannot find a matching article, it prompts the user to submit a ticket.

• Submission Form:

• Email – required for guest customers.

• Subject – defaults to the customer's last search query.

• Message – a text area for the detailed question.

• Processing:

• If Help Desk Ultimate 2 is not installed: A ticket is created in the system, and a confirmation message is displayed.

• If Help Desk Ultimate 2 is installed: The inquiry is sent to the admin via email with the subject: FAQ: Question from "[Article Name]".

FAQ Storefront Experience

FAQ Landing Page

Customers can access the FAQ section via the main navigation menu. The FAQ landing page consists of the following elements:

• FAQ Menu Reference – a navigation link added to the main menu automatically once the first article is published.

• FAQ Category – a thematic grouping of articles related to a specific topic.

• FAQ Article – the primary knowledge unit consisting of a question and an answer.

• Dedicated Article Search – a specialized search tool for the knowledge base.
  Note: This search tool is exclusive to FAQ content and does not index products or blog posts.

Category Display Logic

Depending on your configuration, categories can display a limited number of articles. Additional articles are collapsed under the "Read [number] more articles" link, which redirects customers to a dedicated category page featuring the full list of content.

Search Behavior

The search engine prioritizes results based on relevance:

1. Titles – Articles with matching keywords in the title are displayed first.

2. Content –Articles containing the keyword within the body text are displayed next.

Article Interaction & Rating

Each article allows customers to view and contribute to its helpfulness rating.

• Voting – Customers can cast their votes directly on the article page.

• Feedback – Upon voting, users receive a "Thank you" message or a prompt to contact support/provide feedback (depending on the specific rating).

• Sidebar Navigation – A sidebar is available on article pages to allow quick switching between different topics.

FAQ on Product Pages

The extension allows you to display product-specific information within a dedicated FAQ tab on the product page.

Enabling Product Attributes

To ensure specific product information is visible within the FAQ context on the storefront, configure your attributes as follows:

1. Navigate to Stores > Attributes > Product.

2. Select the attribute you wish to display.

3. Open the Storefront Properties tab.

4. Set Visible on Catalog Pages on Storefront to Yes.