User Guide - Magento 2 AI Chatbot

Welcome to Magehq Docs

MageHQ AI Chatbot User Guide

MageHQ AI Chatbot adds an intelligent AI-powered chat assistant to your Magento 2 storefront. It helps customers ask questions about products, categories, shopping cart, orders, shipping, returns, and store policies directly from a modern floating chatbot widget.

This guide explains how to install, configure, customize, and manage the MageHQ AI Chatbot module in Magento 2.

1. Requirements

Magento 2 store with admin access
MageHQ Core module installed
MageHQ AI Commerce Client module installed
Valid MageHQ license or subscription plan, depending on your setup
Magento cron configured and running
Internet access from the server to connect with the selected AI service

2. Installation

Upload the module files to your Magento installation, then run the following commands from the Magento root directory:

php bin/magento module:enable Magehq_Core Magehq_AICommerceClient Magehq_AIChatbot
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

After installation, log in to the Magento Admin Panel and confirm that the MageHQ menu is available.

3. Admin Menu

After the module is installed, you can manage the chatbot from the Magento admin menu:

Magehq > AI Chatbot > Dashboard
Magehq > AI Chatbot > Diagnostics
Magehq > AI Chatbot > Message Logs
Magehq > AI Chatbot > Settings

You can also access the configuration page from:

Stores > Configuration > Magehq Extensions > AI Chatbot

4. License Configuration

Before enabling the chatbot, make sure your MageHQ license is configured correctly.

Go to Stores > Configuration > Magehq Extensions > Manage Licenses.
Add or verify your MageHQ license key.
Save the configuration.
Flush Magento cache.

If the chatbot is connected to a MageHQ subscription plan, the license and subscription status will be checked before AI responses are generated.

5. General Chatbot Settings

Go to:

Stores > Configuration > Magehq Extensions > AI Chatbot > General

Field	Description
Enable chatbot	Enable or disable the chatbot on the storefront.
Chatbot name	The assistant name displayed in the chatbot header. Example: MageHQ Assistant.
Welcome message	The first message customers see when opening the chatbot.
Fallback message	The message shown when the chatbot cannot answer confidently.
License text	Optional text displayed in the chatbot footer.
System prompt	Defines the main instruction for the AI assistant.
Assistant personality	Defines the tone and behavior of the assistant.

Recommended General Settings

Chatbot name:
MageHQ Assistant

Welcome message:
Hello! How can I help you today?

Fallback message:
I could not answer that confidently right now. Please contact our support team for more help.

System prompt:
You are a helpful Magento storefront assistant. Answer concisely and focus on product, order, shipping, return, and store questions.

Assistant personality:
Professional, concise, accurate, friendly, and helpful.

6. Chatbot Design Customization

The module allows you to customize the chatbot appearance from the admin configuration.

Go to:

Stores > Configuration > Magehq Extensions > AI Chatbot > General

You can customize:

Widget background color
Surface background color
Border color
Text color
Muted text color
Primary gradient colors
Header gradient colors
User bubble color
Bot bubble color
Panel radius
Panel shadow
Custom CSS

Example Design Settings

Widget background:
#fdfdff

Surface background:
#f4f7ff

Surface strong background:
#eaf0ff

Border color:
#d7e1f2

Text color:
#0f172a

Muted color:
#64748b

Primary gradient start:
#0f172a

Primary gradient end:
#2563eb

User bubble color:
#2563eb

Bot bubble color:
#ffffff

Panel radius:
24px

Panel shadow:
0 28px 80px rgba(15, 23, 42, 0.18)

7. AI Connection Settings

The chatbot can work with MageHQ Cloud routing or with your own AI API key, depending on your module configuration and subscription setup.

MageHQ Cloud / Subscription API

With MageHQ Cloud, the chatbot can use the MageHQ AI Commerce platform for license validation, quota checking, subscription control, and AI model routing.

This mode is recommended if you sell the chatbot as part of an AI Commerce subscription plan.

Own API Key Mode

In Own API Key mode, the store owner connects the chatbot to their own AI provider account.

Available configuration fields include:

Own API Provider
Own API Base URL
Own API Timeout
Own API Key
Own API Model
Temperature
Max Tokens

Example Provider Settings

Provider	Base URL	Example Model
OpenAI	https://api.openai.com/v1	gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
Anthropic	Provider API endpoint	claude-3-5-haiku-latest
Gemini	Provider API endpoint	gemini-1.5-flash

After changing connection settings, click Save Config and flush Magento cache.

8. Context Settings

Context settings control what Magento data can be sent to the AI assistant to improve answer quality.

Go to:

Stores > Configuration > Magehq Extensions > AI Chatbot > Context

Field	Description
Send Product Context	Allows the chatbot to understand the current product page.
Send Category Context	Allows the chatbot to understand the current category page.
Send Cart Context	Allows the chatbot to use shopping cart information when answering.
Send Customer Context	Allows the chatbot to use customer-related context when available.
Send Order Context	Allows the chatbot to support order-related questions.

For better shopping assistance, it is recommended to enable product, category, and cart context. For privacy-sensitive stores, review customer and order context settings carefully.

9. Privacy Settings

The module includes privacy controls to reduce sensitive data exposure in AI requests and logs.

Go to:

Stores > Configuration > Magehq Extensions > AI Chatbot > Privacy

Field	Description
Mask Customer Email	Masks customer email addresses before sending or storing data.
Mask Customer Phone	Masks customer phone numbers.
Mask Customer Name	Masks customer names when enabled.
Include PII in AI Request	Controls whether personally identifiable information can be included in AI requests.

Recommended Privacy Settings

Mask Customer Email:
Yes

Mask Customer Phone:
Yes

Mask Customer Name:
No

Include PII in AI Request:
No

10. Logging and Access Control

Go to:

Stores > Configuration > Magehq Extensions > AI Chatbot > Logging

Field	Description
Enable logging	Stores chatbot activity for admin review.
Debug Log	Enables additional debugging information. Use only when troubleshooting.
Store Full Messages	Stores full customer and assistant messages when enabled.
Allowed customer groups	Restricts chatbot access to selected customer groups.
Blocked IPs	Blocks selected IP addresses from using the chatbot.
Max messages per minute	Limits how many messages a visitor can send per minute.
Cooldown seconds	Cooldown period applied after rate limit is reached.
Enable analytics	Enables chatbot analytics tracking.
Message log retention days	Defines how long message logs are kept before automatic cleanup.

Recommended Logging Settings

Enable logging:
Yes

Debug Log:
No

Store Full Messages:
No

Max messages per minute:
10

Cooldown seconds:
60

Enable analytics:
Yes

Message log retention days:
90

11. Training Data

MageHQ AI Chatbot can use Magento store content as training data to improve answer quality.

The module indexes data from:

Products
Categories
CMS pages
Default support and policy topics

Training data is refreshed automatically by Magento cron every 6 hours.

Make sure Magento cron is running correctly:

* * * * * php /path/to/magento/bin/magento cron:run | grep -v "Ran jobs by schedule" >> /path/to/magento/var/log/magento.cron.log

If product, category, or CMS page content changes, the chatbot may need time until the next scheduled indexing cycle before using the updated data.

12. Frontend Chatbot Usage

Once enabled, the chatbot appears as a floating chat button on the storefront.

Customers can use it to ask questions such as:

Do you have this product in stock?
Can you recommend similar products?
What is your return policy?
How long does shipping take?
Can you help me find a product?
What is the status of my order?

The chatbot can display:

AI-generated answers
Quick reply buttons
Product suggestion cards
Product images
Product prices
Product links
Conversation history

13. Order Status Questions

The chatbot can help customers with order status questions when order context is enabled.

Customers may ask:

What is the status of order #000000123?

For security, the chatbot may require the customer email address to verify the order before showing order information.

Example:

Order number: 000000123
Email: customer@example.com

If the order cannot be verified, the chatbot will ask the customer to check the information or contact support.

14. Dashboard

Go to:

Magehq > AI Chatbot > Dashboard

The dashboard gives a quick overview of chatbot activity, including:

Total chats
Token usage
Unresolved conversations
Recent analytics events

Use the dashboard to monitor chatbot adoption and customer engagement.

15. Diagnostics

Go to:

Magehq > AI Chatbot > Diagnostics

The diagnostics page helps verify whether the chatbot is connected and ready to use.

It can show information such as:

License status
Subscription status
Plan code
Routing status
Message log count
Total chats
Connection test result

Use this page when troubleshooting license, subscription, quota, or connection issues.

16. Message Logs

Go to:

Magehq > AI Chatbot > Message Logs

The Message Logs page allows admins to review chatbot requests and responses.

You can view:

Customer message preview
AI response preview
Status
Provider
Model
Input tokens
Output tokens
Error code
Created date

The module also supports:

Filtering logs
Viewing log details
Exporting logs to CSV
Exporting summary reports
Deleting selected logs
Cleaning old logs

17. Recommended Testing Checklist

After configuration, test the chatbot on the storefront.

Open the storefront in a private browser window.
Confirm the floating chatbot button appears.
Open the chatbot panel.
Check the welcome message.
Ask a general store question.
Ask a product-related question on a product page.
Ask a category-related question on a category page.
Add a product to cart and ask a cart-related question.
Test an order status question if order context is enabled.
Check Message Logs in admin.
Check Dashboard metrics.
Run Diagnostics if any response fails.

18. Troubleshooting

Issue	Possible Cause	Solution
Chatbot does not appear on the storefront	The chatbot is disabled, cache is not flushed, or static content is outdated.	Enable the chatbot, flush cache, and redeploy static content if needed.
Chatbot appears but does not answer	AI connection, license, quota, or API key issue.	Check Diagnostics, verify license, subscription, quota, and provider settings.
Invalid license error	The license key is missing, inactive, or does not match the domain.	Check MageHQ license settings and confirm the registered domain.
Quota exceeded	The subscription plan usage limit has been reached.	Upgrade the plan or wait for quota reset.
Wrong or poor AI answers	Prompt, training data, or store context is incomplete.	Review system prompt, assistant personality, product data, CMS content, and context settings.
Product suggestions do not appear	No matching products found or product data is not indexed.	Check product visibility, status, stock, URL, image, and cron indexing.
Order status is not returned	Order context is disabled or order verification failed.	Enable order context and ask the customer to provide the correct order number and email address.
Admin menu is missing	Admin role permissions are not updated.	Go to System > Permissions > User Roles and allow MageHQ AI Chatbot resources.
Logs are not visible	Logging is disabled or logs were cleaned.	Enable logging and check message log retention settings.

19. Best Practices

Keep answers focused by writing a clear system prompt.
Use a friendly but concise assistant personality.
Enable product, category, and cart context for better shopping assistance.
Review privacy settings before sending customer or order data to AI services.
Keep full message storage disabled unless needed for debugging.
Use rate limiting to prevent abuse.
Review message logs regularly to improve prompts and store content.
Keep Magento cron running so training data and cleanup jobs work correctly.
Use Diagnostics after changing license, subscription, or AI provider settings.

20. Uninstallation

To disable the module, run:

php bin/magento module:disable Magehq_AIChatbot
php bin/magento setup:upgrade
php bin/magento cache:flush

To completely remove module files, disable the module first, then remove the module directory from:

app/code/Magehq/AIChatbot

After removing files, run:

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

21. Support

If you need help with installation, configuration, license activation, AI provider setup, or troubleshooting, please contact MageHQ support.

Before contacting support, prepare the following information:

Magento version
PHP version
Module version
Store domain
License key or order information
Screenshot of the Diagnostics page
Relevant error messages from Message Logs