MxChat WooCommerce Integration

Transform your WooCommerce store with AI-powered shopping assistance. This add-on seamlessly integrates your product catalog with MxChat, enabling intelligent product recommendations, cart management, and order tracking—all through natural conversation.

Quick Setup

1. Install the Plugin: Upload and activate MxChat WooCommerce Integration through your WordPress plugins page
2. Verify License: Ensure your MxChat Pro license is active in MxChat → License Activation
3. Configure Settings: Go to MxChat → WooCommerce to customize product display options
4. Enable Product Sync: In MxChat → Knowledge → Settings, enable “Sync Products to Knowledge Base”
5. Create Intents: Set up WooCommerce intents in MxChat → Actions for product inquiry, recommendations, cart, and orders
6. Test Features: Open your chatbot and try asking about products, adding to cart, or checking orders

Key Features

Product Cards & Inquiry

• Smart Product Detection: AI automatically identifies products mentioned in conversation
• Interactive Product Cards: Beautiful cards with images, prices, and add to cart buttons
• Variable Product Support: Dropdown selectors for product variations (size, color, etc.)
• Real-time Availability: Shows stock status and purchasability
• AI-Powered Descriptions: Contextual product information based on user questions
• Configurable Display: Show/hide prices and add to cart buttons per your business needs
• Custom Button Text: Personalize the add to cart button text

AI Product Recommendations

• Context-Aware Suggestions: Recommendations based on order history, cart contents, and conversation
• Personalized Results: Up to 4 products with AI-generated explanations for each
• Multilingual Support: Responds in the user’s language automatically
• Smart Filtering: Excludes products already in cart
• Purchase History Integration: Considers past orders for better suggestions
• Similarity Matching: Uses embeddings to find most relevant products

Shopping Cart Integration

• Toolbar Cart Icon: Live cart count badge in chatbot toolbar
• Cart Dropdown: View cart contents without leaving chat
• Add to Cart from Chat: Users can add products by simply asking
• Product Memory: Remembers last discussed product for quick adding
• Remove Items: Delete products from cart dropdown
• Visual Feedback: Animated cart updates and success indicators
• Cart Subtotal: Real-time total display
• Quick Checkout: Direct links to cart and checkout pages

Order History & Tracking

• Toolbar Orders Icon: Quick access to order history
• Orders Dropdown: View recent orders (up to 5) with status
• AI Order Assistant: Natural language order inquiries
• Order Details: Date, status, items, and totals
• Status Display: Color-coded order statuses
• Direct Order Links: One-click access to full order details
• Login Protection: Secure access for logged-in users only

Product Sync & Knowledge

• Automatic Sync: Products automatically added to knowledge base when published
• Embedding Generation: Uses your configured embedding model (OpenAI, Voyage, or Gemini)
• Pinecone Support: Stores embeddings in Pinecone if configured
• WordPress DB Fallback: Automatically uses WordPress database if Pinecone unavailable
• Auto-Delete: Removes products from knowledge base when deleted
• Comprehensive Data: Includes name, description, price, SKU in embeddings

Checkout Assistance

• Smart Redirect: Guides users to checkout when ready
• Cart Validation: Checks cart isn’t empty before proceeding
• Contextual Messages: Friendly confirmation with cart summary

Configuration Options

Product Display Settings

Configure how products appear in chat at MxChat → WooCommerce:

• Add to Cart Button Text: Customize button label (default: “Add to Cart”)
• Show Product Prices: Toggle price display on/off
  • Enabled: Shows prices in product cards
  • Disabled: Hides prices (useful for “contact for pricing” scenarios)
• Show Add to Cart Button: Toggle cart button visibility
  • Enabled: Shows add to cart button
  • Disabled: Hides button (for catalog-only or quote-based stores)

Product Sync Settings

Control product syncing at MxChat → Knowledge → Settings:

• Sync Products to Knowledge Base: Enable to automatically sync WooCommerce products
  • When enabled, products are added/updated when published
  • Products removed from knowledge base when deleted
  • Uses your configured embedding model
  • Stores in Pinecone if configured, otherwise WordPress database

Toolbar Settings

Enable cart and order icons at MxChat → Toolbar & Components:

• Enable the toolbar to show cart and order history icons
• Icons automatically inject when toolbar is enabled
• Cart icon shows live item count badge
• Order icon available for logged-in users

Setting Up WooCommerce Intents

Configure intents at MxChat → Actions to enable WooCommerce features:

1. Show Product Card

Purpose: Display detailed product information in chat

Callback: Show Product Card

Trigger Phrases Examples:

• show me product name
• tell me about product name
• what is product name
• product information
• details about product name

How It Works:

• AI identifies product name from conversation
• Searches product catalog using advanced matching
• Generates contextual AI response about the product
• Displays interactive product card with image, price, and add to cart
• Remembers product for future “add to cart” requests

2. Product Recommendations

Purpose: Suggest relevant products based on user context

Callback: Product Recommendations

Trigger Phrases Examples:

• recommend products
• what should I buy
• show me similar products
• suggest something
• what do you recommend
• looking for [category/type]

How It Works:

• Analyzes user’s order history (if logged in)
• Checks current cart contents
• Generates AI shopping suggestion based on request
• Finds matching products using embeddings
• Returns up to 4 products with AI-generated justifications
• Responds in user’s language automatically

3. Add to Cart

Purpose: Add products to shopping cart via chat

Callback: Add to Cart

Trigger Phrases Examples:

• add to cart
• add it to my cart
• I want to buy product name
• add product name to cart
• buy this
• purchase product name

How It Works:

• Uses last discussed product if message is generic (“add to cart”)
• Searches for specific product if name mentioned
• Validates product is purchasable and in stock
• Checks if already in cart (prevents duplicates)
• Adds product and updates cart count with animation
• Generates multilingual AI confirmation message

4. Order History

Purpose: Access order information and status

Callback: Order History

Trigger Phrases Examples:

• show my orders
• order history
• where is my order
• track my order
• check order status
• recent purchases

How It Works:

• Requires user to be logged in
• Retrieves all user’s WooCommerce orders
• Formats order details (date, items, total, status)
• Sends to AI for natural language response
• Handles specific queries (“where’s my last order”, “orders from July”)

5. Proceed to Checkout

Purpose: Direct users to checkout page

Callback: Proceed to Checkout

Trigger Phrases Examples:

• checkout
• proceed to checkout
• ready to buy
• complete purchase
• finish order
• go to checkout

How It Works:

• Validates cart isn’t empty
• Shows cart summary (item count, total)
• Redirects to checkout page after 1 second
• Friendly message during redirect

Product Cards

Simple Products

Product cards for simple products include:

• Product image (clickable link to product page)
• Product name (clickable link to product page)
• Price (if enabled in settings)
• Add to cart button (if enabled in settings)
• Real-time stock validation

Variable Products

Product cards for variable products add:

• Dropdown selectors for each attribute (size, color, etc.)
• Dynamic price updates based on selected variation
• Smart option filtering (disables unavailable combinations)
• Stock status per variation
• Required selection validation before adding to cart

Add to Cart Behavior

When users click the add to cart button:

1. Button shows “Adding…” loading state
2. Product added to WooCommerce cart
3. Button changes to “✓ Added” with success styling
4. Cart count badge animates with bounce effect
5. Brief notification dot appears on cart icon
6. Cart dropdown refreshes if open
7. Button returns to normal after 2.5 seconds

Cart Management

Cart Icon & Badge

• Appears in chatbot toolbar when enabled
• Shows live count of items in cart
• Badge hidden when cart is empty
• Click to open cart dropdown
• Updates automatically when items added/removed

Cart Dropdown

The cart dropdown provides:

• Header: “Your Cart” title with close button
• Item List: Shows each product with:
  • Product thumbnail image
  • Product name
  • Price per item
  • Quantity
  • Remove button (×)
• Subtotal: Running cart total
• Action Buttons:
  • “View Cart” – Goes to cart page
  • “Checkout” – Goes to checkout page
• Empty State: “Your cart is empty” message when no items

Adding Products from Chat

Users can add products by:

1. Generic Request: “add to cart” after discussing a product
   • Uses last discussed product stored in transient
   • Valid for 1 hour after product discussion
2. Specific Request: “add product name to cart”
   • Searches catalog for best matching product
   • Uses similarity scoring for accuracy
   • Requires 30+ score for match
3. Product Card Button: Click add to cart on product card
   • Direct add with visual feedback
   • Handles variations automatically

Duplicate Prevention

• Checks if product already in cart before adding
• Shows AI-generated message if duplicate detected
• Message in user’s language: “[Product] is already in your cart”
• Suggests continuing shopping or checking out

Order History

Order History Icon

• Appears in chatbot toolbar when enabled
• Clipboard/document icon design
• Available for logged-in users only
• Click to open orders dropdown

Orders Dropdown

The orders dropdown displays:

• Header: “Your Orders” title with close button
• Order List: Shows up to 5 recent orders with:
  • Order number
  • Order date
  • Order status with color coding
  • Order total
  • First 2 items (with “+ X more” if applicable)
  • “View Order” link to full order details
• Footer: “View All Orders” link to WooCommerce My Account orders page
• Empty State: “You have no orders yet” for new customers
• Login Required: “Please log in to view your orders” for guests

Order Status Colors

• Pending: Yellow/warning
• Processing: Blue/info
• Completed: Green/success
• Cancelled: Red/error
• Failed: Red/error
• On Hold: Orange/warning

AI Order Assistant

When users ask about orders through the Order History intent:

• Retrieves all user orders from WooCommerce
• Formats order details (number, date, items, total)
• Sends formatted data to AI with user’s question
• AI responds conversationally to specific queries like:
  • “Where’s my order from last week?”
  • “What did I order in June?”
  • “How much did I spend on my last order?”
  • “Track order #12345”
• Handles license key requests securely (redirects to email/support)

Product Sync & Knowledge Base

How Product Sync Works

1. Enable Sync: Turn on “Sync Products to Knowledge Base” in MxChat → Knowledge → Settings
2. Automatic Detection: Plugin monitors WooCommerce product changes
3. Content Generation: When product published/updated:
   • Combines description, short description, price, sale price, and SKU
   • Creates comprehensive text for embedding
4. Embedding Creation: Uses your configured embedding model (OpenAI Ada-002, Voyage AI, or Google Gemini)
5. Storage Decision:
   • If Pinecone configured: Stores in Pinecone with metadata
   • If Pinecone unavailable: Stores in WordPress database
   • Automatic fallback ensures reliability
6. Deletion Handling: When product deleted:
   • Removes from Pinecone (if used)
   • Removes from WordPress database
   • Clean removal by product URL

Embedding Models Supported

• OpenAI: text-embedding-ada-002 (1536 dimensions)
• Voyage AI: Various models including voyage-3-large (2048 dimensions)
• Google Gemini: gemini-embedding models (1536 dimensions)

Pinecone Integration

If MxChat Pinecone add-on is installed and configured:

• Products stored as vectors in Pinecone index
• Metadata includes:
  • Product content (description, price, SKU)
  • Source URL (product permalink)
  • Type marker (“product”)
  • Last updated timestamp
  • WooCommerce specific data (product type, ID, SKU)
• Fast similarity search across all products
• Scalable for large catalogs (1000+ products)

WordPress Database Storage

If Pinecone not configured:

• Stores in wp_mxchat_system_prompt_content table
• Includes product content, URL, and serialized embedding
• Works for smaller catalogs (up to ~500 products)
• No external dependencies

Product Matching

When users mention products, the system:

1. Extracts product-related terms from message
2. Generates embedding for search query
3. Searches knowledge base using cosine similarity
4. Returns most relevant product (80%+ similarity by default)
5. Falls back to direct name matching if embedding search fails

Product Recommendations

How Recommendations Work

1. Context Gathering:
   • Retrieves user’s last 5 orders (if logged in)
   • Gets current cart contents
   • Checks recently viewed products
2. AI Analysis:
   • Sends user’s question + context to AI
   • AI generates specific search suggestion
   • Considers order history and preferences
3. Embedding Search:
   • Generates embedding for AI suggestion
   • Searches knowledge base for matching products
   • Returns top 5 most relevant products
   • Filters out products already in cart
4. Product Selection:
   • Keeps up to 4 unique products
   • Validates purchasability and stock
   • Removes duplicates
5. Response Generation:
   • Creates AI prompt with product list and user context
   • AI writes personalized introduction
   • AI explains why each product recommended
   • References order history when relevant
   • Responds in user’s language automatically
6. Display:
   • Shows numbered list (1-4)
   • Each product has image, name, price
   • AI justification below each product
   • Clickable images link to product pages

Recommendation Quality

Recommendations are highly relevant because they:

• Use actual purchase history to understand preferences
• Consider what’s already in cart to avoid duplicates
• Analyze the specific question/request context
• Use semantic search (not just keyword matching)
• Benefit from AI understanding of product relationships

Multilingual Support

• Detects language from user’s message
• Falls back to browser language if unclear
• AI responds in detected language
• No translation needed—native responses
• Works for all AI-supported languages

AI Model Support

The WooCommerce add-on uses your configured AI model from MxChat settings. Supported models for product recommendations and order assistance:

OpenAI Models

• GPT-4o (recommended)
• GPT-4o-mini
• GPT-4 Turbo
• GPT-3.5 Turbo

Claude Models

• Claude 3.5 Sonnet (recommended)
• Claude 3 Opus
• Claude 3 Sonnet
• Claude 3 Haiku

Google Gemini Models

• Gemini 1.5 Pro (recommended)
• Gemini 1.5 Flash
• Gemini 1.0 Pro

xAI Models

• Grok Beta

DeepSeek Models

• DeepSeek Chat
• DeepSeek Coder

Note: AI model selection is configured in MxChat → Settings → General. The WooCommerce add-on automatically uses your selected model.

Troubleshooting

Best Practices

Product Descriptions

• Write detailed, descriptive product descriptions (AI learns from these)
• Include key features, benefits, and use cases
• Use natural language that customers might use
• Add synonyms and alternative names in descriptions
• Keep short descriptions concise (shown in search results)
• Use proper formatting (paragraphs, bullets) for readability

Product Images

• Use high-quality, clear product images
• Set proper featured images (required for product cards)
• Optimize image file sizes for faster loading
• Use consistent image dimensions across products

Intent Configuration

• Create all 5 WooCommerce intents for full functionality
• Use varied trigger phrases (10-15 per intent recommended)
• Include common misspellings and variations
• Test each intent thoroughly before going live
• Adjust similarity thresholds based on matching accuracy
• Review intent logs to improve trigger phrases

Embedding Strategy

• Use Pinecone for large catalogs (500+ products)
• WordPress database fine for smaller stores
• Choose embedding model based on:
  • OpenAI Ada: Best balance of speed and quality
  • Voyage: Higher quality for complex products
  • Gemini: Good free tier option
• Sync products during off-peak hours if possible
• Monitor API usage and costs

AI Model Selection

• GPT-4o: Best overall quality for recommendations
• Claude 3.5 Sonnet: Excellent for detailed explanations
• Gemini 1.5 Pro: Strong multilingual support
• GPT-3.5 Turbo: Fast and cost-effective for basic use
• Test different models to find best fit for your products

User Experience

• Enable toolbar for easy cart and order access
• Customize button text to match your brand voice
• Consider hiding prices for quote-based businesses
• Test the complete shopping flow regularly
• Monitor cart abandonment and adjust messaging
• Use clear product names that AI can easily identify

Performance

• Cache enabled by default for knowledge base searches
• Product embeddings generated once and stored
• Cart operations use WooCommerce’s native caching
• Minimize unnecessary product republishing (triggers resync)
• Monitor server resources with large catalogs

Testing

• Test with actual customer scenarios
• Try various ways of asking for same product
• Test as logged-in and guest users
• Verify cart synchronization across devices
• Test all variable product combinations
• Check mobile responsiveness of dropdowns
• Test in different languages if multilingual site

Technical Details

Database Tables

• wp_mxchat_woo_product_mentions: Tracks product discussions in chat
• wp_mxchat_system_prompt_content: Stores product embeddings (if not using Pinecone)

Transients Used

• mxchat_last_discussed_product_{user_id}: Stores last discussed product ID (1 hour)
• mxchat_system_prompt_embeddings: Caches product embeddings (1 hour)

AJAX Actions

• mxchat_woo_add_to_cart – Add simple product to cart
• mxchat_woo_get_cart_count – Get current cart item count
• mxchat_woo_get_cart_contents – Get full cart contents
• mxchat_woo_remove_cart_item – Remove item from cart
• mxchat_get_variation_data – Get variation details
• mxchat_add_variation_to_cart – Add variation to cart
• mxchat_woo_get_recent_orders – Get user’s recent orders

WordPress Hooks

• wp_insert_post – Triggers product sync on publish
• wp_trash_post – Triggers deletion from knowledge base
• before_delete_post – Triggers permanent deletion cleanup
• woocommerce_update_product – Tracks product updates
• added_to_cart – WooCommerce cart event
• wc_fragment_refresh – WooCommerce cart refresh

Custom Filters

• mxchat_available_callbacks – Registers WooCommerce intents
• mxchat_handle_product_inquiry – Product card generation
• mxchat_handle_product_recommendations – Recommendation engine
• mxchat_handle_add_to_cart_intent – Add to cart logic
• mxchat_handle_order_history – Order retrieval
• mxchat_handle_checkout_intent – Checkout redirect
• mxchat_chatbot_toolbar_end – Injects cart/order icons

JavaScript Events

• added_to_cart – Fired when product added
• removed_from_cart – Fired when product removed
• updated_cart_totals – Fired when cart totals change
• wc_fragment_refresh – Forces cart fragment update
• mxchatFormSubmitted – Custom form submission event

Nonce Validation

All AJAX requests use mxchat_nonce for security. Nonces are:

• Generated on page load
• Validated on server for every AJAX call
• Tied to user session
• Automatically refreshed by WordPress

Product Matching Algorithm

1. Extract search terms from user message
2. Clean and normalize terms (remove punctuation)
3. Get all published products
4. Score each product based on:
   • Name similarity (string matching)
   • Word matches in name (30 points each)
   • Word matches in SKU (20 points each)
   • Word matches in description (10 points each)
   • Purchasability bonus (15 points)
   • Stock availability bonus (included in purchasability)
5. Sort by score descending
6. Return product if score ≥30
7. Fall back to transient if score too low

Embedding Dimensions

• OpenAI Ada-002: 1536 dimensions
• Voyage models: 1024-2048 dimensions (model dependent)
• Gemini: 1536 dimensions (configurable)

Performance Considerations

• Embeddings cached for 1 hour (reduces API calls)
• Batch loading of embeddings (500 at a time)
• Cart operations use WooCommerce’s session storage
• AJAX requests timeout after 30 seconds
• AI requests timeout after 60 seconds
• Product sync happens on shutdown hook (non-blocking)

Frequently Asked Questions

Use Cases & Examples

Need Help?

If you’re experiencing issues not covered here:

• Visit MxChat.ai for documentation and updates
• Check our YouTube channel for video tutorials
• Review WooCommerce’s own documentation at WooCommerce.com
• Check browser console for JavaScript errors
• Enable WordPress debug logging to catch PHP errors
• Contact MxChat support with your license key, WooCommerce version, and detailed description of the issue

Common Support Information Needed

When requesting support, include:

• WordPress version
• WooCommerce version
• MxChat version
• Active theme name
• List of active plugins
• PHP version
• Browser console errors (if applicable)
• Steps to reproduce the issue