English

Français

English

Français

Appearance

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-10-14: Imports, hourly quota, one at a time, and an unchanged counter ​

  • An import re-reads the whole catalog, so it is meant for a full sync, not for each edit. POST /imports now accepts 6 imports per hour per company and environment (live and test keys apart). Beyond that it returns 429 with code import_quota_exceeded, a Retry-After header and details.retry_after; the refusal is not stored under its Idempotency-Key, so the same key can be retried. To keep a catalog fresh, send only the changed products with POST /products/batch or PATCH /products/{id}.
  • POST /imports/{id}/start returns 409 with code import_in_progress while another import or product feed pull of the same catalog is processing. The import stays pending; start it again once the running one, named in details.running_sync_id, is done.
  • New report.unchanged on GET /imports/{id} and on the import.completed / import.failed webhooks: the rows identical to what was last imported, which Humind skipped. Additive: these rows are still counted in report.updated.
  • Errors and Rate limits list the two new codes.

2026-10-12: url on collections ​

  • A collection can carry the public page it has on your storefront: url (absolute http(s) URL, optional) on the Collections endpoint, on writes and reads. The search bar opens that page when a visitor clicks a collection result; without it the click only narrows the search to the collection. Shopify stores get it from the sync. Additive: omitted on a write, the stored value is unchanged; null clears it.

2026-10-12: Recent pages and handoff wait in browser storage ​

  • Browser storage updated with two session items of the chat widget: humind.recentPages (the storefront pages opened in the tab, kept for two sliding hours and sent to Humind only when the shopper asks for a human, so the operator sees where they were) and humind.handoffQueuedAt.<threadId> (the time of the handoff request, for the waiting counter).

2026-10-07: Product feeds in any format ​

  • The product feed URL no longer has to be NDJSON in the Humind format: CSV or TSV, XML (Google Shopping, Lengow, RSS) and JSON feeds are accepted as is. Their fields are mapped to the Humind format automatically, the mapping can be edited in the dashboard, and Test the feed shows what would be imported before anything is saved.
  • Sync your catalog updated accordingly.

2026-09-30: widget.show_home_products setting ​

  • New agent setting on the Settings endpoint: widget.show_home_products (boolean, default true) shows or hides the strip of product cards on the chat widget's home screen (featured products, else the most asked-about ones, else the newest), each with a one-tap question. Additive: existing keys are unchanged.

2026-09-30: clarification_questions and clarification_answers on conversation messages ​

  • A message now carries the clarification quiz the assistant showed (clarification_questions, on an assistant turn whose content is empty) and the choices the visitor picked (clarification_answers, on the user turn that follows). Additive: both are omitted when absent. See Conversations.

2026-09-28: product_sheet_swipe source on the product dataLayer events ​

  • On phones, the product page now opens as a sheet over the conversation and a swipe moves to the previous or next product of the same carousel. Each swipe fires humind_product_page_opened with source set to product_sheet_swipe. Additive: existing values are unchanged. See Track widget events in GA4 / GTM.

2026-09-23: source on the product dataLayer events ​

  • humind_product_page_opened, humind_product_url_opened, humind_product_added_to_cart and humind_product_removed_from_cart now carry a source parameter naming the button that fired them (product_card, quiz_hero, quiz_alternatives, comparison_table, sticky_bar, product_page, variant_picker, cart_sheet, product_chip). Additive: existing parameters are unchanged. See Track widget events in GA4 / GTM.

2026-09-16: Per-event dataLayer filters ​

  • Two new company settings on the Settings endpoint: tracking.data_layer_events (allowlist of the events the chat widget pushes to window.dataLayer, up to 100 names without the humind_ prefix, null = every public event) and tracking.data_layer_once_per_session (boolean: push each event at most once per shopper session).
  • Made for sites billed per hit: an explicit allowlist keeps events added later by Humind off until you add them. See Track widget events in GA4 / GTM.

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 ​

2026-07-25: SSO and privacy ​

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 ​

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

Released under the proprietary Humind license.

© 2026 Humind