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, paginées par curseur) 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.
`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 exportés. Présent seulement quand les `messages` sont inclus.
`event_count`	integer	Total des événements d'interaction sur l'ensemble des messages. Présent seulement quand les `messages` sont inclus.

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, les plus récentes d'abord.

Scope requis : conversations:read

Paramètre de requête	Type	Description
`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`.
`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.

Pagination par curseur

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

bash

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

Réponse `200 OK`

json

{
  "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,
      "contact_id": "65f1c0de8e7d4a2b1c3d4e70"
    }
  ],
  "next_cursor": "eyJpZCI6IjY1ZjFhYjljOGU3ZDRhMmIxYzNkNGU1ZiJ9"
}

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

bash

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

bash

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

Réponse `200 OK`

json

{
  "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 :

bash

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 :

json

{
  "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 :

bash

# 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 :

bash

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.

Erreurs courantes

Statut	Code	Quand	Correction
`400`	`validation_failed`	Format de date invalide, `cursor` invalide ou `{id}` malformé. `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.

Conversations ​

L'objet Conversation ​

Message ​

Événement d'interaction ​

Contact ​

Ce qui est exclu ​

Lister les conversations ​

Requête ​

Réponse 200 OK ​

Récupérer une conversation ​

Requête ​

Réponse 200 OK ​

Recettes ​

Exporter une plage de dates ​

Synchro incrémentale ​

Erreurs courantes ​

Suite ​

Conversations

L'objet Conversation

Message

Événement d'interaction

Contact

Ce qui est exclu

Lister les conversations

Requête

Réponse `200 OK`

Récupérer une conversation

Requête

Réponse `200 OK`

Recettes

Exporter une plage de dates

Synchro incrémentale

Erreurs courantes

Suite