コメント

Communications Mining API のコメント オブジェクト、およびユーザー インターフェイスのメッセージとの関係。

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.

Communications Mining にデータをアップロードしたり、Communications Mining からデータを取得したりする場合、さまざまな種類のデータ (メール、サポート チケットなど) をどのようにコメントとして表す必要があるかを理解しておくことが重要です。 このページでは、データを Communications Mining の comments としてモデル化し、アップロード用に準備する方法と、Communications Mining から取得したデータを理解する方法について説明します。

メールから作成されたコメントの例

レビューから作成された Communications Mining™ のコメント

「概要」セクションでは、コメント オブジェクトの全体的な構造について説明します。Communications Mining™ に API 経由でデータをアップロードする方法、または Communications Mining に API 経由でアップロードしたデータを処理する方法について詳しくは、「API 経由で作成されたコメント」セクションをご覧ください。よく使用される種類のコメント (メールまたはサポート チケット) それぞれについて詳しく説明されています。

連携を介して Communications Mining にアップロードされたデータを処理する方法について詳しくは、「連携によって作成されたコメント」セクションをご覧ください。最後に、利用可能なすべてのコメント オブジェクト フィールドのリストについては、「参照」セクションをご覧ください。

概要

Communications Mining™ は、メール、アンケートへの回答、サポート チケット、顧客のレビューなど、さまざまな種類のテキスト データを処理します。これらの種類のデータに共通するのは、すべてがコミュニケーションの単位 (メール、アンケートへの回答、サポート チケット、顧客のレビュー) で構成されているところです。たとえば、Communications Mining では、1 つのメッセージは 1 つのコメントとして表されます。

あるコメントがどのようなコミュニケーションの単位の種類を表しているかに関係なく、Communications Mining では、常に次の基本構造が維持されます。

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

コメントの種類によっては、上記の必須フィールド以外に他のフィールドも設定する必要があります。データが連携を介して Communications Mining™ にアップロードされている場合、必要なフィールドはすべて Communications Mining によって自動的に入力されます。詳しくは、以下のセクションをご覧ください。

API 経由で作成されたコメント

メール

メールを Communications Mining™ に同期する場合、Exchange との連携を使用するのが最も簡単ですが、独自のメール抽出方法を使用する場合は、API 経由でメールを同期できます。未加工のメールには sync-raw-emails エンドポイントを使用し、処理済みのメールには sync エンドポイントを使用します。

未加工のメールを同期する場合は、抽出した MIME メール ヘッダーとメールの本文をそのまま指定します (未加工のメールの形式について詳しくは、「 参照 」をご覧ください)。Communications Mining によってヘッダーが解析され、メールの本文がクリーンアップされます。

注:

次の未加工のメールの例では、簡潔にするためにごく少数のヘッダーのみを示しています。抽出したすべてのヘッダーを Communications Mining に送信します。そのため、実際に送信するヘッダーはこの例よりもはるかに長くなる可能性があります。

重要:

Communications Mining では未加工のメールはどのように処理されますか?

• メッセージ オブジェクト messages[0] 内にメール固有のフィールドを設定します。
• thread_id フィールドと thread_properties オブジェクトを設定します。
• 引用メールを削除し、署名を独立した signature フィールドに配置して、メールの本文をクリーンアップします。
• メール ヘッダーから抽出したメタデータを user_properties オブジェクトに設定します。メールに存在しないフィールドは、コメントには一切設定されません (null や空の値には設定されません)。たとえば、次の例のコメントには BCC: フィールドが含まれていません。

Communications Mining にアップロードする前にメールに他のデータを付加すると、この追加データをコメントのユーザー プロパティで指定できます。

処理された未加工のメールは、次の処理されたメールの例のようになります。Communications Mining によって作成された追加のフィールドの数を確認します。処理されたメールをアップロードするには、そのメールを、処理されたメールの例のように構成します。

メールの例

直接メール

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

処理された電子メール

{
  "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_position	スレッド内でのコメントの位置です。コメントを timestamp 順に並べ替えて計算されます。開始値は 0 です。
num_messages	スレッド内のコメントの数。
num_participants	スレッド内の一意の参加者 (送信元、宛先、CC、BCC) の総数。
first_sender	スレッド内の最初のコメントの送信者。
duration	スレッド内の最初のコメントと最後のコメントの timestamps の差 (秒単位) です。num_messages の場合は null に設定されます。 は 1 (つまり、 スレッドにはコメントが1つしか含まれていません)。 注: コメントの timestamp は、対応する未加工のメールの sent_at フィールドに対応します。
response_time	スレッド内の最初のコメントとスレッド内の最初の応答の差 (秒単位) です。スレッドの最初の応答は、送信者が first_sender されていない最も古いコメントです。スレッドに応答がない場合 (つまり、スレッド内のすべてのメールが同じ送信者からのものである場合) に null に設定されます。

プラットフォームに新しいコメントが追加されるたびに、対応するスレッドのスレッドプロパティが更新されます。

注:

thread_positionを除き、すべてのプロパティはスレッド内の各コメントで同じです。

サポート チケット

本文に加えて、フォームを介して送信される一般的なサポートチケットには、件名、送信者に関する情報(名前や電子メールアドレスなど)、およびコメントのユーザープロパティの一部としてアップロードできる追加の構造化データ(チケットのトピックなど)が含まれる場合があります。

以下の例は、サポート チケットを Communications Mining™ のコメントの形式にする方法と、そのコメントがプラットフォームの UI にどのように表示されるかを示しています。実際のユーザー プロパティは、収集するデータによって異なる場合があります。

サポート チケットの例

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

統合によって作成されたコメント

Emails (Microsoft Exchange)

Exchange との連携を介して Communications Mining に取り込まれた Microsoft Exchange のメールは、未加工のメールと同じように自動的にコメント オブジェクトに変換されます。

添付ファイルと添付ファイルの内容

コメントにはファイルが添付されている場合があります。 コメントに添付ファイルがある場合、[ attachments ] フィールドには添付ファイルに関するメタデータが含まれます。

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

また、添付ファイルのコンテンツをダウンロードすることもできます。 添付ファイルの内容をダウンロードすると、[ attachment_reference ] フィールドが返されます。

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

attachment_reference を使用して、添付ファイル API からバイナリ ファイルの内容を取得します。前の例では、次の URL を取得します: https://cloud.uipath.com///reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G。

この種類の要求について詳しくは、『API リファレンス』をご覧ください。

添付ファイル オブジェクトに attachment_reference プロパティがない場合は、添付ファイルのコンテンツをダウンロードできません。 これは、次の理由が考えられます。

• Communications Mining™ が添付ファイルの内容を受け取れませんでした。
• 添付ファイルの内容が Communications Mining へのアップロードのサイズ制限を超えました。
• Communications Mining は、ファイルの内容をサポートする前に添付ファイルを処理していました。

添付ファイルの内容の詳細については、「添付ファイル」ページをご覧ください。

参照

コメント

利用可能なコメント フィールドのリストは、以下の表でご確認ください。Communications Mining™ のコメント オブジェクトに精通していない場合は、「概要」をご覧ください。

名前	型	必須	説明
id	string	○	ソース内でコメントを一意に識別します。最大 1024 文字の 16 進数の文字列はすべて有効です ( /[0-9a-f]{1,1024}/に準拠します)。
timestamp	string	○	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>	○	0 個または 1 個のメッセージの配列。
user_properties	map<string, string | number>	×	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	×	メール スレッドを一意に識別する ID。最大 1024 文字の 16 進数の文字列はすべて有効です ( /[0-9a-f]{1,1024}/に準拠します)。
uid	string	Communications Mining™ で設定	source_id.comment_idの形式で結合されたソースとコメント ID です。このフィールドはアップロードされたコメントに対して Communications Mining によって自動的に生成されるため、直接設定しないでください。
created_at	string	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	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>	×	0 個以上の添付ファイルの配列。 添付ファイルは、コメントに添付されたファイルを表します。

名前	型	必須	説明
name	string	○	添付ファイルのファイル名。
size	Number	○	添付ファイルのファイルの内容のサイズ (バイト単位)。
content_type	string	○	添付ファイルの メディアの種類 です。可能な値のリストについては、「 IANA メディア タイプ 」リストをご覧ください。
attachment_reference	string	×	添付ファイル API からバイナリ ファイルの内容を取得するために使用します

ここで Message の形式は次のとおりです。

名前	型	必須	説明
body	コンテンツ	○	メッセージの本文テキストを含むオブジェクト。
subject	コンテンツ	×	メッセージの件名を含むオブジェクト。
signature	コンテンツ	×	メッセージの署名を格納するオブジェクト。
from	string	×	メッセージの送信者。
to	array<string>	×	プライマリ受信者の配列。
cc	array<string>	×	Cc 受信者の配列。
bcc	array<string>	×	Bcc 受信者の配列。
sent_at	string	×	An ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
language	string	×	メッセージの元の言語。これを指定する場合は、[コンテンツ] フィールドに text と translated_from の両方を指定する必要があります。

ここで Content の形式は次のとおりです。

名前	型	必須	説明
text	string	○	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	×	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.

未加工のメール

利用可能な未加工のメール フィールドのリストについては、以下の表をご覧ください。

名前	型	必須	説明
headers	ヘッダー	○	メールのヘッダーを含むオブジェクトです。
body	本文	○	メールの本文を含むオブジェクトです。

ここで Headers の形式は次のとおりです。

名前	型	必須	説明
raw	string	×	rawとparsedのいずれかが必要です。生の電子メールヘッダーは、単一の文字列として指定され、各ヘッダーは独自の行にあります。
parsed	map<string, string | array<string>>	×	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.

ここで Body の形式は次のとおりです。

名前	型	必須	説明
plain	string	×	plainとhtmlのうち少なくとも 1 つが必要です。メールのプレーンテキストの内容です。 最大 65536 文字です。
html	string	×	plainとhtmlのうち少なくとも 1 つが必要です。メールの HTML コンテンツです。