WooCommerce plugin docs / AI Chat

AI Chat

Overview

The storefront chatbot is the main interface. It is a floating launcher and/or an inline shortcode. Shoppers send a message; the server runs one turn (native catalog search or an AI agent loop with approved tools) and returns text plus structured UI (product cards, cart, confirmation, comparison).

Conversational AI is optional. Without an API key, the same widget searches WooCommerce and shows fallback messages.

How It Works

  1. Page loads an empty widget shell (no nonce in HTML, so page cache cannot freeze an old nonce).
  2. Widget calls GET /wp-json/aiwsa/v1/config (uncacheable) for nonce, appearance, feature flags, fallback strings, quick actions.
  3. Widget POST /wp-json/aiwsa/v1/conversations (channel widget or shortcode).
  4. Each send: POST /wp-json/aiwsa/v1/conversations/{uuid}/messages.
  5. If a provider is configured: Turn_Handler → prompt + tools → WooCommerce data → reply.
  6. If not: Catalog_Search_Turn → search/recommend/order tools without an LLM.
  7. Widget renders bubbles, cards, mini-cart, checkout button.
Customer input
    → Session + rate limit + language resolve
    → Intent / catalog search (optional AI)
    → Approved tools (search, Q&A, cart, orders, …)
    → Live WooCommerce data
    → Response + UI payload
    → Frontend cards / confirm / checkout URL

How to Enable It

  1. WordPress Admin → WooCommerce → AI Assistant → Settings → General → Enable AI Agent
  2. Settings → Appearance → Show floating assistant (or place the shortcode)
  3. Optional: AI Provider for LLM replies

Configuration

See General, Appearance, Chatbot, AI Provider, AI Language.

Frontend Usage

  • Click the launcher (bottom right or left).
  • Type and send, or tap a Quick Action.
  • Use product cards: view, add, notify me (out of stock).
  • Open the cart icon for totals, quantity, remove, checkout.

Example

A shopper on /shop/ opens the launcher, types “12V starter motor”, and receives product cards with live prices. With Gemini connected, they also get a short sentence introducing the matches.

Behavior

SituationWhat happens
API connectedAgent loop + tools
API not connectedNative catalog turn + fallback copy
Empty searchNo Products Found fallback
Invalid / too long messageREST validation error
Rate limit429
Enable AI Agent offWidget not rendered; REST refuses
Daily token budget spentDegrades to WooCommerce search
Provider timeout / 5xxFallback provider if set; else fallback messages / catalog
Invalid API keyProvider error → fallback path

Limitations

  • Bundled widget uses blocking POST, not SSE streaming (even if Transport is Streaming).
  • No Gutenberg block and no Elementor widget.
  • Conversation channel enum includes block for internal use; there is no block UI.
  • Guest identity uses a signed cookie/token model, not WordPress users.

Troubleshooting

See Troubleshooting (chatbot not appearing, JS errors, REST 404).

PreviousCart RecoveryNextAI Configuration