Changelog

Version history for the public Humind surfaces: the widgets bundle, the chat loader, and this documentation site.

Product features and merchant-facing changes in the backend and dashboard are tracked in the dashboard's What's New panel; this page covers only the public embed surfaces.

Widgets bundle (widgets.thehumind.com/v1/loader.js)

v1 (current), April 2026

Initial public release of the unified widgets bundle. Replaces the previous quiz.thehumind.com host (which only served the collection quiz) with one bundle for three custom elements.

Custom elements:

• <humind-quiz>: collection discovery quiz
• <humind-gift-finder>: "ask anything" search block
• <humind-product-questions>: product-page Q&A

Breaking change from quiz.thehumind.com: the bundle URL changed from https://quiz.thehumind.com/humind-quiz.js to https://widgets.thehumind.com/v1/loader.js. The /v1/ prefix is new and will stay in the URL going forward. Update any theme blocks or script tags that still reference the old host.

Future: v2 (planned)

A breaking-change version will ship under /v2/. /v1/ stays live during the migration window. Subscribe to the Humind changelog in the dashboard for advance notice.

Chat loader (embed.thehumind.com/loader.js)

The chat loader is unversioned. Every deploy replaces the bundle. Significant changes in attributes, events, or behavior are recorded here.

April 2026

• Shadow DOM isolation for all widget styles.
• Internationalization for 11 languages.
• WebSocket-based live-operator handoff.

Documentation

2026-08-31: Two catalog URL settings removed

• The settings keys catalog.add_params_to_product_url and catalog.product_url_params are removed from the Settings endpoint. They were never applied by the assistant and no store had them enabled. Sending them now returns a validation_failed error like any unknown key.
• The capability they described now lives in the dashboard's product rules (Settings, Catalog, Product rules): the "append URL parameters" effect adds a merchant-defined query string to every product URL the assistant opens, per rule scope rather than store-wide.

2026-08-28: Custom cookie consent text setting

• New setting cookie_consent.custom_text (agent, string, max 500 characters, nullable) on the Settings endpoint: the merchant-authored consent prompt the widget shows instead of its built-in translated default. null restores the default text; the empty string is rejected.
• Per-locale variants of the prompt are managed from the dashboard and are not exposed through the public settings API.

2026-08-28: Shopify metaobject references resolved into readable labels

• For Shopify-connected stores, product metafields of type metaobject_reference and list.metaobject_reference now carry the referenced metaobject's display name in value instead of an opaque gid://shopify/Metaobject/... identifier, once the merchant has granted the additive read_metaobjects scope. The resolved value keeps the shape of the equivalent text type: a plain string for a single reference, a JSON array string for lists. Rollout is progressive: stores that have not reconnected keep the raw identifiers.
• No schema change: metafields[].value stays a string, and the type field is unchanged. If your integration matched the gid:// prefix in metafield values, treat resolved labels as the new normal form.

2026-08-19: Webhook endpoints return a masked prefix and no checksum

• On GET /webhooks/endpoints, GET /webhooks/endpoints/:id, PATCH and the endpoint block of POST /rotate-secret, the prefix field is now masked (whsec_ + the first 4 and last 4 characters of the secret part, e.g. whsec_5f9e••••••••3f0c) and the checksum field is no longer returned. The two raw values together allowed the full signing secret to be rebuilt, which contradicted the "shown once" guarantee. POST /webhooks/endpoints and POST /rotate-secret still return the full secret at the top level, exactly once. If your integration compared prefix to the first characters of your stored secret, compare the visible 4 + 4 characters instead. Documented on the webhooks reference.

2026-08-19: Imports skip unchanged lines, and AI enrichment runs right after the import

• On POST /imports (and the product feed), a line identical to what was last imported for that product is no longer rewritten: it counts in report.updated but costs nothing. Products created or changed by an import get their AI enrichment (search embedding, generated questions) from a background job that starts when the import reaches done, so a product may take a few minutes after the import before the assistant recommends it. Both points are documented on the imports reference (report.updated, Enrichment after the import).

2026-08-18: website_visits and interaction_rate on long periods come from a daily roll-up

• On GET /analytics/kpis (and the MCP get_kpis tool), website_visits and interaction_rate are unchanged up to 90_days: distinct visitors over the whole window, trend included. For year, total and custom ranges reaching back more than 180 days, both KPIs and their trend are now summed from a daily roll-up, where a visitor who came back on several days counts once per day. Values on those periods are slightly higher than before; sessions and conversations are unaffected. Documented in the analytics reference.

2026-08-17: cart_url puts a "Go to checkout" button on function confirmations

• New optional field cart_url on function cart actions: your cart or checkout page. When set, the confirmation toast the widget shows after a successful add offers a "Go to checkout" button that opens it, the same shortcut Shopify, PrestaShop and WooCommerce merchants already have. When omitted, nothing changes: the toast keeps hiding the button, since the widget has no cart of its own to open on a custom storefront. Reads echo the field. The add to cart guide shows it in the example.

2026-08-15: errorName drives what the shopper is told

• A failed add to cart used to be silent: the button simply went back to normal, whatever the reason. The widget now shows a translated message in all 11 of its languages, and the errorName your function cart action returns is what picks it. Ten names are recognized, listed in the guide. Nothing is required of you: errorName stays optional, and a name we do not recognize produces a generic message rather than an error.
• selection_required is not a message, it is a redirect. Return it when the shopper has to pick something first, and the widget sends them to your product_url instead of showing a dead end.
• Applies to every platform, not only function actions: Shopify, PrestaShop and WooCommerce failures are mapped onto the same names and get the same messages.

2026-08-14: redirect cart actions declare their destination with target

• New optional field target on redirect cart actions, with two values: product_page (url is a product page, the CTA reads "View product" and links straight through) and add_to_cart (url is a deep link that fills the cart, the CTA reads "Add to cart"). Both destinations have always been supported and the widget could not tell them apart, which is why the CTA read "View product" on every redirect since 13 August. It now follows what you declare.
• An omitted target means add_to_cart. If your redirect points at a product page, set "target": "product_page" on those variants: otherwise the button reads "Add to cart" and lands the shopper on your page with nothing added. The default errs this way on purpose, because the opposite mistake is a "View product" button that silently fills the cart. Merchants using an add-to-cart deep link have nothing to do, and this also replaces the previous advice to switch to a function action just to get an "Add to cart" label.
• Reads now echo the field: GET on a product returns target when one is stored. Native platforms (shopify, prestashop, woocommerce) and function actions are unaffected.

2026-08-13: redirect cart actions now show a "View product" CTA

• A variant whose cart action is redirect adds nothing inside the conversation: it sends the shopper to a URL. The widget now says so, labelling the CTA "View product" instead of "Add to cart", and linking straight to that URL. Products whose variants all use redirect no longer open the variant picker first: the shopper picks the variant on your own product page. Merchants who point redirect at an add-to-cart deep link keep working exactly as before, but their CTA now reads "View product" too, since the widget cannot tell one target from the other; use a function action when you want the button to promise an add to cart. Native platforms (shopify, prestashop, woocommerce) and function actions are unchanged.

2026-08-11: Widget confirmation toast for function cart actions

• On a successful function add to cart, the widget now shows its own in-conversation confirmation toast (product image, title and quantity, without the checkout shortcut). Merchant functions should no longer display their own confirmation modal: the chat window sits above the page (full-screen on mobile), so a page-level confirmation would be hidden behind it. The add to cart guide reflects the new contract. Failure and fallback behavior are unchanged.

2026-08-11: Removed setting widget.show_add_to_cart_button

• The setting widget.show_add_to_cart_button has been removed from the Settings API. Add-to-cart availability is now decided per product and per variant only (availability and cart action): the widget shows the button whenever the product can actually be added to the cart. Requests writing this key now fail with a 400 validation_failed error; remove it from any automated settings push. Values previously stored are ignored.

2026-08-10: Translatable metafields, related products, metafield configuration API

• Metafields are now translatable: the Products API accepts a metafields array inside each translations.<lang> entry (and on the translations sub-resource). A translated entry overrides the value of the base metafield with the same namespace and key when the assistant serves the product in that language.
• New product fields related_products and complementary_products: merchant-curated recommendations by external_id, mirroring Shopify Search & Discovery semantics. The assistant resolves them and proactively suggests complementary products as cross-sell. For Shopify merchants, the recommendations configured in the Search & Discovery app are now imported automatically.
• New metafield configuration endpoints: GET /settings/metafields lists every metafield detected on your catalog with its configuration, PUT /settings/metafields activates fields for the AI, search filters, and display. Integrations can now push data and activate it in one automated pipeline, without a dashboard step.
• The docs now state explicitly that variant metafields are stored but not read by the assistant: push AI-relevant data at product level.
• The custom catalog guide is now a full integration path: push, activate, knowledge, refresh.

2026-08-03: Add to cart guide, function cart action, full cart action reference

• New cart action type function in the Products API: the widget calls a JavaScript quick-buy function your storefront exposes on window (for example injected via your tag manager), with automatic fallback to a product page redirect when the function is absent. Lets custom storefronts add to cart without leaving the conversation.
• New Add to cart guide: how the widget's add-to-cart works on Shopify, PrestaShop, WooCommerce, and the three options for custom storefronts (function, redirect, noop), including the function contract on the merchant side.
• The cart action reference now documents the full contract: the shopify and woocommerce native types (already accepted by the API) join redirect, noop and prestashop, and the auto-derivation tip covers all three native platforms.
• The OpenAPI spec picks up the new PublicCartActionFunction schema.

2026-07-29: Widget block customization settings

• Five new keys in the Settings API and the MCP update_settings tool: widget.home_greeting, widget.show_sparkle_icon, widget.sparkle_icon_url, widget.show_gift_finder_image, plus a clarified contract for widget.home_title.
• Home screen text overrides (widget.home_title, widget.home_greeting) are now nullable: null restores the built-in translated default, an empty string hides the line entirely in the widget.
• widget.show_sparkle_icon toggles the star icon in chat bubbles and question suggestions; widget.sparkle_icon_url replaces it with your own hosted icon.
• widget.show_gift_finder_image hides the image block of the gift finder widget header (title and subtitle only).

2026-07-28: Merchant MCP server, settings & analytics API

• Humind is now an MCP server: connect Claude or any MCP-compatible agent to your store at https://api.thehumind.com/public/mcp, authenticated with your existing API key. 17 tools whose availability adapts to the key's scopes.
• get_store_overview returns live counters (products, knowledge documents, conversations), the last completed catalog sync, and whether the widget is installed on the site. The get_setup_status tool turns that into an onboarding checklist, with a suggested action (including the MCP tool that can complete it) for every remaining step.
• MCP tools search_docs and get_doc_page: any connected agent can search and read this documentation directly through the MCP server, in English or French. The raw markdown sources are also published at /raw/ with an llms.txt index.
• The MCP page documents the argument shapes that are easy to guess wrong (upsert_knowledge, delete_knowledge, get_kpis, get_top_questions).
• New Settings API: read and update ~50 merchant settings (widget appearance, AI behavior, moderation, CSAT, limits, quiz, tracking, catalog, localization) with a machine-readable schema endpoint.
• New Analytics API: dashboard KPIs and clustered top questions over the API.
• Conversations: free-text search (q) and new filters (languages, entry points, CSAT, message count, tags), plus new response fields (csat, entry_point, summary, message_count, ticket flags).
• Three new API key scopes: settings:read, settings:write, analytics:read; the scopes table is now complete (it was missing imports:write and webhooks:manage).

2026-07-28: Shopify theme blocks for the collection quiz

• New Collection Quiz button theme block: a customizable button that opens the quiz full screen, for merchants running their own dedicated quiz page. The recommendation is presented in the chat assistant.
• The inline Collection Quiz block now works on any template, not just collection pages. Both blocks auto-resolve the current collection on collection pages and expose a collection picker everywhere else.
• Block titles are now localized in the theme editor, matching the dashboard naming.
• Documented the full-screen quiz for custom integrations: a copy-paste button and overlay example, plus the display-mode and page-image-url attributes and the page-back and results-in-chat events.
• Collection quiz install guide updated accordingly.

2026-07-28: Data protection section

• New Data retention and deletion reference: server-side retention periods, automatic purge, end-of-contract deletion, and per-person erasure.
• New Incident management and personal data breaches reference: severity levels, merchant notification within 72 hours, and GDPR role split.
• Browser storage updated: defined lifetimes for every stored item, and anonymous usage measurement that requires no consent.

2026-07-25: SSO and privacy

• New Microsoft Entra SSO & SCIM guide: single sign-on setup, SCIM user provisioning, and tenant isolation.
• New Browser storage reference: a complete, accurate inventory of what the chat widget stores in the shopper's browser.
• Documented cookieless analytics for EU visitors.

2026-07-22: Public API: catalog modeling

• New Product groups API reference.
• Documented product metafields on the catalog API.
• Documented unlisted (deindexed) product handling.

2026-07-10: Analytics integration

• New Analytics guide: mirroring widget events into GA4 via the GTM dataLayer.
• Documented the product-id attribute for the chat widget on product pages.

2026-06-09: Public API: conversations

• New Conversations endpoint reference, with the associated authentication flow.

2026-05-25: AI Agent section

• New AI Agent section: instructions, knowledge base, product snippets, and shared snippets.
• French docs synced with all recent English updates.

2026-04-27: Public catalog API reference

• Published the full API reference (EN + FR): products, collections, knowledge, imports, webhooks, errors, and rate limits, audited against actual backend behavior.
• Added a "Copy page" button for AI-friendly page export.
• Home page and API reference index reorganized.

2026-04-24

Installation guides aligned with widget runtime; added Shopify/hybrid/custom decision tables to each install page; expanded catalog and troubleshooting docs.

2026-04-21

Initial launch of this site, with coverage for:

• Getting started (Shopify + generic)
• Chat widget install and events
• All three bundle widgets
• Catalog sync (Shopify webhooks + custom REST)
• Theming and i18n
• Troubleshooting