Skip to main content

FAQ editor + embed widget

Plans: Growth · Pro · Agency (FAQ editor is plan-gated; the embed widget is gated by the editor — Starter cannot author FAQs and therefore has nothing to embed)

Clione lets you author FAQs per Product, Variant, Category (BigCommerce) / Collection (Shopify), Page, or Globally — then serve them on your storefront with a single embed snippet, with a matching FAQPage JSON-LD block for crawlers and LLMs.

This page is about authoring, generating, importing, and the embed widget. For per-platform install details (BigCommerce Stencil, Catalyst headless, Shopify theme editor, Hydrogen / Next), see FAQ widget install.

Where it lives​

Sidebar → store → FAQs.

Five tabs:

  • Browse — search, edit, soft-delete, restore.
  • Add — manual create, one at a time.
  • Generate — LLM drafts (Growth and above).
  • Import — bulk CSV upload.
  • Embed Script — get the snippet for your storefront.

Entity parity — what you can attach FAQs to​

Clione treats FAQs as a first-class entity with the same parity rule as enrichment: FAQs work across every entity type on both platforms.

Entity typeBigCommerceShopifyNotes
ProductyesyesThe most common attachment.
VariantyesyesUseful for size/color/material specific questions.
Categoryyesn/aBC categories.
Collectionn/ayesShopify collections (same concept).
PageyesyesAbout / Shipping / FAQ content page.
GlobalyesyesApplies to every render — shipping, returns, warranty.

Global FAQs are merged with entity-specific FAQs on every render. A product page shows its own FAQs plus the global set, in the order you control with sortOrder.

1. Adding FAQs manually​

FAQs → Add:

  1. Pick Entity Type (Product / Variant / Category / Collection / Page / Global).
  2. Search for the entity by name. The picker shows display names, not raw IDs.
    • For Global, no entity is selected — the FAQ applies storewide.
  3. Write the Question and Answer.
  4. (Optional) Set Locale if you publish multiple languages.
  5. (Optional) Set Sort Order to control display order. Lower = first.
  6. Save.

New FAQs are immediately visible to the embed widget — no propagation step.

2. Generating FAQs automatically (Growth and above)​

FAQs → Generate is plan-gated. On Starter the tab is hidden — the whole FAQ section sits behind a LockedFeature feature="faq" route. Growth, Pro, and Agency see it.

The Generate panel sends the entity's enriched data (title, identity, reasoning, keywords) to your LLM and gets back a small batch of suggested Q&A pairs. You can:

  1. Pick the scope — one entity, a list of entities, or "everything in this store".
  2. Pick how many drafts per entity (default 5, max 10).
  3. Click Generate.

Drafts are saved automatically as status=approved and ready to serve. Edit or delete any you don't like from the Browse tab.

LLM cost is metered against your plan's enrichment quota — generating 50 product FAQs counts as 50 enrichment calls.

3. Bulk import (CSV)​

FAQs → Import accepts a CSV with this header:

entityType,entityId,question,answer,locale,sortOrder
product,SKU-001,What is the warranty?,2-year manufacturer warranty,en,0
collection,summer-sale,When does the sale end?,Sunday at midnight CET,en,0
global,,What are your shipping times?,2–5 business days within the EU,en,0

Notes:

  • entityType accepts: product, variant, category, collection, page, global.
  • entityId is empty for global. For everything else, use the platform's native ID (BC product ID, Shopify GID, page handle, etc.).
  • locale is a BCP-47 tag (en, es, es-ES, fr-FR). The widget filters by the page's lang attribute when present.
  • sortOrder is integer, ascending. Defaults to 0.
  • Header row is required. UTF-8 encoding. Excel users: save as "CSV UTF-8".

The importer dedupes by (entityType, entityId, question, locale). Re-importing a row updates answer and sortOrder; the FAQ ID is preserved so the embed cache doesn't churn.

4. Exporting​

Two paths:

  • Per-entity — in Browse, filter by entity and click ↓ Export CSV.
  • Whole store — top of the FAQs page → ↓ Download all FAQs (CSV). One file, every FAQ across every entity, globals included.

Export uses the same column set as Import, so a round-trip (export → edit in Excel → re-import) is non-destructive.

5. The embed widget​

FAQs → Embed Script is the source of the snippet you paste on your storefront.

Required setup​

Before the widget can fetch anything, you need:

  1. An API key with the products:read scope.
  2. At least one Allowed Domain on that key (e.g. shop.example.com, *.example.com).

Both are configured under Store → Settings → API Keys — see Store settings and API authentication. Without allowedDomains, the widget gets 403 from the API to block scraping.

The snippet​

<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_…"
  data-target="#clione-faq"
  async
></script>

The loader auto-detects the current page entity from, in order:

  1. data-entity-type + data-entity-id attributes on the script tag (explicit override).
  2. OpenGraph meta tags (og:type="product", product:retailer_item_id).
  3. URL patterns: Shopify /products/, /collections/; BigCommerce /product/, category URLs; WooCommerce body classes; etc.

It then fetches the matching FAQs (entity-specific + global, merged), and injects:

  • A visible accordion at the target selector.
  • An invisible JSON-LD FAQPage block for crawlers and LLM ingestion.

"Powered by Clione" badge​

Starter and Trial plans render a small Powered by Clione badge at the bottom of the accordion. The badge stays — toggling it off requires Growth or above and is controlled from Org → Brand, see Branding settings.

This is policy, not a bug. The branding toggle in Settings is disabled on Starter / Trial and the API enforces it on the embed side as well.

Per-platform install​

The snippet itself is the same on every storefront, but where you paste it differs:

  • BigCommerce Stencil — global footer or per-template injection.
  • BigCommerce headless / Catalyst — page component import.
  • Shopify theme editor — Custom Liquid block or theme.liquid.
  • Hydrogen / Next.js / Nuxt — see the headless guides in the Developers sidebar.

Full step-by-step lives in FAQ widget install. The BigCommerce Schema Injector (which auto-installs the JSON-LD plumbing for products) is a separate feature — see Schema injector.

Troubleshooting​

The widget renders empty — the FAQ list returned 0. Check: (1) you actually have FAQs for this entity or globally, (2) the locale filter matches the page's <html lang>, (3) you're not on a draft / unpublished entity ID.

403 Forbidden — the request's Origin / Referer isn't in allowedDomains for the API key. Add the domain on the key and reload.

JSON-LD doesn't show up in View Source — on Shopify, JSON-LD requires the theme app block to be enabled. On BC, the embed snippet writes it directly. See Schema injector for the platform-specific details.

Generate tab is missing — your plan doesn't include feature=faq. Upgrade to Growth or above in Billing.

Widget renders FAQs but the JSON-LD is missing — Check that the FAQ widget script tag is loaded before any other JSON-LD-emitting script. The widget appends to the head; if another script wipes the head later, the JSON-LD disappears. Inspect with the browser dev tools (Elements → head → search for FAQPage).

FAQs duplicate across multiple page renders — Common when the widget script is loaded twice (e.g. once in the theme header and once in a custom template). Confirm only one script tag with src="api.clione.ai/embed.js" exists per page.

Locale filter shows all FAQs regardless of <html lang> — The page's lang attribute may be missing or malformed (BCP-47 expected). Inspect with document.documentElement.lang in the console. Add the attribute server-side (BC: edit the theme's <html> element; Shopify: ensure your Markets language is configured).

Per-platform notes for FAQ authoring​

BigCommerce​

  • Variant FAQs — BC product variants are first-class entities with their own IDs. When you attach a FAQ to a variant in the editor, the entity picker shows the variant's option selection (e.g. "Size: M, Color: Blue"). The FAQ renders only on the variant's selected state, which BC theme templates expose via the variant_id query string.
  • Category FAQs — render at the top of the category description on the BC Stencil template.
  • Page FAQs — render at the bottom of BC content pages.
  • Global FAQs — render on every page where the widget script runs.

Shopify​

  • Variant FAQs — Shopify variants have a variantId per option combination. The widget detects the current variant from the page's variant selector and shows the variant-specific FAQs. Note: themes that don't trigger a re-render on variant change won't refresh the FAQ list — the widget polls the URL ?variant= parameter and re-fetches on change.
  • Collection FAQs — render at the top of the collection page above the product grid.
  • Page FAQs — render at the bottom of Shopify content pages.
  • Global FAQs — render on every page where the widget script runs.

Generation cost details​

The Generate tab counts each generated FAQ against your enrichment credit quota:

  • 1 product × 5 FAQs = 5 credits.
  • 1 product × 10 FAQs (max) = 10 credits.
  • 50 products × 5 FAQs = 250 credits.

The dashboard shows the projected credit consumption before you click Generate. You can cancel before the cost confirmation if it exceeds your budget.

Embed script — full reference​

The embed script (https://api.clione.ai/embed.js) accepts the following data-* attributes:

AttributeRequiredDefaultDescription
data-api-keyYes—Your store's API key with products:read scope.
data-targetNo#clione-faqCSS selector where the widget mounts.
data-entity-typeNoauto-detectOverride: product, variant, category, collection, page.
data-entity-idNoauto-detectOverride the entity ID.
data-localeNopage langForce a specific locale.
data-maxNo10Maximum number of FAQs to show.
data-themeNoautolight, dark, or auto (follows OS preference).
data-render-json-ldNotrueSet to false to suppress the JSON-LD block (if you render your own).
data-debugNofalseLogs detection + fetch decisions to the console.