yuno.chat
Clés API

Référence de l’API

Conversations

Une conversation correspond à une session d’un visiteur dans le widget, du premier message à sa clôture. Le widget crée les conversations ; l’API permet de les consulter, de les attribuer, de les transférer à une personne et de les fermer.

Points de terminaison

L’objet conversation

Attributs

  • idstring

    Identifiant unique, préfixé par conv_.

  • objectstring

    Toujours conversation.

  • site_idstring

    Le site sur lequel la conversation a commencé.

  • statusenum

    open pendant que l’assistant répond, waiting lorsque le visiteur a demandé à parler à une personne sans avoir encore reçu de réponse, handed_off quand un membre de l’équipe intervient, et closed une fois la conversation terminée.

    openwaitinghanded_offclosed

  • subjectstring | null

    Un bref résumé généré à partir des premiers messages.

  • contact_idstring | null

    Le contact, si le visiteur a été identifié ou a laissé une adresse e-mail.

  • assignee_idstring | null

    Le membre de l’équipe chargé de la conversation.

  • message_countinteger

    Nombre de messages, réponses de l’assistant comprises.

  • page_urlstring

    La page sur laquelle se trouvait le visiteur lors de l’ouverture du widget.

  • last_message_atstring

    Date du dernier message, au format ISO 8601 en UTC.

  • metadataobject

    Jusqu’à 20 paires clé-valeur de vos propres données. Les clés peuvent contenir 40 caractères et les valeurs 500. Définissez une clé sur null pour la supprimer.

  • created_atstring

    Date de création de l’objet, au format ISO 8601 en UTC.

  • updated_atstring

    Date de dernière mise à jour de l’objet, au format ISO 8601 en UTC.

Objet conversation
{
  "id": "conv_8HqL2v9K",
  "object": "conversation",
  "site_id": "site_8Kq2mXvR",
  "status": "handed_off",
  "subject": "Modifier l’adresse de livraison",
  "contact_id": "ctc_4mR8tYw2",
  "assignee_id": "usr_team_lea",
  "message_count": 6,
  "page_url": "https://atelier-gres.fr/products/bol-sauge",
  "last_message_at": "2026-10-03T09:14:02Z",
  "metadata": {
    "order_id": "1187"
  },
  "created_at": "2026-10-03T09:10:51Z",
  "updated_at": "2026-10-03T09:14:02Z"
}

Lister les conversations

GET/conversations

Renvoie les conversations, de la plus récente à la plus ancienne.

Paramètres de requête

  • statusenum

    Renvoie uniquement les conversations ayant ce statut.

    openwaitinghanded_offclosed

  • site_idstring

    Renvoie uniquement les conversations de ce site.

  • contact_idstring

    Renvoie uniquement les conversations de ce contact.

  • limitinteger

    Nombre d’objets à renvoyer, entre 1 et 100. Valeur par défaut : 20.

  • cursorstring

    Le next_cursor d’une page précédente. Omettez-le pour commencer par l’objet le plus récent.

Requête
curl -G https://api.yuno.chat/v1/conversations \
  -H "Authorization: Bearer $YUNO_SECRET_KEY" \
  -d status=waiting \
  -d limit=20
Réponse · 200
{
  "object": "list",
  "data": [
    {
      "id": "conv_8HqL2v9K",
      "object": "conversation",
      "site_id": "site_8Kq2mXvR",
      "status": "handed_off",
      "subject": "Modifier l’adresse de livraison",
      "contact_id": "ctc_4mR8tYw2",
      "assignee_id": "usr_team_lea",
      "message_count": 6,
      "page_url": "https://atelier-gres.fr/products/bol-sauge",
      "last_message_at": "2026-10-03T09:14:02Z",
      "metadata": {
        "order_id": "1187"
      },
      "created_at": "2026-10-03T09:10:51Z",
      "updated_at": "2026-10-03T09:14:02Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImNvbnZfM..."
}

Récupérer une conversation

GET/conversations/{id}

Renvoie une seule conversation.

Paramètres de chemin

  • idstringobligatoire

    L’identifiant de la conversation.

Requête
curl https://api.yuno.chat/v1/conversations/conv_8HqL2v9K \
  -H "Authorization: Bearer $YUNO_SECRET_KEY"
Réponse · 200
{
  "id": "conv_8HqL2v9K",
  "object": "conversation",
  "site_id": "site_8Kq2mXvR",
  "status": "handed_off",
  "subject": "Modifier l’adresse de livraison",
  "contact_id": "ctc_4mR8tYw2",
  "assignee_id": "usr_team_lea",
  "message_count": 6,
  "page_url": "https://atelier-gres.fr/products/bol-sauge",
  "last_message_at": "2026-10-03T09:14:02Z",
  "metadata": {
    "order_id": "1187"
  },
  "created_at": "2026-10-03T09:10:51Z",
  "updated_at": "2026-10-03T09:14:02Z"
}

Mettre à jour une conversation

PATCH/conversations/{id}

Attribue une conversation ou met à jour ses métadonnées. Les champs omis restent inchangés.

Paramètres de chemin

  • idstringobligatoire

    L’identifiant de la conversation.

Paramètres du corps

  • assignee_idstring | null

    L’identifiant d’un membre de l’équipe, ou null pour retirer l’attribution.

  • metadataobject

    Jusqu’à 20 paires clé-valeur de vos propres données. Les clés peuvent contenir 40 caractères et les valeurs 500. Définissez une clé sur null pour la supprimer.

Requête
curl -X PATCH https://api.yuno.chat/v1/conversations/conv_8HqL2v9K \
  -H "Authorization: Bearer $YUNO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignee_id": "usr_team_lea",
    "metadata": {
      "order_id": "1187"
    }
  }'
Réponse · 200
{
  "id": "conv_8HqL2v9K",
  "object": "conversation",
  "site_id": "site_8Kq2mXvR",
  "status": "handed_off",
  "subject": "Modifier l’adresse de livraison",
  "contact_id": "ctc_4mR8tYw2",
  "assignee_id": "usr_team_lea",
  "message_count": 6,
  "page_url": "https://atelier-gres.fr/products/bol-sauge",
  "last_message_at": "2026-10-03T09:14:02Z",
  "metadata": {
    "order_id": "1187"
  },
  "created_at": "2026-10-03T09:10:51Z",
  "updated_at": "2026-10-03T09:14:02Z"
}

Transférer à une personne

POST/conversations/{id}/handoff

Arrête les réponses de l’assistant et passe la conversation à waiting, comme si le visiteur avait demandé à parler à une personne. Utile lorsque vos systèmes détectent une situation nécessitant une intervention humaine.

Paramètres de chemin

  • idstringobligatoire

    L’identifiant de la conversation.

Paramètres du corps

  • assignee_idstring

    Attribue immédiatement la conversation à quelqu’un. Le statut devient handed_off.

  • notestring

    Une note interne visible par votre équipe, jamais par le visiteur.

Requête
curl -X POST https://api.yuno.chat/v1/conversations/conv_8HqL2v9K/handoff \
  -H "Authorization: Bearer $YUNO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Client VIP, commande de plus de 500 €"
  }'
Réponse · 200
{
  "id": "conv_8HqL2v9K",
  "object": "conversation",
  "site_id": "site_8Kq2mXvR",
  "status": "waiting",
  "subject": "Modifier l’adresse de livraison",
  "contact_id": "ctc_4mR8tYw2",
  "assignee_id": null,
  "message_count": 6,
  "page_url": "https://atelier-gres.fr/products/bol-sauge",
  "last_message_at": "2026-10-03T09:14:02Z",
  "metadata": {
    "order_id": "1187"
  },
  "created_at": "2026-10-03T09:10:51Z",
  "updated_at": "2026-10-03T09:14:02Z"
}

Fermer une conversation

POST/conversations/{id}/close

Ferme la conversation. Si le visiteur écrit à nouveau, une nouvelle conversation est créée.

Paramètres de chemin

  • idstringobligatoire

    L’identifiant de la conversation.

Requête
curl -X POST https://api.yuno.chat/v1/conversations/conv_8HqL2v9K/close \
  -H "Authorization: Bearer $YUNO_SECRET_KEY"
Réponse · 200
{
  "id": "conv_8HqL2v9K",
  "object": "conversation",
  "site_id": "site_8Kq2mXvR",
  "status": "closed",
  "subject": "Modifier l’adresse de livraison",
  "contact_id": "ctc_4mR8tYw2",
  "assignee_id": "usr_team_lea",
  "message_count": 6,
  "page_url": "https://atelier-gres.fr/products/bol-sauge",
  "last_message_at": "2026-10-03T09:14:02Z",
  "metadata": {
    "order_id": "1187"
  },
  "created_at": "2026-10-03T09:10:51Z",
  "updated_at": "2026-10-03T09:14:02Z"
}