Install the WooCommerce AI chatbot plugin

The WooCommerce integration ships as a WordPress plugin that authenticates to the Zubby SaaS using a Bearer token + an X-Store-ID header. Once paired, the plugin pushes your catalog to Zubby in the background, registers WooCommerce webhooks for products, orders, customers, and coupons, and auto-injects the widget on your storefront pages.

WordPress requirements

PHP 8.2+, WordPress 6.4+, and WooCommerce 8.0 or newer (tested up to WooCommerce 11.2.1). WooCommerce must be active - the plugin declares it as a required plugin.

Get the plugin

From your Zubby dashboard open Imports → WooCommerce and click Download Zubby AI plugin (.zip). The zip always serves the latest release; once installed, the plugin also self-updates through WordPress’s normal plugin-updates screen.

Install in WordPress

Open the WordPress admin
Go to Plugins → Add new → Upload plugin.
Upload the zip
Choose the downloaded salespilot-ai-for-woocommerce-x.y.z.zip, click Install now, then Activate.
Open the settings page
Find Zubby AI in the WordPress admin sidebar (it also appears as a tab under WooCommerce settings).

Connect to Zubby

There’s no setup code to copy. Click Log in & Connect on the plugin page (or Create account if you are new to Zubby). Pairing is a browser handshake:

The plugin sends you to /connect/woo on the Zubby app with your site URL, a plugin key, and a WordPress nonce that binds the handshake to your admin session.
You sign in (or create an account) and click Approve Connection. Zubby provisions the store and posts the credentials back to your WordPress admin.
The plugin encrypts the store token with your WordPress salts (AES-256-GCM) before storing it, registers WooCommerce webhooks for product, order, customer, and coupon events, and queues the first catalog sync.

App base URL

The plugin defaults to https://app.zubbyai.com. You only need to change the Zubby App URL field (on the plugin’s Advanced tab) if support has pointed you at a different environment - for approved non-production test setups.

First catalog sync

The first sync starts automatically after pairing and runs in the background via Action Scheduler - the plugin pushes products in batches of 100, plus shipping zones, historical orders and customers, and your store pages for the knowledge base. Duration depends on the host, catalog, REST limits, Action Scheduler, network, queues, providers, and retries; you can leave the page and check back. Need to re-run it? Both the plugin page and Dashboard → Catalog have a manual sync trigger.

Verify the wiring

Three health checks confirm the plugin is talking to Zubby:

The plugin page shows Connected with your paired workspace, plus a webhook-health panel (with a Repair Webhooks button if a topic went missing).
Dashboard → Catalog in Zubby lists the product count you’d expect.
Dashboard → Imports → WooCommerce shows the plugin connection, webhook health, and sync-job history in one place.

How the widget gets onto your storefront

The plugin enqueues its bridge script and the widget on every storefront page via standard WordPress hooks (wp_footer-based). By default the widget is hidden on the checkout page (a toggle), and you can also hide it on the cart page or disable it entirely from the plugin settings - widget appearance itself is managed in the dashboard’s Widget Designer. For what the bridge passes to the widget (cart, page, and logged-in customer context), see the widget bridge guide.

Troubleshooting

Start with the observed symptom and inspect connection and job status before changing credentials or retrying a sync:

Symptom	Fix
Plugin activates then crashes with a fatal error.	Check the PHP version and WordPress error log. PHP < 8.2 is unsupported, but a fatal error can have other causes. Use PHP 8.2+ and share the redacted error with support if it persists.
Handshake fails / “Reconnect Store” loops.	Check whether your host or security plugin blocks outbound HTTPS to `app.zubbyai.com`. Allow the required endpoint through a narrow security rule, then run Reconnect Store from the Connection panel.
Catalog sync never runs.	The sync runs through Action Scheduler, which piggybacks on WP-Cron. If your site has no traffic or WP-Cron is disabled, trigger it manually or wire a real cron to `wp-cron.php`.
401s on sync or webhook calls.	Credential drift between plugin and SaaS. Click Regenerate credentials in the plugin’s Connection Management panel; it rotates and re-stores a fresh secret on both sides.
Webhook events stop arriving.	A topic was deleted or disabled in `WooCommerce → Settings → Advanced → Webhooks`. Click Repair Webhooks on the plugin page to re-register the required topics.

Order help and platform limits

Order status uses synced data; verify the last sync before treating a stale status as a live fulfillment fact. Cancel, edit, and refund requests create high-priority human tickets on WooCommerce, even when the related AI switch is enabled. Address changes are a separate path: the connected plugin can update an eligible unfulfilled order after verified ownership and explicit confirmation. The address switch is on by default. Review the action matrixbefore enabling any write behavior.

The assistant holdout can suppress the widget and record visitor counts on WooCommerce. The current cart-token join does not produce a valid WooCommerce order-conversion lift result; do not use visitor suppression alone as evidence of incremental revenue.

Worked verification: a product and a handoff

Illustrative staging test: create a test product with two sizes, set one out of stock, and add a short approved returns policy. After sync and indexing, ask for the unavailable size, compare the price with WordPress, and ask about the return window. The expected answer preserves the unavailable state and policy terms. Then request a cancellation on an owned test order: find its ticket in Inbox → Conversations → Ticketsand verify that the WooCommerce order was not silently cancelled.

If prices differ, inspect the synced variant and job status. If the widget is missing, check plugin visibility settings, audience rules, checkout suppression, caching, and widget troubleshooting. A green connection verifies authentication, not every storefront or payment workflow. Keep real shopper data out of staging tests.

Updates

The plugin self-updates through WordPress’s standard plugin-updates screen: it checks Zubby’s release manifest and only accepts download packages from allowlisted Zubby hosts, so a compromised manifest can’t redirect WordPress to arbitrary code. When a new version shows up under Plugins → Updates, update as you would any other plugin.

Where credentials live (advanced)

All plugin state is stored in a single salespilot_ai_settings row in wp_options. Secrets inside it (the API token, widget key, and plugin key) are encrypted at rest with AES-256-GCM keyed off your WordPress salts - so a raw database read doesn’t expose them, and wp option get shows only ciphertext. Every plugin → SaaS request authenticates with Authorization: Bearer <token> plus an X-Store-ID header, verified server-side with a constant-time compare.

Uninstalling

To fully unpair, click Disconnect in the plugin’s Connection Management panel first - that calls the SaaS to revoke the store credentials, then clears them locally. Deactivating the plugin alone just stops the sync schedules and widget injection on your site; deleting the plugin removes its options from wp_options. Your Zubby workspace and its analytics stay intact either way, so you can reconnect later.