Work from the outer runtime boundary inward. Fix the first failed layer before changing relevance thresholds, prompts or presentation.
1. Record the test context
Record Assistant version, WordPress, PHP, WooCommerce, theme/page builder, active language, exact page, timestamp and timezone, user state (guest/admin), expected behaviour and the first visible error. Use a private browser session for the reproduction.
Do not include complete licence/API keys, passwords, order details or customer personal data.
2. Licence gate
Open NAI Assistant → License.
- Status must be Active or a still-valid Grace period.
- Runtime access must be Enabled.
- Product must be Assistant.
- Activated domain and environment must match the current installation.
Use Refresh status. Domain mismatch, wrong product, invalid key, disallowed environment and activation-limit responses require correcting the entitlement; cache clearing cannot fix them.
3. Provider and models
Open Settings → General.
- Test the selected chat provider.
- Test the selected embedding provider.
- If Smart/Hybrid routing is enabled, test every approved role provider.
- Confirm provider billing and model entitlement.
- Confirm an image-capable model exists before diagnosing visual search.
Temporarily switch to One fixed model to isolate a routed-provider failure. Do not revoke the old key until a replacement is proven.
4. Product index
Open Dashboard.
- Compare indexed and total products.
- Check whether the embedding provider/model changed.
- Run Reindex all when the signature is incompatible.
- Keep Action Scheduler/WP-Cron operating until completion.
- Run Advanced → Search test with an exact name and natural-language request.
Correct WooCommerce title, category, attributes, variation, stock, SKU or custom-field data before adjusting relevance.
5. Knowledge Base
- Confirm the intended source is published, public, selected and in the right language.
- Inspect Knowledge overview counts and run the exact query diagnostic.
- Rebuild after embedding, post-type or broad source-scope changes.
- Clear response cache and use a new conversation.
- Add a training link only after the authoritative page is correct.
If a support request shows a blog card, verify that a dedicated guide/procedure exists and is indexed.
6. Front-end widget and embed
- Confirm Floating widget or the intended block/shortcode/profile is enabled.
- Clear WordPress, builder, CDN and browser caches.
- Check duplicate global/profile/Elementor surfaces.
- Test at 320–430 px and keyboard-only.
- For external embeds, verify exact HTTPS origin and Content Security Policy.
Cart, checkout, order lookup and stock subscription are intentionally unavailable in an external cross-site iframe.
7. WooCommerce actions
- Confirm WooCommerce integration is enabled.
- Verify product and variation are purchasable.
- Compare cart session, quantities and totals with native WooCommerce.
- Test shipping/tax inputs before comparing checkout totals.
- Verify order lookup with order number and billing email.
- Confirm WordPress email for contact and stock alerts.
8. Rate limits, cache and background work
- Determine whether chat or other-action rate limit was hit.
- Check trusted proxy/CDN IP handling.
- Clear Assistant response cache after source or settings changes.
- Inspect Action Scheduler or WP-Cron for queued work.
- On low-traffic sites, configure a real server cron through the host.
9. Technical diagnostics
Enable Diagnostic logging only for the bounded reproduction. Keep PII redaction on. Reproduce once, open the affected conversation and inspect the first warning/error, provider call, candidate/source list and final outcome.
Export problematic logs only, review locally and remove unrelated personal data before support. Return logging to Standard afterward.
Symptom map
| Symptom | First checks |
|---|---|
| Assistant hidden/read-only | Licence runtime, floating/profile setting, cache |
| Chat error but Search test works | Chat provider/model, routing role, rate limit |
| Chat works but products are empty | Woo integration, embedding provider, index |
| Exact product found, use-case request fails | index freshness, attributes/content, relevance diagnostics |
| Wrong policy/source | source scope, language, KB rebuild, cache |
| Image upload missing | configured vision key/model |
| Cart differs from WooCommerce | session, variation, cache/fragments |
| External embed has no commerce actions | expected security boundary |
| Messages/emails missing | contact/stock feature, sender/recipient, WordPress mail |
| Old behaviour after update | version, caches, index signature, fresh session |
Safe recovery order
- Back up.
- Correct licence/domain/environment.
- Correct provider/key/model.
- Repair cron/background worker.
- Rebuild product and Knowledge Base indexes only when required.
- Clear relevant caches.
- Retest in a fresh session.
- Change thresholds or training only with diagnostic evidence.
Support package
Include versions, timestamp/timezone, exact safe steps, expected/actual result, language/page, licence status without the key, selected provider/model names, index counts/state, the first safe error and the smallest redacted problematic-log export.