How to Build a Custom "Product Q&A" Module in Magento 2

How to Build a Custom "Product Q&A" Module in Magento 2

Imagine this: a customer lands on a product page and has a specific question about sizing or compatibility. Instead of leaving the page or calling support, they ask directly under the product. Later, other shoppers find the question and answer useful — conversion increases, returns drop. That’s the value of an inline Product Q&A module in Magento 2.

In this post I’ll walk you through building a custom Product Q&A module step-by-step (code included). I’ll keep the tone friendly — like explaining to a teammate — and focus on clean architecture, frontend integration, admin moderation, SEO with Schema.org FAQ markup, and optional extensions such as email notifications and automated moderation. I’ll use Magefine as the vendor namespace so examples align with magefine.com.

Overview and architecture

High-level components we’ll implement:

• Database table(s) for questions (and optionally answers)
• Models, ResourceModels, and Collections
• Repository/Service layer for business logic
• Frontend controller endpoints (AJAX) to post questions and fetch lists
• Blocks/ViewModels and templates to render the Q&A on product pages
• Admin area: grid + form to moderate, approve, edit and answer questions
• JSON-LD output for Schema.org FAQPage per product
• Optional integrations: email notifications, automated moderation, spam protection

Module name: Magefine_ProductQa (Vendor: Magefine, Module: ProductQa). We'll keep code examples clear and ready to drop into a module skeleton.

Step 0 — Create module basic files

Create the folder app/code/Magefine/ProductQa and add these files:

// app/code/Magefine/ProductQa/registration.php
<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Magefine_ProductQa',
    __DIR__
);

// app/code/Magefine/ProductQa/etc/module.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Magefine_ProductQa" setup_version="1.0.0" />
</config>

After adding those files run bin/magento setup:upgrade and bin/magento setup:di:compile (if in production mode).

Step 1 — Database schema

Use declarative schema. We'll create a simple questions table. Each question can have an answer column, but you may prefer separate answer records for multiple answers or threads.

// app/code/Magefine/ProductQa/etc/db_schema.xml
<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">
    <table name="magefine_productqa_question" resource="default" engine="innodb" comment="Product Q&A Questions">
        <column xsi:type="int" name="question_id" unsigned="true" nullable="false" identity="true" comment="Question ID" />
        <column xsi:type="int" name="product_id" unsigned="true" nullable="false" comment="Product ID" />
        <column xsi:type="int" name="customer_id" unsigned="true" nullable="true" comment="Customer ID" />
        <column xsi:type="text" name="question_text" nullable="false" comment="Question Text" />
        <column xsi:type="text" name="answer_text" nullable="true" comment="Answer Text" />
        <column xsi:type="smallint" name="status" nullable="false" default="0" comment="0=pending,1=approved,2=rejected" />
        <column xsi:type="smallint" name="is_visible" nullable="false" default="1" comment="Visibility" />
        <column xsi:type="timestamp" name="created_at" nullable="false" on_update="false" default="CURRENT_TIMESTAMP" />
        <column xsi:type="timestamp" name="updated_at" nullable="true" on_update="true" />

        <constraint referenceId="PRIMARY" xsi:type="primary" columns="question_id" />
        <constraint xsi:type="foreign" referenceId="FK_MAGEFINE_QA_PRODUCT_ID" column="product_id" referenceTable="catalog_product_entity" referenceColumn="entity_id" onDelete="CASCADE" />
        <index name="PRODUCT_ID" column="product_id" />
    </table>
</schema>

Run setup:upgrade and Magento will create the table.

Step 2 — Model, ResourceModel, Collection

Minimal model structure:

// app/code/Magefine/ProductQa/Model/Question.php
<?php
namespace Magefine\ProductQa\Model;

use Magento\Framework\Model\AbstractModel;

class Question extends AbstractModel
{
    protected function _construct()
    {
        $this->_init(\Magefine\ProductQa\Model\ResourceModel\Question::class);
    }
}

// app/code/Magefine/ProductQa/Model/ResourceModel/Question.php
<?php
namespace Magefine\ProductQa\Model\ResourceModel;

use Magento\Framework\Model\ResourceModel\Db\AbstractDb;

class Question extends AbstractDb
{
    protected function _construct()
    {
        $this->_init('magefine_productqa_question', 'question_id');
    }
}

// app/code/Magefine/ProductQa/Model/ResourceModel/Question/Collection.php
<?php
namespace Magefine\ProductQa\Model\ResourceModel\Question;

use Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection;

class Collection extends AbstractCollection
{
    protected function _construct()
    {
        $this->_init(\Magefine\ProductQa\Model\Question::class, \Magefine\ProductQa\Model\ResourceModel\Question::class);
    }
}

Good practice: define interfaces and repositories for the model so other modules can rely on a contract.

Step 3 — Repository and service layer

Define a repository interface to abstract persistence. This helps for unit testing and future changes.

// app/code/Magefine/ProductQa/Api/QuestionRepositoryInterface.php
<?php
namespace Magefine\ProductQa\Api;

use Magefine\ProductQa\Model\Question;

interface QuestionRepositoryInterface
{
    public function save(Question $question);
    public function getById($id);
    public function getList(\Magento\Framework\Api\SearchCriteriaInterface $criteria);
    public function delete(Question $question);
}

// app/code/Magefine/ProductQa/Model/QuestionRepository.php
<?php
namespace Magefine\ProductQa\Model;

use Magefine\ProductQa\Api\QuestionRepositoryInterface;
use Magefine\ProductQa\Model\Question as QuestionModel;
use Magefine\ProductQa\Model\ResourceModel\Question as ResourceQuestion;
use Magefine\ProductQa\Model\ResourceModel\Question\CollectionFactory;
use Magento\Framework\Api\SearchCriteriaBuilder;

class QuestionRepository implements QuestionRepositoryInterface
{
    protected $resource;
    protected $collectionFactory;
    protected $searchCriteriaBuilder;

    public function __construct(
        ResourceQuestion $resource,
        CollectionFactory $collectionFactory,
        SearchCriteriaBuilder $searchCriteriaBuilder
    ) {
        $this->resource = $resource;
        $this->collectionFactory = $collectionFactory;
        $this->searchCriteriaBuilder = $searchCriteriaBuilder;
    }

    public function save(QuestionModel $question)
    {
        $this->resource->save($question);
        return $question;
    }

    public function getById($id)
    {
        $model = new QuestionModel();
        $this->resource->load($model, $id);
        return $model;
    }

    public function getList(\Magento\Framework\Api\SearchCriteriaInterface $criteria)
    {
        $collection = $this->collectionFactory->create();
        // Apply filters based on $criteria (left as exercise or implement using collection processors)
        return $collection;
    }

    public function delete(QuestionModel $question)
    {
        $this->resource->delete($question);
        return true;
    }
}

For larger modules use repository pattern with extension attributes and SearchResultsInterface. The above is enough to get started.

Step 4 — Frontend controllers (AJAX) and routes

Create a frontend route and controller to handle question submission. We'll post via AJAX to this endpoint and return JSON.

// app/code/Magefine/ProductQa/etc/frontend/routes.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route id="productqa" frontName="productqa">
            <module name="Magefine_ProductQa" />
        </route>
    </router>
</config>

// app/code/Magefine/ProductQa/Controller/Ajax/Post.php
<?php
namespace Magefine\ProductQa\Controller\Ajax;

use Magento\Framework\App\Action\Action;
use Magento\Framework\App\Action\Context;
use Magento\Framework\Controller\Result\JsonFactory;
use Magefine\ProductQa\Model\QuestionFactory;

class Post extends Action
{
    protected $resultJsonFactory;
    protected $questionFactory;

    public function __construct(Context $context, JsonFactory $resultJsonFactory, QuestionFactory $questionFactory)
    {
        parent::__construct($context);
        $this->resultJsonFactory = $resultJsonFactory;
        $this->questionFactory = $questionFactory;
    }

    public function execute()
    {
        $result = $this->resultJsonFactory->create();
        $request = $this->getRequest();

        if (!$request->isAjax() || !$request->isPost()) {
            return $result->setData(['success' => false, 'message' => 'Invalid request']);
        }

        $productId = (int)$request->getParam('product_id');
        $questionText = trim($request->getParam('question'));
        $customerId = $this->_getSession()->getCustomerId() ?? null; // If using customer session

        if (!$productId || !$questionText) {
            return $result->setData(['success' => false, 'message' => 'Missing fields']);
        }

        try {
            $question = $this->questionFactory->create();
            $question->setData([
                'product_id' => $productId,
                'customer_id' => $customerId,
                'question_text' => $questionText,
                'status' => 0 // pending
            ]);
            $question->save();

            // Optionally send notification to admin (event or service)

            return $result->setData(['success' => true, 'message' => 'Your question has been submitted and is pending moderation.']);
        } catch (\Exception $e) {
            return $result->setData(['success' => false, 'message' => 'An error occurred: ' . $e->getMessage()]);
        }
    }
}

Note: For customer session you may want to inject Magento\Customer\Model\Session. Also consider form key validation; Magento's Action class provides getRequest() and the default form key validator can be used via Magento\Framework\App\Action\Context or via csrf protection by using POST and form_key param.

Step 5 — Block, layout and template for product page

We want to show the Q&A under the product description or in a tab. Add a layout update to insert our block into catalog_product_view.

// app/code/Magefine/ProductQa/view/frontend/layout/catalog_product_view.xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Magefine\ProductQa\Block\ProductQa" name="magefine.productqa" template="Magefine_ProductQa::productqa.phtml" after="product.info.details" />
        </referenceContainer>
    </body>
</page>

// app/code/Magefine/ProductQa/Block/ProductQa.php
<?php
namespace Magefine\ProductQa\Block;

use Magento\Catalog\Block\Product\Context;
use Magento\Framework\UrlInterface;
use Magefine\ProductQa\Model\ResourceModel\Question\CollectionFactory as QuestionCollectionFactory;

class ProductQa extends \Magento\Framework\View\Element\Template
{
    protected $product;
    protected $urlBuilder;
    protected $questionCollectionFactory;

    public function __construct(Context $context, UrlInterface $urlBuilder, QuestionCollectionFactory $questionCollectionFactory, array $data = [])
    {
        parent::__construct($context, $data);
        $this->urlBuilder = $urlBuilder;
        $this->questionCollectionFactory = $questionCollectionFactory;
    }

    public function getPostUrl()
    {
        return $this->getUrl('productqa/ajax/post');
    }

    public function getProductId()
    {
        return $this->getProduct()->getId();
    }

    public function getProduct()
    {
        if (!$this->product) {
            $this->product = $this->_coreRegistry->registry('current_product');
        }
        return $this->product;
    }

    public function getApprovedQuestions()
    {
        $collection = $this->questionCollectionFactory->create();
        $collection->addFieldToFilter('product_id', $this->getProduct()->getId());
        $collection->addFieldToFilter('status', 1); // approved
        $collection->setOrder('created_at', 'DESC');
        return $collection;
    }
}

Now the template. Keep it simple and accessible.

// app/code/Magefine/ProductQa/view/frontend/templates/productqa.phtml
<?php /** @var \Magefine\ProductQa\Block\ProductQa $block */ ?>
<div class="magefine-product-qa" id="magefine-product-qa" data-post-url="<?= $block->escapeUrl($block->getPostUrl()) ?>" data-product-id="<?= $block->getProductId() ?>">
    <h2>Questions & Answers</h2>

    <div class="mf-qa-form">
        <textarea id="mf-question-text" placeholder="Ask a question about this product" rows="3"></textarea>
        <button id="mf-submit-question" class="action primary" type="button">Submit question</button>
        <div id="mf-feedback" style="display:none; margin-top:10px;"></div>
    </div>

    <div class="mf-qa-list">
        <?php foreach ($block->getApprovedQuestions() as $q): ?>
            <div class="mf-qa-item" data-id="<?= $q->getId() ?>">
                <strong><?= $block->escapeHtml($q->getQuestionText()) ?></strong>
                <div class="mf-qa-answer"><?= $block->escapeHtml($q->getAnswerText()) ?></div>
                <div class="mf-qa-meta"><?= $q->getCreatedAt() ?></div>
            </div>
        <?php endforeach; ?>
    </div>
</div>

<script type="text/javascript">
require(['jquery'], function($) {
    $(document).ready(function() {
        $('#mf-submit-question').on('click', function() {
            var url = $('#magefine-product-qa').data('post-url');
            var productId = $('#magefine-product-qa').data('product-id');
            var question = $('#mf-question-text').val();
            var formKey = $.cookie('form_key');

            if (!question.trim()) {
                $('#mf-feedback').text('Please write a question').show();
                return;
            }

            $.ajax({
                url: url,
                type: 'POST',
                dataType: 'json',
                data: {product_id: productId, question: question, form_key: formKey},
                success: function(res) {
                    $('#mf-feedback').text(res.message).show();
                    if (res.success) {
                        $('#mf-question-text').val('');
                    }
                },
                error: function() {
                    $('#mf-feedback').text('Unexpected error, please try later').show();
                }
            });
        });
    });
});
</script>

Notes about the JS above:

• We used jQuery and a simple cookie read for form_key. In modern Magento you can get formKey via mage/cookies or inject formKey into the block and render a hidden field. Ensure CSRF protection by passing form_key.
• We post to productqa/ajax/post which we implemented earlier.

Step 6 — Admin backoffice: routes, ACL, menu

Create admin routes and ACL so admins can moderate questions.

// app/code/Magefine/ProductQa/etc/adminhtml/routes.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="admin">
        <route id="productqa" frontName="productqa">
            <module name="Magefine_ProductQa" />
        </route>
    </router>
</config>

// app/code/Magefine/ProductQa/etc/adminhtml/menu.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Menu/etc/menu.xsd">
    <menu>
        <add id="Magefine_ProductQa::menu" title="Product Q&A" module="Magefine_ProductQa" sortOrder="70" parent="Magento_Backend::content" action="productqa/question/index" resource="Magefine_ProductQa::manage" />
    </menu>
</config>

// app/code/Magefine/ProductQa/etc/acl.xml
<?xml version="1.0"?>
<acl xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <resources>
        <resource id="Magento_Backend::admin" title="Admin" >
            <resource id="Magefine_ProductQa::manage" title="Manage Product Q&A" />
        </resource>
    </resources>
</acl>

Now admin controllers: a simple grid listing questions and actions to approve, reject, delete.

// app/code/Magefine/ProductQa/Controller/Adminhtml/Question/Index.php
<?php
namespace Magefine\ProductQa\Controller\Adminhtml\Question;

use Magento\Backend\App\Action;
use Magento\Backend\App\Action\Context;
use Magento\Framework\View\Result\PageFactory;

class Index extends Action
{
    const ADMIN_RESOURCE = 'Magefine_ProductQa::manage';
    protected $resultPageFactory;

    public function __construct(Context $context, PageFactory $resultPageFactory)
    {
        parent::__construct($context);
        $this->resultPageFactory = $resultPageFactory;
    }

    public function execute()
    {
        $resultPage = $this->resultPageFactory->create();
        $resultPage->setActiveMenu('Magefine_ProductQa::menu');
        $resultPage->getConfig()->getTitle()->prepend(__('Product Q&A'));
        return $resultPage;
    }
}

Use a UI component grid for the list. Skeleton for the UI component XML:

// app/code/Magefine/ProductQa/view/adminhtml/ui_component/magefine_productqa_question_listing.xml
<?xml version="1.0"?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <settings>
        <spinner>productqa_listing_columns
            <argument name="class" xsi:type="string">Magefine\ProductQa\Ui\DataProvider\Question\DataProviderproductqa_question_listing_data_sourcequestion_idquestion_id

// app/code/Magefine/ProductQa/Controller/Adminhtml/Question/Approve.php
<?php
namespace Magefine\ProductQa\Controller\Adminhtml\Question;

use Magento\Backend\App\Action;
use Magento\Backend\App\Action\Context;

class Approve extends Action
{
    const ADMIN_RESOURCE = 'Magefine_ProductQa::manage';
    protected $questionFactory;

    public function __construct(Context $context, \Magefine\ProductQa\Model\QuestionFactory $questionFactory)
    {
        parent::__construct($context);
        $this->questionFactory = $questionFactory;
    }

    public function execute()
    {
        $id = (int)$this->getRequest()->getParam('id');
        if (!$id) {
            $this->messageManager->addErrorMessage(__('Invalid ID'));
            return $this->_redirect('*/*/');
        }

        $model = $this->questionFactory->create()->load($id);
        if (!$model->getId()) {
            $this->messageManager->addErrorMessage(__('Question not found'));
            return $this->_redirect('*/*/');
        }

        $model->setStatus(1); // approved
        $model->save();
        $this->messageManager->addSuccessMessage(__('Question approved'));
        return $this->_redirect('*/*/');
    }
}

// In the productqa block, render JSON-LD when the product page renders
<?php
$questions = $block->getApprovedQuestions();
$faq = [
    '@context' => 'https://schema.org',
    '@type' => 'FAQPage',
    'mainEntity' => []
];
foreach ($questions as $q) {
    if (!$q->getAnswerText()) continue; // FAQ needs an answer
    $faq['mainEntity'][] = [
        '@type' => 'Question',
        'name' => $q->getQuestionText(),
        'acceptedAnswer' => [
            '@type' => 'Answer',
            'text' => $q->getAnswerText()
        ]
    ];
}
if (!empty($faq['mainEntity'])) {
    echo '';
}
?>

// app/code/Magefine/ProductQa/Observer/SendNotification.php (sketch)
public function execute(\Magento\Framework\Event\Observer $observer)
{
    $question = $observer->getEvent()->getQuestion();
    // Build and send email with TransportBuilder
}

// Example: simple keyword check before saving (in a plugin or service)
$blacklist = ['spamword1','spamword2'];
foreach ($blacklist as $word) {
    if (stripos($questionText,$word) !== false) {
        // mark as rejected or require manual review
    }
}

<?php
$questions = $block->getApprovedQuestions();
$faqEntities = [];
foreach ($questions as $q) {
    $questionText = trim((string)$q->getQuestionText());
    $answerText = trim((string)$q->getAnswerText());
    if ($questionText === '' || $answerText === '') continue;
    $faqEntities[] = [
        '@type' => 'Question',
        'name' => $questionText,
        'acceptedAnswer' => [
            '@type' => 'Answer',
            'text' => $answerText
        ]
    ];
}
if (!empty($faqEntities)) {
    $faq = [
        '@context' => 'https://schema.org',
        '@type' => 'FAQPage',
        'mainEntity' => $faqEntities
    ];
    echo '';
}
?>