Settings

Lisez et mettez à jour les settings marchand de votre boutique (apparence du widget, comportement IA, modération, collecte CSAT, limites d'usage, invitation au chat, pre-chat survey, consentement cookies, quiz de collection, tracking, comportement catalogue et localisation), les mêmes settings affichés dans votre dashboard, via l'API.

Allowlist, pas un miroir de base de données

Seuls les settings explicitement listés dans le schéma sont exposés ici. Les secrets (tokens d'intégration, auth order-tracking), le state billing/subscription, le team/RBAC et les domaines ne transitent jamais par cette surface, même avec une clé pleinement scopée.

Les endpoints, en un coup d'œil

GET /settings renvoie la valeur actuelle de chaque setting.
GET /settings/schema renvoie le contrat (clé, type, bornes) ; appelez-le une fois pour savoir ce que vous pouvez écrire, ou pour construire une UI/un générateur de config à partir d'une liste stable.
PATCH /settings écrit un ou plusieurs settings en une seule requête all-or-nothing.
GET / PUT /settings/metafields lisent et remplacent la configuration des metafields : lesquels de vos metafields catalogue alimentent l'IA, servent de filtres de recherche ou s'affichent sur les surfaces produit.

Lire tous les settings

GET /settings renvoie un snapshot plat de chaque setting autorisé.

Scope requis : settings:read

Requête

bash

curl https://api.thehumind.com/public/v1/settings \
  -H "Authorization: Bearer hmd_live_..."

Réponse `200 OK`

json

{
  "data": {
    "widget.agent_name": "Léa",
    "widget.interface_color": "#1a2b3c",
    "ai.personality": "welcoming",
    "ai.instructions": [],
    "limits.messages_per_hour": 60,
    "catalog.category": null
  }
}

Une clé jamais personnalisée reste présente dans la réponse, avec la valeur null : la surface complète est toujours renvoyée, pas seulement ce qu'un marchand a touché.

Schéma des settings

GET /settings/schema renvoie le contrat machine-readable que chaque clé doit respecter en écriture. C'est le même registre sur lequel la validation du PATCH s'appuie, il ne peut donc jamais diverger de ce que l'API accepte réellement.

Scope requis : settings:read

Requête

bash

curl https://api.thehumind.com/public/v1/settings/schema \
  -H "Authorization: Bearer hmd_live_..."

Réponse `200 OK`

json

{
  "data": [
    {
      "key": "widget.agent_name",
      "scope_of_change": "agent",
      "description": "Display name of the AI assistant shown in the chat widget.",
      "type": "string",
      "max": 40
    },
    {
      "key": "ai.personality",
      "scope_of_change": "agent",
      "description": "Overall tone of the assistant.",
      "type": "enum",
      "values": ["welcoming", "neutral", "factual", "professional", "funny"]
    },
    {
      "key": "catalog.category",
      "scope_of_change": "company",
      "description": "Primary vertical of the catalog (drives prompt tuning). Null = unspecified.",
      "type": "enum",
      "values": ["apparel", "home_goods", "beauty_personal_care", "…"],
      "nullable": true
    }
  ]
}

Champ	Type	Description
`key`	string	Clé publique en dot-notation, ex. `widget.agent_name`. Stable entre versions de l'API.
`scope_of_change`	string	`company` ou `agent` : sur quel document interne vit le setting. Informationnel : vous l'écrivez toujours de la même façon, via `PATCH /settings`.
`description`	string	Explication marchand-facing, en une ligne.
`type`	string	`boolean`, `string`, `integer`, `enum` ou `array`.
`values`	string[]	Valeurs autorisées. Présent uniquement quand `type` vaut `enum`.
`min`	integer	Borne inférieure incluse. Présent uniquement quand `type` vaut `integer`.
`max`	integer	Borne supérieure incluse (`type: integer`) ou longueur max (`type: string` / `type: array`).
`nullable`	boolean	Si `null` réinitialise la valeur à son défaut. Présent uniquement quand `true`.

Mettre à jour des settings

PATCH /settings écrit un ou plusieurs settings. Le body est un objet plat { "<clé de setting>": valeur } : seules les clés que vous passez sont touchées, tout le reste reste inchangé.

Scope requis : settings:write

Validation all-or-nothing

Si une seule clé du body est inconnue, ou si une seule valeur échoue sa contrainte (mauvais type, hors limites, absente de la liste enum…), la requête entière est rejetée avec 400 validation_failed, et rien n'est appliqué, pas même les clés valides. Corrigez chaque problème dans error.details.issues et renvoyez.

Header	Requis	Description
`Idempotency-Key`	Oui	Les replays de la même clé sous 24h avec un body identique renvoient la réponse en cache. Voir Conventions.

Requête

bash

curl -X PATCH https://api.thehumind.com/public/v1/settings \
  -H "Authorization: Bearer hmd_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f7c2e9a-4b1c-4e5f-9c3d-65f1ab9c8e7d" \
  -d '{
    "widget.agent_name": "Léa",
    "ai.personality": "professional",
    "limits.messages_per_hour": 60
  }'

Réponse `200 OK`

Seules les clés qui faisaient partie du PATCH reviennent, relues en base après l'écriture (vous voyez donc toute coercition côté serveur, pas juste un écho de ce que vous avez envoyé) :

json

{
  "data": {
    "widget.agent_name": "Léa",
    "ai.personality": "professional",
    "limits.messages_per_hour": 60
  }
}

Réponse `400 Bad Request` (échec de validation)

json

{
  "error": {
    "code": "validation_failed",
    "message": "One or more settings are invalid.",
    "details": {
      "issues": [
        { "key": "ai.personalityy", "message": "Unknown setting key. See GET /public/v1/settings/schema for the list." },
        { "key": "limits.messages_per_hour", "message": "Number must be less than or equal to 10000" }
      ]
    }
  }
}

Un PATCH réussi invalide les caches de configuration du chat-service dans le cadre de la requête : les changements atteignent le widget live en quelques secondes, pas le TTL de 5 à 60 minutes que ces caches tiennent normalement.

Agent non provisionné

Certains settings (tout ce qui est sous widget.*, ai.*, moderation.*, csat.*, limits.*, chat_invitation.*, pre_chat_survey.*, cookie_consent.* ; voir scope_of_change: "agent" dans le schéma) vivent sur la configuration de l'agent IA de la boutique. Une company qui n'a pas fini son onboarding n'a pas encore d'agent ; écrire une de ces clés renvoie alors :

json

{
  "error": {
    "code": "agent_not_provisioned",
    "message": "This company has no agent configured yet. Finish onboarding before updating agent settings."
  }
}

Les settings scopés company (quiz.*, tracking.*, store_locator.*, catalog.*, localization.*) ne sont pas concernés et peuvent toujours être écrits.

Référence des settings

Chaque clé exposée par le registre, groupée comme dans le dashboard. S'applique à reflète scope_of_change du schéma.

Clé	S'applique à	Type	Description
`widget.agent_name`	agent	string (max 40)	Nom d'affichage de l'assistant IA dans le widget de chat.
`widget.home_title`	agent	string (max 120, nullable)	Titre custom sur l'écran d'accueil du widget. `null` = le défaut traduit intégré, chaîne vide = la ligne est masquée.
`widget.home_greeting`	agent	string (max 120, nullable)	Message d'accueil custom sur l'écran d'accueil du widget (« Bonjour »). `null` = le défaut traduit intégré, chaîne vide = la ligne est masquée.
`widget.show_sparkle_icon`	agent	boolean	Affiche l'icône étoiles dans les bulles de chat et les suggestions de questions du widget.
`widget.sparkle_icon_url`	agent	string (URL, max 500, nullable)	URL HTTPS d'une icône custom remplaçant l'étoile. `null` = l'icône par défaut.
`widget.show_gift_finder_image`	agent	boolean	Affiche le bloc image de l'en-tête du widget chercheur de cadeaux. Désactivé = titre et sous-titre seulement.
`widget.interface_color`	agent	string (couleur hex)	Couleur de marque principale du widget.
`widget.text_color`	agent	string (couleur hex)	Couleur du texte affiché sur la couleur principale.
`widget.bubble_rounding`	agent	integer (0-100)	Rayon d'arrondi des bulles de chat, en pixels.
`widget.show_searchbar`	agent	boolean	Afficher la barre de recherche produit dans le widget.
`widget.show_preset_questions`	agent	boolean	Afficher les questions préconfigurées sur l'écran d'accueil du widget.
`widget.disable_powered_by`	agent	boolean	Masquer l'attribution "Powered by Humind" dans le widget.
`widget.allow_generated_followup`	agent	boolean	Laisser l'IA suggérer des questions de relance générées après chaque réponse.
`widget.add_to_cart_bg_color`	agent	string (couleur hex)	Couleur de fond du bouton ajouter au panier.
`widget.add_to_cart_text_color`	agent	string (couleur hex)	Couleur du texte du bouton ajouter au panier.
`widget.add_to_cart_rounding`	agent	integer (0-100)	Rayon d'arrondi du bouton ajouter au panier, en pixels.
`widget.cart_button_destination`	agent	enum : `cart`, `checkout`	Où le bouton panier du widget envoie le visiteur (Shopify uniquement).

Comportement IA

Clé	S'applique à	Type	Description
`ai.personality`	agent	enum : `welcoming`, `neutral`, `factual`, `professional`, `funny`	Ton général de l'assistant.
`ai.answer_length`	agent	enum : `concise`, `standard`, `meticulous`	Verbosité cible des réponses.
`ai.enforce_emojis`	agent	boolean	Forcer l'assistant à utiliser des emojis dans les réponses.
`ai.followup_enforce_emojis`	agent	boolean	Forcer les emojis dans les questions de relance suggérées.
`ai.enforce_language`	agent	boolean	Forcer l'assistant à toujours répondre dans `ai.custom_language`.
`ai.custom_language`	agent	string (max 40)	Langue dans laquelle l'assistant doit répondre quand `ai.enforce_language` est actif (ex. `"French"`).
`ai.instructions`	agent	array (max 50 items)	Règles custom que l'assistant doit suivre. Remplace la liste entière en écriture ; voir ci-dessous.

`ai.instructions`

Chaque item a la forme :

json

{
  "is_enabled": true,
  "title": "No medical advice",
  "instruction": "Never give medical or dosage advice, even if asked directly. Redirect to a healthcare professional.",
  "severity": "critical"
}

severity: "critical" force le classifieur de qualité à noter une réponse en infraction comme mauvaise ; "warning" (le défaut) la déclasse en acceptable. C'est un remplacement de liste complète : pour ajouter une instruction sans perdre les autres, faites un GET /settings, ajoutez à l'array côté client, puis PATCH toute la clé ai.instructions.

Modération

Clé	S'applique à	Type	Description
`moderation.offensive`	agent	enum : `serve`, `decline`	Ce que fait l'assistant avec les messages offensants : répondre quand même, ou décliner poliment.
`moderation.spam`	agent	enum : `serve`, `decline`	Ce que fait l'assistant avec les messages spam.
`moderation.off_topic`	agent	enum : `serve`, `decline`	Ce que fait l'assistant avec les messages hors-sujet.

Collecte CSAT

Clé	S'applique à	Type	Description
`csat.collect_on_ai`	agent	boolean	Demander aux visiteurs une note de satisfaction 1-5 à la fin des conversations 100% IA.
`csat.collect_on_human`	agent	boolean	Demander une note après un handoff humain résolu.

Limites d'usage

Clé	S'applique à	Type	Description
`limits.messages_per_hour`	agent	integer (1-10000)	Maximum de messages visiteur par heure avant l'affichage du message de limite.
`limits.conversations_per_day`	agent	integer (1-100000)	Maximum de nouvelles conversations par visiteur et par jour.
`limits.limit_reached_message`	agent	string (max 500, requis)	Message affiché au visiteur quand une limite est atteinte.
`limits.priority_language`	agent	enum : `EN`, `FR`	Langue de repli de l'UI du widget.
`limits.allow_other_languages`	agent	boolean	Laisser l'assistant répondre dans des langues autres que la langue prioritaire.

Invitation au chat

Clé	S'applique à	Type	Description
`chat_invitation.enabled`	agent	boolean	Inviter proactivement le visiteur à chatter après un délai.
`chat_invitation.wait_seconds`	agent	integer (0-600)	Délai en secondes avant l'apparition de l'invitation au chat.
`chat_invitation.text`	agent	string (max 300)	Texte de la bulle d'invitation au chat.
`chat_invitation.button_enabled`	agent	boolean	Afficher un bouton d'appel à l'action sur l'invitation.
`chat_invitation.button_text`	agent	string (max 80)	Libellé du bouton d'appel à l'action de l'invitation.
`chat_invitation.smart_invitation_enabled`	agent	boolean	Utiliser l'IA pour choisir le moment et le texte de l'invitation selon le contexte de la page.

Pre-chat survey

Clé	S'applique à	Type	Description
`pre_chat_survey.enabled`	agent	boolean	Demander ses coordonnées au visiteur avant de démarrer une conversation.
`pre_chat_survey.name_required`	agent	boolean	Rendre le nom du visiteur obligatoire dans le pre-chat survey.
`pre_chat_survey.email_required`	agent	boolean	Rendre l'email du visiteur obligatoire dans le pre-chat survey.
`pre_chat_survey.phone_required`	agent	boolean	Rendre le téléphone du visiteur obligatoire dans le pre-chat survey.
`pre_chat_survey.consent_required`	agent	boolean	Exiger une case de consentement explicite dans le pre-chat survey.

Consentement cookies

Clé	S'applique à	Type	Description
`cookie_consent.require_consent`	agent	boolean	Exiger le consentement cookies avant que le widget ne stocke quoi que ce soit dans le navigateur.

Quiz de collection

Clé	S'applique à	Type	Description
`quiz.expanded_by_default`	company	boolean	Démarrer le quiz de collection déployé sur desktop plutôt qu'en teaser replié.
`quiz.holdout_percent`	company	integer (0-50)	Pourcentage de visiteurs qui ne voient jamais le quiz, comme groupe témoin A/B.
`quiz.full_pages_enabled`	company	boolean	Servir les guides quiz en pleine page sur la storefront (opt-in, pages crawlables).
`quiz.rules`	company	string (max 2000)	Consignes company-wide que l'IA suit pour générer les quiz.

Tracking

Clé	S'applique à	Type	Description
`tracking.data_layer_enabled`	company	boolean	Miroir des événements analytics du widget dans `window.dataLayer` (GTM/GA4) sur le site marchand.

Store locator

Clé	S'applique à	Type	Description
`store_locator.enabled`	company	boolean	Publier le store locator en pleine page sur la storefront (page publique quand actif).

Comportement catalogue

Clé	S'applique à	Type	Description
`catalog.description`	company	string (max 5000)	Description libre du catalogue, utilisée pour ancrer l'IA.
`catalog.add_params_to_product_url`	company	boolean	Ajouter des paramètres de query custom aux URLs produit ouvertes depuis le widget.
`catalog.product_url_params`	company	string (max 500)	Query string ajoutée aux URLs produit (ex. `utm_source=humind`).
`catalog.add_to_cart_behavior`	company	enum : `redirect_to_url`, `add_to_cart_function`	Comment le widget ajoute au panier : redirection vers l'URL produit, ou appel de la fonction panier de la storefront.
`catalog.category`	company	enum (nullable)	Vertical principal du catalogue (pilote le tuning des prompts). `null` = non spécifié. Une valeur parmi : `apparel`, `home_goods`, `beauty_personal_care`, `electronics`, `sports_outdoors`, `wellness`, `food_drink`, `baby_kids`, `pet_supplies`, `gaming`, `books_ebooks`, `art_diy`, `jewelry_accessories`, `automotive`, `pharmacy_medical`, `sexual_wellness`, `travel_experiences`, `other`.

Localisation

Clé	S'applique à	Type	Description
`localization.default_currency`	company	enum	Devise par défaut utilisée quand un produit n'a pas de devise explicite. N'importe quel code ISO 4217 (ex. `EUR`, `USD`, `GBP`).
`localization.default_country`	company	string (2 caractères, requis)	Pays ISO 3166-1 alpha-2 par défaut de la boutique (ex. `FR`).

Configuration des metafields

Pousser un metafield produit le stocke ; ces deux endpoints contrôlent ce que Humind en fait : alimenter l'assistant IA, servir de filtre de recherche, ou s'afficher sur les surfaces produit. Ils reflètent la page de configuration des metafields du dashboard, pour qu'une intégration puisse pousser son catalogue et activer ses champs dans un seul pipeline automatisé.

Lister les metafields détectés

GET /settings/metafields renvoie chaque metafield détecté sur votre catalogue, fusionné avec sa configuration actuelle.

Scope requis : settings:read

Requête

bash

curl https://api.thehumind.com/public/v1/settings/metafields \
  -H "Authorization: Bearer hmd_live_..."

Réponse `200 OK`

json

{
  "data": {
    "metafields": [
      {
        "namespace": "olfactif",
        "key": "notes_tete",
        "detected_type": "list.single_line_text_field",
        "sample_value": "[\"Bergamote\",\"Mandarine\"]",
        "product_count": 240,
        "last_seen_at": "2026-08-10T09:12:00.000Z",
        "display_name": "Notes de tête",
        "include_in_ai": true,
        "display_on_b2c": false,
        "use_as_filter": true,
        "filter_type": "multiselect",
        "data_type": "string",
        "unit": "",
        "filter_description": "Top notes of the fragrance pyramid.",
        "examples": ["Bergamote"],
        "synonyms": ["notes de tete", "top notes"],
        "buckets": []
      }
    ],
    "total_detected": 12,
    "total_configured": 4
  }
}

La détection tourne après chaque écriture catalogue réussie (une fois par run pour les imports NDJSON) : un metafield apparaît donc ici juste après que les produits qui le portent ont été poussés. Un metafield jamais configuré est renvoyé avec tous les toggles à false et la config de facette par défaut.

Mettre à jour la configuration des metafields

PUT /settings/metafields remplace la liste de configuration entière, la même sémantique que le formulaire du dashboard. Envoyez l'état complet souhaité, pas un delta.

Scope requis : settings:write

Chaque entrée :

Champ	Type	Description
`namespace`, `key`	string, requis	Quel metafield détecté cette entrée configure.
`display_name`	string (max 120), nullable	Libellé montré à l'assistant et sur les surfaces produit à la place de la clé brute.
`include_in_ai`	boolean	Alimente l'assistant IA avec la valeur (ancrage de la recherche et réponses produit).
`use_as_filter`	boolean	Crée une facette de filtre de recherche à partir de ce metafield.
`display_on_b2c`	boolean	Marque le champ pour affichage sur les surfaces produit.
`filter_type`	enum : `exact`, `range`, `multiselect`, `boolean`	Comment le filtre matche les valeurs. `multiselect` comprend les valeurs de liste encodées en JSON.
`data_type`	enum : `string`, `number`, `boolean`, `date`	Comment les valeurs sont interprétées.
`unit`	string (max 20)	Unité d'affichage optionnelle, ex. `cm`.
`filter_description`	string (max 500)	Indique à l'assistant quand appliquer le filtre.
`examples`, `synonyms`	string[] (max 20 chacun)	Valeurs d'exemple et noms alternatifs, donnés à l'assistant.
`buckets`	object[] (max 50)	Pour les filtres `range` : `{ "label": "10-15 cm", "min": 10, "max": 15 }`. Une borne `null` est non bornée de ce côté.

Requête

bash

curl -X PUT https://api.thehumind.com/public/v1/settings/metafields \
  -H "Authorization: Bearer hmd_live_..." \
  -H "Idempotency-Key: 8c9d0e1f-2a3b-4c5d-6e7f-8a9b0c1d2e3f" \
  -H "Content-Type: application/json" \
  -d '{
    "metafields": [
      { "namespace": "olfactif", "key": "notes_tete", "display_name": "Notes de tête", "include_in_ai": true, "use_as_filter": true, "filter_type": "multiselect" },
      { "namespace": "olfactif", "key": "notes_coeur", "display_name": "Notes de cœur", "include_in_ai": true },
      { "namespace": "conseil", "key": "utilisation", "display_name": "Conseil d'utilisation", "include_in_ai": true }
    ]
  }'

Réponse `200 OK`

json

{
  "data": {
    "saved_count": 3,
    "ignored": [],
    "ai_settings_changed": true,
    "filter_settings_changed": true,
    "reindex_queued": true,
    "filter_tokens_queued": true,
    "warnings": []
  }
}

Comportement à connaître :

Les entrées pour des metafields non détectés sur votre catalogue ne sont pas persistées ; elles reviennent dans ignored. Poussez d'abord les produits, configurez ensuite.
Quand les settings IA ont changé, Humind met en file un job de ré-indexation des produits ; quand la config des filtres a changé, un job de reconstruction des filtres. Les deux sont signalés par reindex_queued / filter_tokens_queued et prennent quelques minutes sur les gros catalogues. Si un job n'a pas pu être mis en file, la sauvegarde réussit quand même et warnings vous dit quoi retenter.
La configuration s'applique aux metafields au niveau produit uniquement ; les metafields de variante ne sont pas utilisés par l'assistant.

Erreurs courantes

Statut	Code	Quand	Correction
`400`	`validation_failed`	Une clé inconnue, un mauvais type, ou une valeur hors limites dans le body du PATCH, ou un `Idempotency-Key` manquant/malformé.	Corrigez chaque entrée dans `error.details.issues` et renvoyez.
`401`	`missing_credentials`, `invalid_key`, `revoked`	Header d'auth manquant, malformé, ou clé inactive.	Voir Authentication.
`403`	`insufficient_scope`	La clé n'a pas `settings:read` (GETs) ou `settings:write` (PATCH).	Créez une clé avec le bon scope.
`409`	`agent_not_provisioned`	Écriture d'une clé scopée agent avant que la company n'ait un agent configuré.	Finissez d'abord l'onboarding dans le dashboard.
`409`	`idempotency_conflict`, `idempotency_in_progress`	L'`Idempotency-Key` a été réutilisée avec un body différent, ou la requête originale est toujours en cours.	Utilisez une clé fraîche par écriture logique.
`429`	`rate_limited`	Trop de requêtes pour cette clé.	Temporisez via le header `Retry-After`. Voir Rate limits.

Suite

Authentication : générer une clé settings:read / settings:write.
Analytics : lire les KPIs et les top questions.
Serveur MCP : laissez un agent IA lire et mettre à jour les settings directement.

Settings

Les endpoints, en un coup d'œil

Lire tous les settings

Requête

Réponse `200 OK`

Schéma des settings

Requête

Réponse `200 OK`

Mettre à jour des settings

Requête

Réponse `200 OK`

Réponse `400 Bad Request` (échec de validation)

Propagation au widget

Agent non provisionné

Référence des settings

Apparence du widget

Comportement IA

`ai.instructions`

Modération

Collecte CSAT

Limites d'usage

Invitation au chat

Pre-chat survey

Consentement cookies

Quiz de collection

Tracking

Store locator

Comportement catalogue

Localisation

Configuration des metafields

Lister les metafields détectés

Requête

Réponse `200 OK`

Mettre à jour la configuration des metafields

Requête

Réponse `200 OK`

Erreurs courantes

Suite

Settings ​

Les endpoints, en un coup d'œil ​

Lire tous les settings ​

Requête ​

Réponse 200 OK ​

Schéma des settings ​

Requête ​

Réponse 200 OK ​

Mettre à jour des settings ​

Requête ​

Réponse 200 OK ​

Réponse 400 Bad Request (échec de validation) ​

Propagation au widget ​

Agent non provisionné ​

Référence des settings ​

Apparence du widget ​

Comportement IA ​

ai.instructions ​

Modération ​

Collecte CSAT ​

Limites d'usage ​

Invitation au chat ​

Pre-chat survey ​

Consentement cookies ​

Quiz de collection ​

Tracking ​

Store locator ​

Comportement catalogue ​

Localisation ​

Configuration des metafields ​

Lister les metafields détectés ​

Requête ​

Réponse 200 OK ​

Mettre à jour la configuration des metafields ​

Requête ​

Réponse 200 OK ​

Erreurs courantes ​

Suite ​

Settings

Les endpoints, en un coup d'œil

Lire tous les settings

Requête

Réponse `200 OK`

Schéma des settings

Requête

Réponse `200 OK`

Mettre à jour des settings

Requête

Réponse `200 OK`

Réponse `400 Bad Request` (échec de validation)

Propagation au widget

Agent non provisionné

Référence des settings

Apparence du widget

Comportement IA

`ai.instructions`

Modération

Collecte CSAT

Limites d'usage

Invitation au chat

Pre-chat survey

Consentement cookies

Quiz de collection

Tracking

Store locator

Comportement catalogue

Localisation

Configuration des metafields

Lister les metafields détectés

Requête

Réponse `200 OK`

Mettre à jour la configuration des metafields

Requête

Réponse `200 OK`

Erreurs courantes

Suite