Commentaires

Chaque message dans Communications Mining™ est représenté par un seul objet de commentaire dans l’API. En conséquence, elles peuvent être considérées comme équivalentes. La documentation pour les développeurs 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.

Lorsque vous téléchargez des données vers Communications Mining ou que vous récupérez des données depuis Communications Mining, il est important de comprendre comment différents types de données (tels que les e-mails ou les tickets d'assistance) doivent être représentés par des commentaires. Cette page explique comment modéliser vos données en tant que Communications Mining comments pour les préparer avant leur chargement et comment comprendre les données extraites de Communications Mining.

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

Commentaire Communications Mining™ créé à partir d’un avis

La section Aperçu décrit la structure globale d'un objet de commentaire. Si vous souhaitez télécharger des données vers Communications Mining™ via l’API ou savoir comment traiter les données téléchargées vers Communications Mining via l’API, consultez la section Commentaires créés via l’API . Vous pouvez trouver des descriptions détaillées pour chacun des types de commentaires les plus utilisés (e-mails ou tickets d'assistance). Si vous souhaitez mieux comprendre comment traiter les données téléchargées dans 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 de commentaires disponibles, consultez la section Référence .

Vue d'ensemble (Overview)

Communications Mining™ fonctionne avec différents types de données textuelles tels que les e-mails, les réponses aux enquêtes, les tickets d’assistance ou les avis des clients. Ces types de données ont en commun le fait qu’ils se composent tous d’unités de communication (un e-mail, une réponse à une enquête, un ticket d’assistance, un avis d’un client). Dans Communications Mining, un seul message est représenté par un commentaire, par exemple.

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 illustré dans l'extrait de code précédent, en plus du texte réel, un commentaire possède toujours un ID et un horodatage. L'ID doit être unique dans le contenu du 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 vers 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, dans les cas où 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.

Lorsque vous synchronisez des e-mails bruts, fournissez les en-têtes d'e-mail MIME extraits et le corps de l'e-mail tels quels. Communications Mining analyse les en-têtes et nettoyer le corps de l’e-mail.

Remarque :

L'exemple d'e-mail brut suivant montre un très petit nombre d'en-têtes par souci de simplicité. Envoyez tous les en-têtes extraits à Communications Mining, qui seront probablement beaucoup plus longs que dans l’exemple.

Important :

Comment Communications Mining traite-t-il les e-mails bruts ?

• 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 de l’exemple suivant ne contient pas de champ BCC: .

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é suivant. Vérifiez 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 de l'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 dans le 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 :

Hormis 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 suivant montre comment formater un ticket d’assistance en tant que commentaire Communications Mining™ et comment ce commentaire s’affiche dans l’interface utilisateur de la plate-forme. Vos propriétés 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"
  }
}

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 commentaires 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 à partir de l'API des pièces jointes. Pour l’exemple précédent, vous récupérez l’URL suivante : https://cloud.uipath.com///reinfer_/api/v1/attachments/CjQSEIExTHEqtdntxxxz2WtbZDformeiIIVqcP1Sfx2L4epyRB. carte1RSODvheQ3bvLhj3L-_81G.

Consultez la Référence de l’API 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 suivant 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 section Vue d’ensemble.

Nom	Saisie de texte	Requis	DESCRIPTION
id	string	oui	Identifie un commentaire de manière unique dans une source. Toute chaîne hexadécimale allant jusqu'à 1024 caractères est valide (se 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 un message.
user_properties	`map<string, string	Nombre>	non
thread_id	string	non	Un ID qui identifie de manière unique un fil de discussion d'e-mail. Toute chaîne hexadécimale allant jusqu'à 1024 caractères est valide (se 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 de la pièce jointe. Pour obtenir une liste des valeurs possibles, consultez la liste Types de médias IANA .
attachment_reference	string	non	Utilisé pour récupérer le contenu du fichier binaire à partir de l’API des pièces jointes

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. Si cela est fourni, les champs text et translated_from doivent être fournis dans les champs Contenu.

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

Consultez le tableau suivant pour obtenir 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	Tableau>`	non

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.