Commentaires

Objet Commentaires dans l'API Communications Mining et sa relation avec les messages dans l'interface utilisateur.

Each message in Communications Mining™ is represented by a single comment object in the API. As a result, they can be considered equivalent. The developer documentation and API will refer primarily to comments, whilst the user guide and the Communications Mining UI refer primarily to 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 Vue d'ensemble décrit la structure globale d'un objet de commentaire. Si vous souhaitez charger des données vers Communications Mining™ via l’API, ou 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 . Vous pouvez trouver des descriptions détaillées de chacun des types de commentaires couramment 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’objets de commentaire 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": { ... },
}

As shown in the previous code snippet, in addition to the actual piece of text, a comment always has an ID and a timestamp. The ID needs to be unique within the containing message. The timestamp is used in the platform UI to filter and sort by date, and to generate date-based analytics.

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	An ISO-8601 timestamp indicating when the comment was created. If the timestamp does not specify a timezone, UTC will be assumed. The timestamp must be in the range 1950-01-01T00:00:00Z to 2049-12-31T23:59:59Z inclusive.
messages	array<Message>	oui	Tableau de zéro ou un message.
user_properties	map<string, string | number>	non	Any user-defined metadata that applies to the comment. There are two possible types: string and number. The key of a user property has the format "type:name", eg. "string:Domain Name" or "number:Star Rating". The user property name may consist of letters, numbers, spaces, and underscores, and may contain up to 32 characters (conforms to /\w([\w ]{0,30}\w)?/). The value must be a string or a number depending on the type of the user property.
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	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is created.
updated_at	string	défini par Communications Mining	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is updated.
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	An ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
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	If language (other than the source's language) has been supplied, this should be the translated text of the content. Otherwise, it should be in the original language it was collected; it will be translated if not in the source's language and the source has should_translate set to true. Maximum 65536 characters.
translated_from	string	non	If language (other than the source's language) has been supplied, this should be the original text of the content. Supplying this field without having supplied a language will result in an error. At most 65536 characters.

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 | array<string>>	non	One of raw and parsed is required. The parsed email headers, given as an object with string keys and string or array<string> values. Each key must be ASCII, and represents one email header. Value strings may be any valid UTF-8. Lists of values will be concatenated with , before being set as a single header value. If you require duplicate header keys, please use raw instead.

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.