注释

Communications Mining 中的每条消息都由 API 中的单个注释对象表示。 因此，可以将它们视为等效。 开发者文档和 API 将主要引用comments ，而用户指南和 Communications Mining 用户界面将主要引用messages 。

将数据上传到 Communications Mining 或从 Communications Mining 获取数据时，了解如何将不同类型的数据（例如电子邮件、支持票证或聊天）表示为注释，这一点很重要。 本页说明如何将数据建模为 Communications Mining comments ，以准备将其上传到 Communications Mining，以及如何了解从 Communications Mining 中提取的数据。

根据电子邮件创建的注释示例

根据审核创建的 Communications Min 注释

“概述”部分介绍注释对象的整体结构。 如果要通过 API 将数据上传到 Communications Mining，或了解如何处理通过 API 上传到 Communications Mining 的数据，请查看“通过 API 创建的注释”部分。 您可以找到每种常用注释类型（电子邮件、支持工单和聊天）的详细说明。 如果您想更好地了解如何处理通过集成上传到 Communications Mining 的数据，请查看“集成创建的注释”部分。 最后，有关可用注释对象字段的完整列表，请查看参考部分。

概述

Communications Mining 适用于各种类型的文本数据，例如电子邮件、调查响应、支持票证或客户评论。 这些类型的数据的共同点是，它们都由通信单元（电子邮件、调查响应、支持票证、客户评论）组成。 在 Communications Mining 中，即单个消息表示为注释。

无论注释代表哪种通信单位，它都会始终保持以下基本结构：

{
  "id": <UNIQUE ID>,
  "timestamp": <TIMESTAMP>,
  "messages": [
    {
      "body": { "text": <TEXT> },
      ...
    }
  ],
  "user_properties": { ... },
}

如上面的代码片段所示，除了实际的文本段外，注释还总是具有 ID 和时间戳。 此 ID 在包含消息的来源中必须是唯一的。 时间戳用于在平台用户界面中按日期进行筛选和排序，以及生成基于日期的分析。

除了这些必填字段外，还应根据注释的类型设置其他字段。 如果您的数据已通过集成上传到 Communications Mining，则 Communications Mining 会自动填充所有必填字段。 请查看以下部分以获取更详细的说明。

通过 API 创建的注释

电子邮件

虽然将电子邮件同步到 Communications Mining 的最简单方法是通过Exchange 集成，但如果您要自己提取电子邮件，则可以通过 API 同步电子邮件。 对于原始电子邮件，请使用sync-raw-emails端点，对于已处理的电子邮件，请使用sync端点。

同步原始电子邮件时，请按原样提供提取的 MIME 电子邮件标头和电子邮件正文（查看参考资料以获取原始电子邮件格式的说明）。 Communications Mining 解析标头并清理电子邮件正文。

注意：为简洁起见，下面的原始电子邮件示例显示了极少量的标头。 将所有提取的标头发送到 Communications Mining，这些标头可能比示例中的标头长得多。

重要提示：

Communications Mining 如何处理原始电子邮件？

Communications Mining：

• 在消息对象messages[0]中设置特定于电子邮件的字段
• 设置thread_id字段和thread_properties对象
• 通过去除带引号的电子邮件并将签名放入单独的signature字段中，来清理电子邮件正文
• 使用从电子邮件标头中提取的元数据填充user_properties对象。

如果电子邮件中不存在某个字段，则根本不会在注释中设置该字段（而不是设置为 null 或空值）。 例如，以下示例中的注释不包含“密送：”字段。

如果在上传到 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	会话中唯一参与者（发件人、收件人、抄送、密件抄送）总数。
first_sender	会话中第一个注释的发件人。
duration	会话中第一个注释与最后一个注释的timestamps之间的差异 (以秒为单位)。 如果 ，则系统会设置为nullnum_messages 是 1（即 线程仅包含 1 个注释）。 注意：注释的timestamp对应于相应原始电子邮件的sent_at字段。
response_time	会话中第一个注释与会话中第一个响应之间的差异 (以秒为单位)。 会话中的第一个响应是发件人不是first_sender的最早注释。 如果会话中没有任何响应（即会话中的所有电子邮件都来自同一发件人），则设置为null 。

每次将新注释添加到平台时，都会更新相应线程的线程属性。

注意：除了thread_position之外，会话中每条注释的所有属性都相同。

支持票证

除正文外，通过表单提交的典型支持工单还可能包含主题、发件人信息（例如姓名或电子邮件地址）以及其他可以上传的结构化数据（例如工单主题）。作为注释的用户属性的一部分。

下面的示例演示了如何将支持工单的格式设置为 Communications Mining 注释，以及该注释在平台的用户界面中的显示方式。 您的用户属性可能会有所不同，具体取决于您收集的数据。

支持工单示例

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

聊天

在所有类型的注释中，聊天是唯一应在messages数组中为每个注释设置多条消息的情况（所有其他类型的注释，每个注释一条消息）。 您还可以为每条消息设置发件人和发送消息的时间。 与支持工单类似，您通常拥有结构化数据（例如聊天时长或解决状态），可以将其作为注释的用户属性的一部分上传。

下面的示例说明了如何将聊天对话设置为 Communications Mining 注释的格式，以及该注释在平台用户界面中的显示方式。 当然，您的用户属性可能会有所不同，具体取决于您收集的数据。

聊天示例

{
  "id": "5be6a3e4",
  "timestamp": "2020-02-28T19:20:22Z",
  "user_properties": {
    "number:Duration": 542,
    "string:Close Reason": "Complete Acknowledged",
    "string:Resolution": "Unknown"
  },
  "messages": [
    {
      "body": {
        "text": "Hi, my name is Alice 👋 How can I help?"
      },
      "sent_at": "2020-02-28T19:20:01Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "Hi. I would like to close my account"
      },
      "sent_at": "2020-02-28T19:22:39Z",
      "from": "Customer"
    },
    {
      "body": {
        "text": "Thanks for waiting. Please call our account team at this number: 012-3456-7890."
      },
      "sent_at": "2020-02-28T19:27:50Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "Ok, thanks, I will follow up with them"
      },
      "sent_at": "2020-02-28T19:28:31Z",
      "from": "Customer"
    },
    {
      "body": {
        "text": "Sure thing! Anything else I can help you with today?"
      },
      "sent_at": "2020-02-28T19:28:42Z",
      "from": "Agent"
    },
    {
      "body": {
        "text": "No. Thanks."
      },
      "sent_at": "2020-02-28T19:29:03Z",
      "from": "Customer"
    }
  ]
}

集成创建的注释

电子邮件 (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] (#FIXME) 检索二进制文件内容。 对于上述示例，您可以获取以下 URL：https://cloud.uipath.com/<organisation>/<tenant>/reinder_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIIVqcP1Sfx2L4epyRQTasa1RSODvheQ3bvLhj3L-_81G。

查看 [API 参考](#FIXME)，详细了解此类请求。

如果附件对象没有attachment_reference属性，您将无法下载附件的内容。 这可能是因为：

• Communications Mining 未收到附件的内容。
• 附件内容超过了上传到 Communications Mining 的大小限制。
• Communications Mining 在支持文件内容之前处理了附件。

在附件页面了解有关附件内容的更多信息。

参考

注释

有关可用注释字段的列表，请参阅下表。 如果您不熟悉 Communications Mining 注释对象，请查看概述。

名称	类型	必填	说明
id	字符串	是	在源中唯一标识注释。 不超过 1024 个字符的任何十六进制字符串都有效（符合 /[0-9a-f]{1,1024}/）。
timestamp	字符串	是	指明注释创建时间的 ISO-8601 时间戳。 如果时间戳未指定时区，则采用 UTC。 时间戳必须在 1950-01-01T00:00:00Z 到 2049-12-31T23:59:59Z（含）范围内。
messages	array<Message>	是	由零条或多条消息组成的数组。 对话表示为按时间顺序排列的一系列消息，而单个文本段应为单元素数组。
user_properties	map<string, string | number>	否	适用于注释的任何用户定义的元数据。 有两种可能的类型： string和number 。 用户属性键的格式为“类型:名称”，例如 “字符串：域名”或“数字：星级”。 用户属性名称可由字母、数字、空格和下划线组成，最多可包含 32 个字符 (符合 /\w([\w ]{0,30}\w)?/)。 该值必须是字符串或数字，具体取决于用户属性的类型。
thread_id	字符串	否	唯一标识电子邮件会话的 ID。 不超过 1024 个字符的任何十六进制字符串都有效（符合 /[0-9a-f]{1,1024}/）。
uid	字符串	由 Communications Mining 设置	合并的来源和注释 ID，格式为source_id.comment_id 。 您不应直接设置此字段，因为它是 Communications Mining 为上传的注释自动生成的。
created_at	字符串	由 Communications Mining 设置	ISO-8601 时间戳，其约束与timestamp字段相同。 您不应直接设置此字段，因为它是创建注释时由 Communications Mining 自动生成的。
updated_at	字符串	由 Communications Mining 设置	ISO-8601 时间戳，其约束与timestamp字段相同。 您不应直接设置此字段，因为它是在更新注释时由 Communications Mining 自动生成的。
attachments	array<Attachment>	否	由零个或多个附件组成的数组。 附件表示附加到注释的文件。

名称	类型	必填	说明
name	字符串	是	附件的文件名。
size	数字	是	附件文件内容的大小 (以字节为单位)。
content_type	字符串	是	附件的[媒体类型](https://en.wikipedia.org/wiki/Media_type)。 有关可能值的列表，请参阅 [IANA 媒体类型] (https://www.iana.org/assignments/media-types/media-types.xhtml) 列表。
attachment_reference	字符串	否	用于从 [附件 API] 检索二进制文件内容 (#FIXME)

其中Message具有以下格式：

名称	类型	必填	说明
body	内容	是	包含消息主体文本的对象。
subject	内容	否	包含消息主题的对象。
signature	内容	否	包含消息签名的对象。
from	字符串	否	消息发件人。
to	array<string>	否	主要收件人数组。
cc	array<string>	否	副本收件人数组。
bcc	array<string>	否	密件副本收件人数组。
sent_at	字符串	否	指示消息创建时间的 ISO-8601 时间戳。 如果时间戳未指定时区，则采用 UTC。
language	字符串	否	消息的原始语言。 如果提供了此项，则应为“内容” 字段同时提供text和translated_from 。

其中Content具有以下格式：

名称	类型	必填	说明
text	字符串	是	如果已提供language （而非来源的language ），则这应是内容的翻译文本。 否则，应使用收集时的原始语言；如果源的language中没有该内容，并且源已将should_translate设置为true ，则对其进行翻译。 最多支持 65536 个字符。
translated_from	字符串	否	如果提供了language （而非来源的language ），则应提供内容的原始文本。 在未提供language的情况下提供此字段将导致发生错误。 最多 65536 个字符。

原始电子邮件

有关可用原始电子邮件字段的列表，请参阅下表。

名称	类型	必填	说明
headers	标头	是	包含电子邮件标头的对象。
body	正文	是	包含电子邮件正文的对象。

其中Headers具有以下格式：

名称	类型	必填	说明
raw	字符串	否	需要raw和parsed 。 原始电子邮件标头，以单个字符串形式提供，每个标头占自己的行。
parsed	映射<字符串，字符串|数组 <string>>	否	需要raw和parsed 。 已解析的电子邮件标头，作为具有字符串键和字符串或数组<string>值的对象提供。 每个密钥必须是 ASCII，并代表一个电子邮件标头。 值字符串可以是任何有效的 UTF-8 字符串。 值列表将使用,连接，然后再设置为单个标头值。 如果您需要重复的标头键，请改用raw 。

其中Body具有以下格式：

名称	类型	必填	说明
plain	字符串	否	至少需要plain和html 。 电子邮件的明文内容。 最多 65536 个字符。
html	字符串	否	至少需要plain和html 。 电子邮件的 HTML 内容。