Conversations

Exportez vos conversations, les échanges que les visiteurs ont eus avec l'assistant IA (et avec vos opérateurs après un handoff), pour l'analytics, votre data warehouse, l'enrichissement CRM ou l'archivage de conformité.

Ces endpoints sont en lecture seule. Vous pouvez lister les conversations (filtrées par date, langue, entry point, CSAT et plus ; paginées par curseur, ou en recherche texte libre paginée par page) et récupérer une conversation complète avec sa transcription de messages, les tags qui lui sont associés, et les événements d'interaction qu'elle a produits (ajout au panier, clics produit, clic bouton support).

Léger par défaut

L'endpoint de liste renvoie uniquement les métadonnées de la conversation et les tags. Ajoutez include=messages pour inliner la transcription, et include=contact pour inliner les coordonnées client. Un balayage sur une plage de dates reste ainsi rapide, et vous n'optez pour les données plus lourdes que lorsque vous en avez besoin.

L'objet Conversation

Champ	Type	Description
humind_id	string	Id hex 24 caractères de la conversation. À utiliser comme {id} sur l'endpoint de récupération.
created_at	ISO 8601	Début de la conversation (UTC).
updated_at	ISO 8601	Dernière activité (UTC). Sert à la synchro incrémentale updated_after.
last_message_at	ISO 8601	Horodatage du message le plus récent.
origin	string	Canal d'où la conversation a démarré (ex. shopify).
origin_url	string	URL de la page où le chat a commencé, si connue.
language	string[]	Langue(s) détectée(s), ISO 639-1.
title	string	Titre de conversation assigné par l'IA/l'opérateur, si défini.
handoff_status	string	ai_active, queued ou human_active.
tags	string[]	Tags assignés par l'IA et les opérateurs. Toujours présent (peut être vide).
has_triggered_cart	boolean	true si le visiteur a ajouté un produit au panier durant la conversation.
has_triggered_support	boolean	true si le visiteur a cliqué un bouton support/handoff à un moment de la conversation.
has_open_ticket	boolean	true si la conversation a actuellement un ticket support ouvert.
entry_point	string	Où la conversation a démarré : launcher, product_page, gift_generator, shop_banner, quiz ou unknown.
summary	string[]	Points clés générés par l'IA résumant la conversation. Omis si pas encore généré (threads très courts).
csat	object	La note de satisfaction 1-5 du visiteur, si soumise. Omis si aucune note n'a été donnée. Voir CSAT.
contact_id	string	Id du client identifié, quand il y en a un. Renvoyé sauf si include=contact est passé (l'objet contact complet le remplace alors).
contact	object | null	Coordonnées du client. Présent uniquement quand include=contact est passé. Voir Contact.
messages	object[]	La transcription. Toujours présente sur l'endpoint de récupération ; sur la liste uniquement quand include=messages est passé. Voir Message.
message_count	integer	Nombre de messages visiteur dénormalisé. Présent dès que la conversation porte un compte dénormalisé (quasi toujours) ; reflète la longueur exacte de la transcription quand messages est inclus.
event_count	integer	Total des événements d'interaction sur l'ensemble des messages. Présent seulement quand les messages sont inclus.

CSAT

Champ	Type	Description
rating	integer	De 1 à 5.
comment	string	Commentaire libre, quand le visiteur en a laissé un.
submitted_at	ISO 8601	Moment de soumission de la note.
handled_by	string	ai ou human : si la résolution notée était 100% IA ou incluait un handoff humain.

Message

Champ	Type	Description
humind_id	string	Id du message.
from	string	Émetteur : user, assistant ou operator.
role	string	conversation (tour visiteur) ou answer (tour assistant).
source	string	Comment un message visiteur a été envoyé, si connu (ex. typed, follow_up, product_page_question).
content	string[]	Le texte du message, en un ou plusieurs blocs.
created_at	ISO 8601	Envoi du message (UTC).
product_ids	string[]	Ids Humind des produits montrés dans ce tour. Omis si vide.
referenced_product_ids	string[]	Ids Humind des produits cités inline (non affichés en cartes). Omis si vide.
attachments	object[]	Fichiers uploadés dans ce tour. Omis si vide. Chacun : { id, type, original_name, mime_type, size, width?, height? }.
events	object[]	Événements d'interaction sur ce message. Omis si vide. Voir Événement d'interaction.

Événement d'interaction

Les interactions visiteur capturées sur un message : ce que les visiteurs ont fait, pas seulement ce qu'ils ont dit.

Champ	Type	Description
humind_id	string	Id de l'événement.
type	string	add_product, remove_product, open_product_page, open_product_url ou click_support_button.
created_at	ISO 8601	Enregistrement de l'événement (UTC).
product_id	string	Id produit Humind. Présent pour les quatre types d'événement produit.
product_title	string	Titre du produit, inclus quand résolvable.
product_variant_id	string	Le variant ajouté/retiré. Présent pour add_product / remove_product.
price_at_event	number	Prix unitaire capturé au moment de l'événement. Présent pour add_product / remove_product.
button_identifier	string	Quel bouton support a été cliqué : email, contact_us, support_page ou phone. Présent pour click_support_button.

Contact

Renvoyé uniquement quand vous passez include=contact. Contient des données personnelles. Voir l'avertissement ci-dessous.

Champ	Type	Description
id	string	Id du contact.
name	string	Nom du client, si connu.
email	string	Email du client, si connu.
phone	string	Téléphone du client, si connu.

Quand include=contact est passé mais que la conversation n'a aucun contact identifié, contact vaut null.

Les données de contact sont des données personnelles

name, email et phone sont des PII. Elles sont exclues par défaut et renvoyées seulement quand vous ajoutez explicitement include=contact. Traitez ces données conformément à votre politique de confidentialité et à la réglementation applicable (RGPD, etc.), et ne les demandez que lorsque votre cas d'usage l'exige.

Ce qui est exclu

L'export est la vue marchand d'une conversation. Les éléments suivants ne sont pas renvoyés, par conception :

• Conversations playground/sandbox : les threads de test du playground du dashboard n'apparaissent jamais.
• Notes internes opérateur : les annotations réservées aux opérateurs ne font pas partie de la transcription.
• Messages supprimés : les messages soft-deleted sont omis plutôt que renvoyés comme tombstones.
• Champs IA internes : embeddings, notes de qualité de réponse, appels d'outils et traces de raisonnement ne sont jamais exposés.

---

Lister les conversations

GET /conversations renvoie les conversations de la company à laquelle la clé API est rattachée.

Scope requis : conversations:read

Paramètre de requête	Type	Description
q	string	Recherche texte libre sur les ids, titres et contenu des messages (2 caractères min). Bascule la réponse en mode recherche : trié par pertinence, paginé par page au lieu de cursor.
page	integer	Index de page (0 à 100). Utilisé, et pertinent, uniquement avec q. Défaut 0.
created_after	ISO 8601	Uniquement les conversations démarrées à/après cet instant. Accepte une date (2026-05-01) ou un date-time (2026-05-01T00:00:00Z).
created_before	ISO 8601	Uniquement les conversations démarrées à/avant cet instant.
updated_after	ISO 8601	Synchro incrémentale : uniquement les conversations mises à jour à/après cet instant (un nouveau message met à jour updated_at).
include	string	Ensemble opt-in séparé par des virgules : messages (inline la transcription avec les événements imbriqués), contact (inline les PII de contact).
handoff_status	string	Filtrer par statut : ai_active, queued, human_active.
languages	string	Codes ISO 639-1 séparés par des virgules (ex. fr,en). Matche les conversations dont les langues détectées intersectent cet ensemble.
entry_points	string	Séparés par des virgules : launcher, product_page, gift_generator, shop_banner, quiz.
min_messages	integer	Uniquement les conversations avec au moins ce nombre de messages visibles côté visiteur.
has_triggered_cart	true | false	Filtrer selon si la conversation a déclenché un ajout au panier.
has_csat	true | false	true restreint aux conversations avec une note CSAT soumise.
csat_min / csat_max	integer (1-5)	Borne la note CSAT. L'un ou l'autre implique has_csat=true.
tag	string	Une seule valeur de tag assignée par l'IA ou un opérateur, telle qu'elle apparaît dans tags[].
limit	integer	Éléments par page (1 à 100). Défaut 50.
cursor	string	Curseur opaque renvoyé comme next_cursor dans la page précédente. À omettre au premier appel. Ignoré quand q est présent.

Tous les filtres se combinent, y compris avec q.

Mode recherche vs. mode curseur

Sans q : la liste est triée par les plus récentes d'abord, paginée par curseur : { data, next_cursor }.

Avec q : les résultats sont triés par pertinence (le curseur _id ne peut pas exprimer un tri par pertinence), donc la pagination bascule sur page, et la forme de la réponse devient { data, has_more, page }.

Pagination par curseur

Sans q : la réponse renvoie jusqu'à limit éléments plus un next_cursor. Repassez-le comme cursor pour la page suivante. Quand next_cursor vaut null, vous avez atteint la fin. Le curseur est opaque : ne le parsez pas ; son format peut changer dans une future version.

Requête

curl "https://api.thehumind.com/public/v1/conversations?created_after=2026-05-01&limit=50" \
  -H "Authorization: Bearer hmd_live_..."

Réponse 200 OK

{
  "data": [
    {
      "humind_id": "65f1ab9c8e7d4a2b1c3d4e5f",
      "created_at": "2026-05-15T10:00:00Z",
      "updated_at": "2026-05-15T10:05:00Z",
      "last_message_at": "2026-05-15T10:05:00Z",
      "origin": "shopify",
      "origin_url": "https://example.com/products/creme-hydratante",
      "language": ["fr"],
      "title": "Question sur la crème hydratante",
      "handoff_status": "ai_active",
      "tags": ["high-intent", "skincare"],
      "has_triggered_cart": true,
      "has_triggered_support": false,
      "has_open_ticket": false,
      "entry_point": "product_page",
      "summary": ["A demandé la taille 50ml", "A ajouté le produit au panier"],
      "csat": { "rating": 5, "submitted_at": "2026-05-15T10:06:00Z", "handled_by": "ai" },
      "contact_id": "65f1c0de8e7d4a2b1c3d4e70",
      "message_count": 3
    }
  ],
  "next_cursor": "eyJpZCI6IjY1ZjFhYjljOGU3ZDRhMmIxYzNkNGU1ZiJ9"
}

Pour chercher plutôt que naviguer chronologiquement :

curl "https://api.thehumind.com/public/v1/conversations?q=creme%20hydratante%2050ml&page=0" \
  -H "Authorization: Bearer hmd_live_..."

{
  "data": [
    { "humind_id": "65f1ab9c8e7d4a2b1c3d4e5f", "title": "Question sur la crème hydratante", "..." : "..." }
  ],
  "has_more": true,
  "page": 0
}

Pour filtrer par langue, entry point et CSAT en un seul appel :

curl "https://api.thehumind.com/public/v1/conversations?languages=fr&entry_points=product_page,launcher&has_csat=true&csat_min=4" \
  -H "Authorization: Bearer hmd_live_..."

Pour inliner la transcription et les événements d'interaction en un seul balayage :

curl "https://api.thehumind.com/public/v1/conversations?created_after=2026-05-01&include=messages&limit=25" \
  -H "Authorization: Bearer hmd_live_..."

---

Récupérer une conversation

GET /conversations/{id} renvoie une conversation complète avec sa transcription de messages (chaque message avec ses événements d'interaction imbriqués). {id} est le humind_id de la conversation.

Scope requis : conversations:read

Paramètre de requête	Type	Description
include	string	Passez contact pour inliner les PII de contact client. La transcription (messages) est toujours incluse sur cet endpoint.

Requête

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

Réponse 200 OK

{
  "humind_id": "65f1ab9c8e7d4a2b1c3d4e5f",
  "created_at": "2026-05-15T10:00:00Z",
  "updated_at": "2026-05-15T10:05:00Z",
  "last_message_at": "2026-05-15T10:05:00Z",
  "origin": "shopify",
  "language": ["fr"],
  "handoff_status": "ai_active",
  "tags": ["high-intent", "skincare"],
  "has_triggered_cart": true,
  "contact_id": "65f1c0de8e7d4a2b1c3d4e70",
  "message_count": 3,
  "event_count": 1,
  "messages": [
    {
      "humind_id": "65f1ab9c8e7d4a2b1c3d4e60",
      "from": "user",
      "role": "conversation",
      "source": "typed",
      "content": ["Vous l'avez en 50 ml ?"],
      "created_at": "2026-05-15T10:01:00Z"
    },
    {
      "humind_id": "65f1ab9c8e7d4a2b1c3d4e61",
      "from": "assistant",
      "role": "answer",
      "content": ["Oui, la crème hydratante existe en 50 ml."],
      "created_at": "2026-05-15T10:01:30Z",
      "product_ids": ["65f1aa008e7d4a2b1c3d4e10"]
    },
    {
      "humind_id": "65f1ab9c8e7d4a2b1c3d4e62",
      "from": "user",
      "role": "conversation",
      "content": ["Parfait, je la prends."],
      "created_at": "2026-05-15T10:02:00Z",
      "events": [
        {
          "humind_id": "65f1ab9c8e7d4a2b1c3d4e80",
          "type": "add_product",
          "created_at": "2026-05-15T10:02:05Z",
          "product_id": "65f1aa008e7d4a2b1c3d4e10",
          "product_title": "Crème hydratante",
          "product_variant_id": "65f1aa008e7d4a2b1c3d4e11",
          "price_at_event": 29.90
        }
      ]
    }
  ]
}

Pour inclure les coordonnées du contact :

curl "https://api.thehumind.com/public/v1/conversations/65f1ab9c8e7d4a2b1c3d4e5f?include=contact" \
  -H "Authorization: Bearer hmd_live_..."

Le champ contact_id est alors remplacé par un objet contact :

{
  "contact": {
    "id": "65f1c0de8e7d4a2b1c3d4e70",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+33123456789"
  }
}

---

Recettes

Exporter une plage de dates

Paginez tout ce qui a démarré sur une fenêtre :

# Première page
curl "https://api.thehumind.com/public/v1/conversations?created_after=2026-05-01&created_before=2026-06-01&include=messages&limit=50" \
  -H "Authorization: Bearer hmd_live_..."

# Page suivante : passez le next_cursor de la réponse précédente
curl "https://api.thehumind.com/public/v1/conversations?created_after=2026-05-01&created_before=2026-06-01&include=messages&limit=50&cursor=COLLER_NEXT_CURSOR" \
  -H "Authorization: Bearer hmd_live_..."

Continuez à suivre next_cursor jusqu'à ce qu'il revienne null.

Synchro incrémentale

Ne récupérez que ce qui a changé depuis votre dernier run. Stockez l'horodatage de votre synchro précédente et passez-le en updated_after :

curl "https://api.thehumind.com/public/v1/conversations?updated_after=2026-06-07T00:00:00Z&include=messages" \
  -H "Authorization: Bearer hmd_live_..."

Cela renvoie chaque conversation touchée (nouveau message, handoff, changement de tag) depuis cet instant, idéal pour un ETL nocturne vers votre warehouse.

Trouver les conversations peu satisfaisantes à revoir

Combinez has_csat avec une borne de note et un filtre de langue :

curl "https://api.thehumind.com/public/v1/conversations?has_csat=true&csat_max=2&languages=fr&limit=50" \
  -H "Authorization: Bearer hmd_live_..."

Récupérez la transcription de chacune avec include=messages, ou une à une via Récupérer une conversation.

Chercher plutôt que naviguer

Quand vous ne connaissez pas la plage de dates, utilisez q et paginez avec has_more :

# Première page
curl "https://api.thehumind.com/public/v1/conversations?q=politique%20de%20retour&page=0" \
  -H "Authorization: Bearer hmd_live_..."

# Page suivante
curl "https://api.thehumind.com/public/v1/conversations?q=politique%20de%20retour&page=1" \
  -H "Authorization: Bearer hmd_live_..."

Arrêtez quand has_more revient false.

---

Erreurs courantes

Statut	Code	Quand	Correction
400	validation_failed	Format de date invalide, cursor invalide, {id} malformé, q de moins de 2 caractères, ou valeur entry_points inconnue. details pointe le problème.	Corrigez le paramètre 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 conversations:read.	Créez une clé avec le scope conversations:read.
404	not_found	{id} ne correspond à aucune conversation de votre company (les ids cross-tenant et playground renvoient aussi 404).	Vérifiez le humind_id.
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é conversations:read.
• Conventions : dates, pagination, identifiants.
• Errors : référence complète des codes d'erreur.
• Analytics : top questions groupées, chacune avec des conversation_ids d'exemple à retrouver ici.
• Serveur MCP : laissez un agent IA chercher et lire les conversations directement.