コメント

Communications Mining™ の各メッセージは、API 内では 1 つのコメント オブジェクトで表します。したがって、メッセージとコメント オブジェクトは同等のものと見なすことができます。開発者向けドキュメントと API では主に comments と呼び、ユーザー ガイドと Communications Mining UI では主に 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": { ... },
}

前のコード スニペットに示すように、コメントには、実際のテキストのほかに必ず ID とタイムスタンプが付きます。ID は、そのメッセージが含まれるページ内で一意である必要があります。タイムスタンプは、プラットフォームの UI で日付を条件にしてフィルター処理したり並べ替えたりする場合や、日付ベースの分析を生成する場合に使用します。

コメントの種類によっては、上記の必須フィールド以外に他のフィールドも設定する必要があります。データが連携を介して 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つしか含まれていません)。 Note: The timestamp of a comment corresponds to the sent_at field of the corresponding raw email.
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 ... },

Use attachment_reference to retrieve the binary file content from the attachments API. For the previous example, you fetch the following 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	○	コメントが作成された日時を示す ISO-8601 タイムスタンプ。 タイムスタンプにタイムゾーンが指定されていない場合は、UTCが想定されます。 タイムスタンプは、1950-01-01T00:00:00Z から 2049-12-31T23:59:59Z の範囲である必要があります。
messages	array<Message>	○	0 個または 1 個のメッセージの配列。
user_properties	`map<string, string	number>`	×
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 によって設定	timestamp フィールドと同じ制約を持つ ISO-8601 タイムスタンプ。このフィールドはコメントの作成時に Communications Mining によって自動的に生成されるため、直接設定しないでください。
updated_at	string	Communications Mining によって設定	timestamp フィールドと同じ制約を持つ ISO-8601 タイムスタンプ。このフィールドは、コメントの更新時に Communications Mining によって自動的に生成されるため、直接設定しないでください。
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	×	メッセージが作成された日時を示す ISO-8601 タイムスタンプ。 タイムスタンプにタイムゾーンが指定されていない場合は、UTCが想定されます。
language	string	×	The original language of the message. If this is supplied, both text and translated_from should be supplied for the Content fields.

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

名前	型	必須	説明
text	string	○	language (ソースの language 以外) が指定されている場合、コンテンツの翻訳されたテキストを指定する必要があります。それ以外の場合は、収集時の元の言語にする必要があります。ソースの language ではなく、ソースの should_translate が true に設定されている場合、翻訳されます。最大 65536 文字です。
translated_from	string	×	language(ソースのlanguage以外)が提供されている場合は、コンテンツの元のテキストによって提供されます。languageを指定せずにこのフィールドを指定すると、エラーが発生します。最大 65536 文字です。

未加工のメール

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

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

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

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

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

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