Commentaires

Chaque message dans Communications Mining est représenté par un objet de commentaire unique dans l'API. Ils peuvent donc être considérés comme équivalents. La documentation du développeur et l'API font principalement référence à comments, tandis que le guide de l'utilisateur et l'interface utilisateur de Communications Mining font principalement référence à messages.

Lors du chargement de données vers Communications Mining ou de la récupération de données à partir de Communications Mining, il est important de comprendre comment différents types de données (tels que les e-mails, les tickets d'assistance ou les chat) doivent être représentés sous forme de commentaires. Cette page explique comment modéliser vos données en tant que Communications Mining comments pour les préparer à leur téléchargement dans Communications Mining, et comment comprendre les données extraites de Communications Mining.

Exemple de commentaire créé à partir d'un e-mail

Commentaire sur Communications Mining créé à partir d'un examen

La section Vue d'ensemble (Overview) décrit la structure globale d'un objet de commentaire. Si vous souhaitez charger des données vers Communications Mining via l'API ou pour comprendre comment traiter les données téléchargées vers Communications Mining via l'API, consultez la section Commentaires créés via l'API (Comments created via the API ). Vous pouvez trouver des descriptions détaillées pour chacun des types de commentaires couramment utilisés (e-mails, tickets d’assistance et chat). Si vous voulez mieux comprendre comment traiter les données téléchargées à Communications Mining via une intégration, consultez la section Commentaires créés par les intégrations . Enfin, pour obtenir la liste complète des champs d'objet commentaire disponibles, consultez la section Référence .

Vue d'ensemble (Overview)

Communications Mining fonctionne avec différents types de données textuelles telles que les e-mails, les réponses aux enquêtes, les tickets d'assistance ou les avis des clients. Ce que ces types de données ont en commun, c'est qu'ils sont tous constitués d'unités de communication (un e-mail, une réponse à une enquête, un ticket d'assistance, un avis client). Dans Communications Mining, c'est-à-dire qu'un message unique est représenté par un commentaire.

Quel que soit le type d'unité de communication symbole par un commentaire, il conserve systématiquement cette structure fondamentales :

{
  "id": <UNIQUE ID>,
  "timestamp": <TIMESTAMP>,
  "messages": [
    {
      "body": { "text": <TEXT> },
      ...
    }
  ],
  "user_properties": { ... },
}

Comme indiqué dans l'extrait de code ci-dessus, en plus du texte réel, un commentaire possède toujours un ID et un horodatage. L'ID doit être unique dans la source contenant le message. L'horodatage est utilisé dans l'interface utilisateur de la plate-forme pour filtrer et trier par date, et pour générer des analyses basées sur la date.

En plus de ces champs obligatoires, d'autres champs doivent être définis en fonction du type de commentaire. Si vos données ont été téléchargées dans Communications Mining via une intégration, Communications Mining remplit automatiquement tous les champs nécessaires. Consultez les sections suivantes pour une description plus détaillée.

Commentaires créés via l'API

Emails

Bien que le moyen le plus simple de synchroniser les e-mails dans Communications Mining consiste à utiliser l' intégration Exchange, si vous effectuez votre propre extraction d'e-mails, vous pouvez synchroniser les e-mails via l'API. Utilisez le point de terminaison sync-raw-emails pour les e-mails bruts et le point de terminaison sync pour les e-mails traités.

Lors de la synchronisation des e-mails bruts, fournissez les en-têtes et le corps de l'e-mail MIME extraits tels quels (consultez la référence pour obtenir une description du format de l'e-mail brut). Communications Mining analyse les en-têtes et nettoyage le corps des e-mails.

Remarque : l'exemple d'e-mail brut ci-dessous montre un très petit nombre d'en-têtes pour plus de informations. Envoyez tous les en-têtes extraits à Communications Mining, qui sont susceptibles d'être beaucoup plus longs que dans l'exemple.

Important :

COMMENT Communications Mining traite les e-mails bruts ?

Communications Mining :

• Définit les champs spécifiques aux e-mails dans l'objet de message messages[0]
• Définit le champ thread_id et l'objet thread_properties
• Nettoyer le corps de l'e-mail en supprimant les e-mails entre guillemets et en plaçant la signature dans un champ signature séparé
• Remplit l'objet user_properties avec des métadonnées extraites des en-têtes d'e-mail.

Si un champ n'est pas présent dans l'e-mail, il ne sera pas du tout défini dans le commentaire (plutôt que d'être défini sur une valeur nulle ou vide). Par exemple, le commentaire dans l'exemple ci-dessous ne contient pas de champ Cci:.

Si vous enrichissez les e-mails avec d'autres données avant le téléchargement dans Communications Mining, vous pouvez indiquer ces données supplémentaires dans les propriétés utilisateur du commentaire.

L'e-mail brut traité ressemble à l'exemple d'e-mail traité ci-dessous : voir le nombre de champs supplémentaires créés par Communications Mining. Si vous souhaitez télécharger des e-mails traités, structurez-les comme dans l'exemple d'e-mail traité.

Exemple d'e-mail

E-mail brut

{
  "raw_email": {
    "body": {
      "plain": "Hi Bob,\n\nCould you send me the figures for today?\n\nThanks,\nAlice"
    },
    "headers": {
      "raw": "From: Alice Smith <[e-mail]>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <[e-mail]>\nSubject: Figures for today\nTo: Bob <[e-mail]>\nCc: Joe <[e-mail]>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}

E-mail traité

{
  "comment": {
    "id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
    "timestamp": "2021-08-03T09:57:42Z",
    "user_properties": {
      "string:Has Signature": "Yes",
      "string:Sender": "[e-mail]",
      "string:Thread": "<[e-mail]>",
      "string:Message ID": "<[e-mail]>",
      "number:Recipient Count": 2,
      "number:Participant Count": 3,
      "number:Position in Thread": 1,
      "string:Sender Domain": "example.com",
      "string:Team": "Team XYZ"
    },
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me the figures for today?"
        },
        "signature": {
          "text": "Thanks,\nAlice"
        },
        "subject": {
          "text": "Figures for today"
        },
        "to": ["\"Bob\" <[e-mail]>"],
        "cc": ["\"Joe\" <[e-mail]>"],
        "sent_at": "2021-08-03T09:57:42Z",
        "from": "\"Alice Smith\" <[e-mail]>"
      }
    ],
    "thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
  },
  "thread_properties": {
    "duration": null,
    "response_time": null,
    "num_messages": 1,
    "num_participants": 3,
    "first_sender": "[e-mail]",
    "thread_position": 0
  }
}

Propriétés du thread

Les propriétés de thread suivantes sont disponibles.

Nom	DESCRIPTION
thread_position	Position du commentaire dans le fil de discussion, calculée en triant le commentaire par timestamp. Commence à 0.
num_messages	Nombre de commentaires dans le fil de discussion.
num_participants	Nombre total de participants uniques (De (From), À (To), Cc, Cci) dans le fil de discussion.
first_sender	Expéditeur du premier commentaire du fil de discussion.
duration	Différence (en secondes) entre le timestamps du premier et dernier commentaire du fil de discussion. Sera défini sur null si num_messages est de 1 (c'est-à-dire le fil de discussion ne contient qu'un seul commentaire). Remarque : le timestamp d'un commentaire correspond au champ sent_at de l'e-mail brut correspondant.
response_time	Différence (en secondes) entre le premier commentaire du fil de discussion et la première réponse du fil de discussion. La première réponse du fil de discussion est le commentaire le plus ancien dont l'expéditeur n'est pas first_sender. Sera défini sur null s'il n'y a pas de réponses dans le fil de discussion (c'est-à-dire si tous les e-mails du fil de discussion proviennent du même expéditeur).

Chaque fois qu'un nouveau commentaire est ajouté à la plate-forme, les propriétés de fil de discussion du fil de discussion correspondant sont mises à jour.

Remarque : à l'exception de thread_position, toutes les propriétés sont les mêmes pour chaque commentaire du fil de discussion.

Tickets d’assistance

En plus du texte principal, un ticket d'assistance standard soumis via un formulaire peut comporter un objet, des informations sur l'expéditeur (telles que le nom ou l'adresse e-mail) et des données structurées supplémentaires (telles que la rubrique du ticket) qui peuvent être téléchargées dans le cadre des propriétés utilisateur du commentaire.

L'exemple ci-dessous montre comment formater un ticket d'assistance en tant que commentaire Communications Mining et comment ce commentaire est affiché dans l'interface utilisateur de la plate-forme. Vos propriétés d'utilisateur peuvent différer selon les données que vous collectez.

Exemple de ticket d'assistance

{
  "id": "dbcb03ad",
  "timestamp": "2020-02-26T16:09:00Z",
  "messages": [
    {
      "body": {
        "text": "Hi Support Team\n\nPlease could you look into my broadband service network status. I don't have any signal."
      },
      "subject": {
        "text": "Network Outage for over 24 hours - Customer account number 1234567"
      },
      "from": "[e-mail]"
    }
  ],
  "user_properties": {
    "string:Customer Name": "Alice Smith",
    "string:Source": "Support Form",
    "string:Topic": "Broadband"
  }
}

Messagerie

De tous les types de commentaires, les chat sont le seul cas où vous devez définir plusieurs messages par commentaire dans le tableau messages (tous les autres types de commentaires ont un message par commentaire). Vous pouvez définir l'expéditeur et l'heure à laquelle le message a été envoyé, en plus pour chaque message. Comme pour les tickets d'assistance, vous avez généralement des données structurées (telles que la durée du chat ou le statut de résolution) que vous pouvez télécharger dans le cadre des propriétés utilisateur du commentaire.

L'exemple ci-dessous vous montre comment formater une conversation de chat en tant que commentaire Communications Mining et comment ce commentaire est affiché dans l'interface utilisateur de la plate-forme. Bien sûr, vos propriétés d'utilisateur peuvent différer selon les données que vous collectez.

Exemple de chat

{
  "id": "5be6a3e4",
  "timestamp": "2020-02-28T19:20:22Z",
  "user_properties": {
    "number:Duration": 542,
    "string:Close Reason": "Complete Acknowledged",
    "string:Resolution": "Unknown"
  },
  "messages": [
    {
      "body": {
        "text": "Hi, my name is Alice 👋 How can I help?"
      },
      "sent_at": "2020-02-28T19:20:01Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "Hi. I would like to close my account"
      },
      "sent_at": "2020-02-28T19:22:39Z",
      "from": "Customer"
    },
    {
      "body": {
        "text": "Thanks for waiting. Please call our account team at this number: 012-3456-7890."
      },
      "sent_at": "2020-02-28T19:27:50Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "Ok, thanks, I will follow up with them"
      },
      "sent_at": "2020-02-28T19:28:31Z",
      "from": "Customer"
    },
    {
      "body": {
        "text": "Sure thing! Anything else I can help you with today?"
      },
      "sent_at": "2020-02-28T19:28:42Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "No. Thanks."
      },
      "sent_at": "2020-02-28T19:29:03Z",
      "from": "Customer"
    }
  ]
}

Commentaires créés par les intégrations

E-mails (Microsoft Exchange)

Les e-mails Microsoft Exchange ingérés dans Communications Mining via l' intégration Exchange sont automatiquement convertis en objets de commentaire de la même manière que les e- mails bruts.

Pièces jointes et contenu des pièces jointes

Les commentaires peuvent être associés à des fichiers. Si un commentaire contient des pièces jointes, le champ attachments contient des métadonnées à leur sujet :

```json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
        }
    ],
    // other comment fields omitted
    ...
},
```

En outre, vous pouvez également télécharger le contenu de la pièce jointe. Le téléchargement du contenu de la pièce jointe renvoie le champ attachment_reference :

```json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
            "attachment_reference": "CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G"
        }
    ],
    // other comment fields omitted
    ...
},
```

Utilisez attachment_reference pour récupérer le contenu du fichier binaire depuis [l'API des pièces jointes](#FixME). Pour l’exemple ci-dessus, vous récupérez l’URL suivante : https://cloud.uipath.com/<organisation>/<tenant>/reinfer_/api/v1/attachments/CjQSEIExTHEqtdntboxz2WtbZDNEiIIVqcP1Sfx2L4epyQDas1RSODvheQ3bvLhj3L-_81G.

Consultez le [Référence d'API](#Fixme) pour plus de détails sur ce type de requête.

Si l'objet pièce jointe n'a pas de propriété attachment_reference , vous ne pouvez pas télécharger le contenu de la pièce jointe. Cela peut être dû à la raison suivante :

• Communications Mining n'a pas reçu le contenu de la pièce jointe.
• Le contenu de la pièce jointe dépassait la limite de taille pour le téléchargement vers Communications Mining.
• Communications Mining a traité la pièce jointe avant de prendre en charge le contenu des fichiers.

En savoir plus sur le contenu de la pièce jointe sur la page Pièce jointe (Attachment).

Référence (Reference)

Commentaires

Consultez le tableau ci-dessous pour découvrir une liste des champs de commentaires disponibles. Si vous n'êtes pas familiarisé avec les objets de commentaire de Communications Mining, consultez la Vue d'ensemble ( Overview).

Nom	Saisie de texte	Requis	DESCRIPTION
id	string	oui	Identifie un commentaire de manière unique dans une source. Toute chaîne hexadécimale ne dépassant pas 1024 caractères est valide (est conforme à /[0-9a-f]{1,1024}/).
timestamp	string	oui	Un horodatage ISO-8601 indiquant quand le commentaire a été créé. Si l'horodatage ne spécifie pas de fuseau horaire, UTC sera utilisé. L'horodatage doit être compris entre 1950-01-01T00:00:00Z et 2049-12-31T23:59:59Z inclus.
messages	array<Message>	oui	Tableau de zéro ou plusieurs messages. Les conversations sont représentées par une série chronologique de messages, tandis qu'un seul élément de texte doit être un tableau à un seul élément.
user_properties	map<string, string | number>	non	Toutes les métadonnées définies par l'utilisateur qui s'appliquent au commentaire. Il existe deux types possibles : string et number. La clé d'une propriété utilisateur a le format « type:name », par ex. : "string:Domain Name" ou "number:Star Rating". Le nom de la propriété utilisateur peut être composé de lettres, de chiffres, d'espaces et de traits de soulignement, et peut contenir jusqu'à 32 caractères (est conforme à /\w([\w ]{0,30}\w)?/). La valeur doit être une chaîne ou un nombre selon le type de propriété utilisateur.
thread_id	string	non	Un ID identifiant de manière unique un fil de discussion. Toute chaîne hexadécimale ne dépassant pas 1024 caractères est valide (est conforme à /[0-9a-f]{1,1024}/).
uid	string	défini par Communications Mining	Une source et un ID de commentaire combinés sous la forme de source_id.comment_id. Vous ne devez pas définir ce champ directement car il est automatiquement généré par Communications Mining pour les commentaires téléchargés.
created_at	string	défini par Communications Mining	Un horodatage ISO-8601 avec les mêmes contraintes que le champ timestamp . Vous ne devez pas définir ce champ directement car il est automatiquement généré par Communications Mining lors de la création du commentaire.
updated_at	string	défini par Communications Mining	Un horodatage ISO-8601 avec les mêmes contraintes que le champ timestamp . Vous ne devez pas définir ce champ directement car il est automatiquement généré par Communications Mining lorsque le commentaire est mis à jour.
attachments	array<Attachment>	non	Tableau de zéro ou plusieurs pièces jointes. Une pièce jointe représente un fichier joint à un commentaire.

Nom	Saisie de texte	Requis	DESCRIPTION
name	string	oui	Nom de fichier de la pièce jointe.
size	Numérique	oui	La tailler du contenu du fichier de la pièce jointe en octets.
content_type	string	oui	Le [Type de média](https://en.wikipedia.org/wiki/Media_type) de la pièce jointe. Pour obtenir une liste des valeurs possibles, consultez la liste des [Types de médias IANA](https://www.ana.org/assignments/media-types/media-types.xhtml).
attachment_reference	string	non	Utilisé pour récupérer le contenu du fichier binaire depuis [l'API de pièces jointes](#FixME)

Où Message a le format suivant :

Nom	Saisie de texte	Requis	DESCRIPTION
body	Contenu (Content)	oui	Objet contenant le corps du texte principal du message.
subject	Contenu (Content)	non	Objet contenant l'objet du message.
signature	Contenu (Content)	non	Objet contenant la signature du message.
from	string	non	L'expéditeur du message.
to	array<string>	non	Tableau des destinataires principaux.
cc	array<string>	non	Un tableau de destinataires en copie carbone.
bcc	array<string>	non	Tableau de destinataires en copie carbone invisible.
sent_at	string	non	Un horodatage ISO-8601 indiquant quand le message a été créé. Si l'horodatage ne spécifie pas de fuseau horaire, UTC sera utilisé.
language	string	non	La langue d'origine du message. Dans ce cas, text et translated_from doivent être fournis pour les champs Contenu (Content) .

Où Content a le format suivant :

Nom	Saisie de texte	Requis	DESCRIPTION
text	string	oui	Si language (autre que le language de la source) a été fourni, il doit s'agir du texte traduit du contenu. Sinon, elle doit être dans la langue originale où elle a été collectée. il sera traduit s'il n'est pas dans le language de la source et la source a should_translate défini sur true. 65 536 caractères maximum.
translated_from	string	non	Si language (autre que le language de la source) a été fourni, cela doit être par le texte original du contenu. Enregistrer ce champ sans avoir fourni de language entraînera une erreur. 65 536 caractères maximum.

E-mails bruts

Voir le tableau ci-dessous pour une liste des champs d'e-mail bruts disponibles.

Nom	Saisie de texte	Requis	DESCRIPTION
headers	En-têtes	oui	Objet contenant les en-têtes de l'e-mail.
body	Corps	oui	Objet contenant le corps principal de l'e-mail.

Où Headers a le format suivant :

Nom	Saisie de texte	Requis	DESCRIPTION
raw	string	non	L'un des raw et parsed est requis. Les en-têtes d'e-mail bruts, fournis sous la forme d'une chaîne unique, avec chaque en-tête sur sa propre ligne.
parsed	map<string, string |<string>tableau<chaîne>>	non	L'un des raw et parsed est requis. Les en-têtes d’e-mail analysés, donnés en tant qu’objet avec des clés de chaîne et des valeurs de chaîne ou de tableau<string> . Chaque clé doit être ASCII et représenter un en-tête d'e-mail. Les chaînes de valeur peuvent être n'importe quel UTF-8 valide. Les listes de valeurs seront concaténées avec , avant d'être définies comme une valeur d'en-tête unique. Si vous avez besoin de clés d'en-tête en double, veuillez utiliser raw à la place.

Où Body a le format suivant :

Nom	Saisie de texte	Requis	DESCRIPTION
plain	string	non	Au moins une des plain et html est requise. Le contenu en texte brut de l'e-mail. 65 536 caractères maximum.
html	string	non	Au moins une des plain et html est requise. Le contenu HTML de l'e-mail.