Troubleshooting & Frequently Asked Questions (FAQ)

This guide provides answers to common questions and troubleshooting steps to ensure your Visperity AI search and virtual assistant operate smoothly.

1. Troubleshooting Guide

Issue 1: The widget or search dropdown is not appearing on my website

  1. Check Script Placement:
    • Verify that you copied the exact <script> tag from the Embed Code tab of your builder.
    • Ensure the script is placed right before the closing </body> tag on your website template.
  2. Verify Approved Domain Whitelist:
    • In Datasets & Knowledge, click ✏️ Edit on your active dataset.
    • Check the Approved Domains field. If you entered domain names (e.g. yourstore.com), ensure your live website domain is included. (Tip: If testing locally or on a staging domain like staging.yourstore.com, add both to the whitelist or leave the field blank to allow all domains).
  3. Verify Target CSS Classes & Field Names:
    • For Live Search: Ensure your search input or form container has the exact class configured in search_container (e.g. class="sbpro-search-container").
    • For Embedded Search: Ensure your results page has a container element with the class configured in embeeded_search_target_class (e.g. <div class="sbpro-embedded-container"></div>).

Issue 2: A search query is not returning the expected product

  1. Check Knowledge Base Indexing:
    • Go to Datasets & Knowledge and use the search bar above the table to check if the product or article URL is indexed in your dataset.
    • If missing, use the Single Page Crawler or Manual Document Ingestion to index it.
  2. Check Exact SKU / Keywords:
    • Click ✏️ Edit on the record and verify that your product SKUs or tags are listed under Product SKUs / Custom Keyword Tags (e.g. WH-1000, HEADPHONES).
  3. Check Language Gating:
    • If searching on a localized store page (e.g. in Spanish), verify that you have translated the record into that language. Because Visperity enforces strict language gating, Spanish searches only return Spanish-indexed records.

Issue 3: How do I update prices or product descriptions?

  • Option A (Manual Edit): Go to Datasets & Knowledge, find the product row, click ✏️ Edit, update the Price (e.g. $39.99) or Content, and click Save & Re-Vectorize Record.
  • Option B (CSV Re-Upload): If you manage prices in a master CSV spreadsheet, simply upload an updated CSV via CSV Bulk Upload. Visperity will update the existing records and recalculate embeddings automatically.
  • Option C (Rest API): Update titles, content and pricing data via the REST API.
  • Option D (Workflow Automation): Update pricings via an automation setup through a provider such as Zapier.
  • Option E (Site Store Pro Direct Updates): If you are using Site Store Pro as your ecommerce platform, pricing and content updates will automatically (natively) update the indexed records on Visperity AI after setting up the API linkage in the Site Store Pro admin settings panel.

Issue 4: How do I remove a discontinued product or deleted page?

  • Go to Datasets & Knowledge, find the record, and click the red Delete button. It will immediately be removed from the vector database and will no longer appear in search results or AI recommendations. *** If you are using the REST API, you can easily setup an automation process to delete content in realtime when there is a change on your ecommerce platform and/or CMS. If you are using Site Store Pro as your ecommerce platform, products and cms content deletes or status changes are automatically propagated into your Visperity AI indexing.

2. Frequently Asked Questions (FAQ)

Q: How quickly do changes made in the dashboard go live on my website?

A: Whenever you click Save Settings, Visperity automatically updates and deploys your configuration to Amazon CloudFront CDN within seconds. However, you must install the newly created script on your site. Due to global CDN caching of JS and CSS, installing the new script ensures that your customers will see the most recent configuration changes.

NOTE: New data URL records, updates or deletions in your dataset(s) are instantly visible and do not require a new script installation. Only configuration changes to your AI widgets require a new script install. All data record changes / deletions are real-time.

Q: Will Visperity slow down my website?

A: No. Visperity widgets and scripts are loaded asynchronously (async) and delivered through high-speed global CloudFront CDN servers. They never block your page layout or affect your website's core web vitals.

Q: Does Visperity work with mobile devices?

A: Yes. All three widgets (AI Virtual Assistant, Live Search dropdown, and Embedded Search results) are fully responsive and optimized for mobile screens, tablets, and desktops.

Q: What is the recommended format for thumbnail images?

A: Square or 4:3 aspect ratio images in standard web formats (.jpg, .png, .webp) hosted on secure https:// URLs work best. You can also upload photos directly using the Upload to CDN button on any ingestion or edit form.

Q: How can I segment my datasets to use with specific areas on my site such as my online store products only or my knowledge base articles?

A: To segment a specific area of your site to use with any of the Visperity tools, simply create a new dataset and add that content only (URLs) to that dataset. If you install the script for that tool based on that dataset, it will limit the results only to the ingested URLs content.

You can also add the same content (URLs) to your main site dataset as well if you want to provide resource links from BOTH your primary site dataset and your secondary (segmented) site dataset.

[!NOTE] We provide a very generous number of quota URLs in every plan specifically to account for situations where the site requires duplication of some URLs in multiple datasets. We have not encountered any merchants who exceeded their content URL quota even when segmenting with different datasets. The primary reason most merchants will need to upgrade to a higher quota plan is due to the site usage (unique users) exceeding their plan’s sessions quota and not the available number of indexable URLs in their plan.

Q: What is the difference between Category Tags and Dataset Segmentation?

A:

  • Category Tags (User Experience Labeling): Category tags are a visual labeling feature designed to enhance the customer browsing experience. When you tag a record with a category (e.g. PRODUCTS, SUPPORT FAQ, SHIPPING), that label appears in bold directly above the product/article title in Live Search dropdowns, Embedded Search results, and AI Virtual Assistant chat cards. Category tags do not restrict or filter search results—they provide clear visual context for visitors.
  • Dataset Segmentation (Content Isolation): If you want a specific search box or chat widget to search only certain pages (for example, searching only documentation on /help and only products on /shop), create separate Datasets. Each dataset has its own unique embed script that strictly limits search results to its ingested URLs.

Q: How does Visperity protect customer privacy?

A: Visperity only references product information and articles that you choose to index into your dataset. Customer search logs are stored securely in your private merchant account and are never shared or used to train public AI models.

← 6. Multi-Language & Translations 📚 All Documentation Guides Documentation Hub →