Anmerkungen

Kommentarobjekt in der Communications Mining-API und seine Beziehung zu Nachrichten in der Benutzeroberfläche.

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.

Beim Hochladen von Daten in Communications Mining oder Abrufen von Daten aus Communications Mining ist es wichtig zu verstehen, wie unterschiedliche Datentypen (z. B. E-Mails oder Support-Tickets) als Kommentare dargestellt werden sollen. Auf dieser Seite wird erklärt, wie Sie Ihre Daten als Communications Mining comments modellieren, um sie für den Upload vorzubereiten, und wie die von Communications Mining abgerufenen Daten zu verstehen sind.

Beispiel eines Kommentars, der aus einer E-Mail erstellt wurde

Communications Mining™-Kommentar, der aus einer Überprüfung erstellt wurde

Im Abschnitt Übersicht wird die Gesamtstruktur eines Kommentarobjekts beschrieben. Wenn Sie Daten über die API in Communications Mining™ hochladen möchten oder verstehen möchten, wie Daten verarbeitet werden, die über die API in Communications Mining hochgeladen wurden, sehen Sie sich den Abschnitt Kommentare erstellt über die API an. Sie können detaillierte Beschreibungen für jeden der häufig verwendeten Kommentartypen (E-Mails oder Support-Tickets) finden.

Wenn Sie besser verstehen möchten, wie Daten verarbeitet werden, die über eine Integration in Communications Mining hochgeladen wurden, sehen Sie sich den Abschnitt Durch Integrationen erstellte Kommentare an. Eine vollständige Liste der verfügbaren Kommentarobjektfelder finden Sie im Abschnitt Referenz .

Überblick

Communications Mining™ arbeitet mit verschiedenen Arten von Textdaten wie E-Mails, Umfrageantworten, Support-Tickets oder Kundenrezensionen. Gemeinsam ist diesen Datentypen, dass sie alle aus Kommunikationseinheiten bestehen (aus einer E-Mail, einer Umfrageantwort, einem Support-Ticket, einer Kundenrezension). In Communications Mining wird eine einzelne Nachricht z. B. als Kommentar dargestellt.

Unabhängig davon, welche Art von Kommunikationseinheit ein Kommentar symbolisiert, behält er diese grundlegende Struktur durchgängig bei:

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

Zusätzlich zu diesen Pflichtfeldern sollten je nach Typ des Kommentars weitere Felder festgelegt werden. Wenn Ihre Daten über eine Integration in Communications Mining™ hochgeladen wurden, füllt Communications Mining automatisch alle erforderlichen Felder aus. Eine detailliertere Beschreibung finden Sie in den folgenden Abschnitten.

Kommentare, die über die API erstellt wurden

Emails

Während die einfachste Möglichkeit, E-Mails mit Communications Mining™ zu synchronisieren, die Exchange-Integration ist, können Sie in Fällen, in denen Sie Ihre eigene E-Mail-Extraktion durchführen, E-Mails über die API synchronisieren. Verwenden Sie den sync-raw-emails -Endpunkt für unformatierte E-Mails und den sync -Endpunkt für verarbeitete E-Mails.

Geben Sie beim Synchronisieren unformatierter E-Mails die extrahierten MIME-E-Mail-Header und den E-Mail-Text so an, wie sie sind (eine Beschreibung des unformatierten E-Mail-Formats finden Sie in der Referenz ). Communications Mining analysiert die Header und bereinigt den E-Mail-Text.

Hinweis:

Das folgende Beispiel für eine unformatierte E-Mail zeigt eine sehr kleine Anzahl von Headern der Kürze entsprechend. Senden Sie alle extrahierten Header an Communications Mining, die wahrscheinlich viel länger sind als im Beispiel.

Wichtig:

Wie verarbeitet Communications Mining unformatierte E-Mails?

• Legt die E-Mail-spezifischen Felder im Nachrichtenobjekt messages[0]
• Legt das Feld thread_id und das Objekt thread_properties fest
• Bereinigung des E-Mail-Textkörpers durch Entfernen von E-Mails mit Anführungszeichen und Einfügen der Signatur in ein separates signature -Feld
• Füllt das user_properties -Objekt mit Metadaten auf, die aus E-Mail-Headern extrahiert wurden. Wenn ein Feld in der E-Mail nicht vorhanden ist, wird es überhaupt nicht im Kommentar festgelegt ( sondern auf einen NULL- oder leeren Wert festgelegt. Der Kommentar im folgenden Beispiel enthält beispielsweise kein BCC: -Feld.

Wenn Sie E-Mails vor dem Hochladen in Communications Mining mit anderen Daten anreichern, können Sie diese zusätzlichen Daten in den Benutzereigenschaften des Kommentars angeben.

Die verarbeitete unformatierte E-Mail sieht wie im folgenden Beispiel für eine verarbeitete E-Mail aus. Überprüfen Sie die Anzahl der zusätzlichen Felder, die Communications Mining erstellt hat. Wenn Sie verarbeitete E-Mails hochladen möchten, strukturieren Sie sie wie im Beispiel für die verarbeitete E-Mail.

Beispiel-E-Mail

Unformatierte E-Mail

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

Verarbeitete E-Mail

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

Thread-Eigenschaften

Die folgenden Thread-Eigenschaften sind verfügbar.

Name	BESCHREIBUNG
thread_position	Position des Kommentars im Thread, berechnet durch Sortieren des Kommentars nach timestamp . Beginnt um 0 .
num_messages	Anzahl der Kommentare im Thread.
num_participants	Gesamtanzahl der eindeutigen Teilnehmer (Von, An, CC, BCC) im Thread.
first_sender	Absender des ersten Kommentars im Thread.
duration	Differenz (in Sekunden) zwischen dem timestamps des ersten und letzten Kommentars im Thread. Wird auf null festgelegt, wenn num_messages ist 1 (d. h Thread enthält nur 1 Kommentar). Hinweis: Das timestamp eines Kommentars entspricht dem sent_at -Feld der entsprechenden unformatierten E-Mail.
response_time	Unterschied (in Sekunden) zwischen dem ersten Kommentar im Thread und der ersten Antwort im Thread. Die erste Antwort im Thread ist der älteste Kommentar, bei dem der Absender nicht first_sender ist. Wird auf null festgelegt, wenn keine Antworten im Thread vorhanden sind (d. h. wenn alle E-Mails im Thread vom selben Absender stammen.

Jedes Mal, wenn der Plattform ein neuer Kommentar hinzugefügt wird, werden die Thread-Eigenschaften des entsprechenden Threads aktualisiert.

Hinweis:

Abgesehen von thread_position sind alle Eigenschaften für jeden Kommentar im Thread gleich.

Support-Tickets

Zusätzlich zum Haupttext kann ein typisches Support-Ticket, das über ein Formular eingereicht wird, einen Betreff, Informationen über den Absender (z. B. Name oder E-Mail-Adresse) und zusätzliche strukturierte Daten (z. B. das Thema des Tickets) enthalten, die hochgeladen werden können als Teil der Benutzereigenschaften des Kommentars.

Das folgende Beispiel zeigt, wie ein Support-Ticket als Communications Mining™-Kommentar formatiert wird und wie dieser Kommentar auf der Benutzeroberfläche der Plattform angezeigt wird. Ihre Benutzereigenschaften können sich je nach den von Ihnen gesammelten Daten unterscheiden.

Beispiel für ein Support-Ticket

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

Kommentare, die von Integrationen erstellt wurden

E-Mails (Microsoft Exchange)

Microsoft Exchange-E-Mails, die über die Exchange-Integration in Communications Mining erfasst werden, werden automatisch auf die gleiche Weise wie unformatierte E-Mails in Kommentarobjekte konvertiert .

Anhänge und Anhangsinhalte

An Kommentare können Dateien angehängt sein. Wenn ein Kommentar Anhänge hat, enthält das Feld attachments Metadaten darüber:

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

Darüber hinaus können Sie auch den Inhalt des Anhangs herunterladen. Beim Herunterladen des Inhalts des Anhangs wird das Feld attachment_reference zurückgegeben:

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

Verwenden Sie attachment_reference , um den Binärdateiinhalt aus der Anlagen-API abzurufen. Für das vorherige Beispiel rufen Sie die folgende URL ab: https://cloud.uipath.com///reinfer_/api/v1/attachments/CjQSIExTHEqtdnoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G.

Weitere Informationen zu diesem Anforderungstyp finden Sie in der API-Referenz.

Wenn das Anhangsobjekt keine attachment_reference -Eigenschaft hat, können Sie den Inhalt des Anhangs nicht herunterladen. Dies kann folgende Ursachen haben:

• Communications Mining™ hat den Inhalt des Anhangs nicht empfangen.
• Der Inhalt des Anhangs hat die Größenbegrenzung für das Hochladen in Communications Mining überschritten.
• Communications Mining hat den Anhang verarbeitet, bevor er die Dateiinhalte unterstützt.

Weitere Informationen zu den Inhalten von Anhängen finden Sie auf der Seite Anhang.

Referenz (Reference)

Anmerkungen

Eine Liste der verfügbaren Kommentarfelder finden Sie in der folgenden Tabelle. Wenn Sie mit Communications Mining™-Kommentarobjekten nicht vertraut sind, überprüfen Sie die Übersicht.

Name	Typ	Erforderlich	BESCHREIBUNG
id	string	ja	Identifiziert einen Kommentar eindeutig innerhalb einer Quelle. Jede hexadezimale Zeichenfolge mit bis zu 1024 Zeichen ist gültig (entspricht /[0-9a-f]{1,1024}/).
timestamp	string	ja	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>	ja	Ein Array mit null oder einer Nachricht.
user_properties	map<string, string | number>	nein	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	nein	Eine ID, die einen E-Mail-Thread eindeutig identifiziert. Jede hexadezimale Zeichenfolge mit bis zu 1024 Zeichen ist gültig (entspricht /[0-9a-f]{1,1024}/).
uid	string	von Communications Mining™ festgelegt	Eine kombinierte Quellen- und Kommentar-ID im Format source_id.comment_id. Sie sollten dieses Feld nicht direkt festlegen, da es automatisch von Communications Mining für hochgeladene Kommentare generiert wird.
created_at	string	von Communications Mining festgelegt	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	von Communications Mining festgelegt	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>	nein	Ein Array von null oder mehr Anhängen. Ein Anhang stellt eine Datei dar, die an einen Kommentar angehängt ist.

Name	Typ	Erforderlich	BESCHREIBUNG
name	string	ja	Der Dateiname des Anhangs.
size	Nummer	ja	Die Größe des Dateiinhalts des Anhangs in Bytes.
content_type	string	ja	Der Medientyp des Anhangs. Eine Liste möglicher Werte finden Sie in der Liste IANA-Medientypen .
attachment_reference	string	nein	Wird verwendet, um den Inhalt der Binärdatei aus der Anlagen-API abzurufen

Dabei hat Message das folgende Format:

Name	Typ	Erforderlich	BESCHREIBUNG
body	Inhalt	ja	Ein Objekt, das den Haupttexttext der Nachricht enthält.
subject	Inhalt	nein	Ein Objekt, das den Betreff der Nachricht enthält.
signature	Inhalt	nein	Ein Objekt, das die Signatur der Nachricht enthält.
from	string	nein	Der Absender der Nachricht.
to	array<string>	nein	Ein Array primärer Empfänger.
cc	array<string>	nein	Ein Array von CC-Empfängern.
bcc	array<string>	nein	Eine Reihe von BCC-Empfängern.
sent_at	string	nein	An ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
language	string	nein	Die Originalsprache der Nachricht. Wenn dies angegeben ist, sollten sowohl text als translated_from für die Inhaltsfelder angegeben werden.

Dabei hat Content das folgende Format:

Name	Typ	Erforderlich	BESCHREIBUNG
text	string	ja	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	nein	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.

Unformatierte E-Mails

In der folgenden Tabelle finden Sie eine Liste der verfügbaren unformatierten E-Mail-Felder.

Name	Typ	Erforderlich	BESCHREIBUNG
headers	Header	ja	Ein Objekt, das die Header der E-Mail enthält.
body	Text	ja	Ein Objekt, das den Haupttext der E-Mail enthält.

Dabei hat Headers das folgende Format:

Name	Typ	Erforderlich	BESCHREIBUNG
raw	string	nein	Entweder raw oder parsed ist erforderlich. Die unformatierten E-Mail-Header, die als einzelne Zeichenfolge angegeben werden, wobei jeder Header in einer eigenen Zeile steht.
parsed	map<string, string | array<string>>	nein	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.

Dabei hat Body das folgende Format:

Name	Typ	Erforderlich	BESCHREIBUNG
plain	string	nein	Mindestens einer von plain und html ist erforderlich. Der Klartext-Inhalt der E-Mail. Höchstens 65536 Zeichen.
html	string	nein	Mindestens einer von plain und html ist erforderlich. Der HTML-Inhalt der E-Mail.