- API 文档
- CLI
- 集成指南
- 博客
注释
comments
,而用户指南和 Communications Mining 用户界面将主要引用messages
。
comments
,以准备将其上传到 Communications Mining,以及如何了解从 Communications Mining 中提取的数据。
“概述”部分介绍注释对象的整体结构。 如果要通过 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": <UNIQUE ID>,
"timestamp": <TIMESTAMP>,
"messages": [
{
"body": { "text": <TEXT> },
...
}
],
"user_properties": { ... },
}
如上面的代码片段所示,除了实际的文本段外,注释还总是具有 ID 和时间戳。 此 ID 在包含消息的来源中必须是唯一的。 时间戳用于在平台用户界面中按日期进行筛选和排序,以及生成基于日期的分析。
除了这些必填字段外,还应根据注释的类型设置其他字段。 如果您的数据已通过集成上传到 Communications Mining,则 Communications Mining 会自动填充所有必填字段。 请查看以下部分以获取更详细的说明。
电子邮件
sync-raw-emails
端点,对于已处理的电子邮件,请使用sync
端点。
同步原始电子邮件时,请按原样提供提取的 MIME 电子邮件标头和电子邮件正文(查看参考资料以获取原始电子邮件格式的说明)。 Communications Mining 解析标头并清理电子邮件正文。
Communications Mining 如何处理原始电子邮件?
Communications Mining:
- 在消息对象
messages[0]
中设置特定于电子邮件的字段 - 设置
thread_id
字段和thread_properties
对象 - 通过去除带引号的电子邮件并将签名放入单独的
signature
字段中,来清理电子邮件正文 - 使用从电子邮件标头中提取的元数据填充
user_properties
对象。
如果电子邮件中不存在某个字段,则根本不会在注释中设置该字段(而不是设置为 null 或空值)。 例如,以下示例中的注释不包含“密送:”字段。
如果在上传到 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 <alice@example.com>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <e7784b5b@mail.example.com>\nSubject: Figures for today\nTo: Bob <bob@company.com>\nCc: Joe <joe@company.com>"
}
},
"user_properties": {
"string:Team": "Team XYZ"
}
}
{
"raw_email": {
"body": {
"plain": "Hi Bob,\n\nCould you send me the figures for today?\n\nThanks,\nAlice"
},
"headers": {
"raw": "From: Alice Smith <alice@example.com>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <e7784b5b@mail.example.com>\nSubject: Figures for today\nTo: Bob <bob@company.com>\nCc: Joe <joe@company.com>"
}
},
"user_properties": {
"string:Team": "Team XYZ"
}
}
{
"comment": {
"id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
"timestamp": "2021-08-03T09:57:42Z",
"user_properties": {
"string:Has Signature": "Yes",
"string:Sender": "alice@example.com",
"string:Thread": "<e7784b5b@mail.example.com>",
"string:Message ID": "<e7784b5b@mail.example.com>",
"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\" <bob@company.com>"],
"cc": ["\"Joe\" <joe@company.com>"],
"sent_at": "2021-08-03T09:57:42Z",
"from": "\"Alice Smith\" <alice@example.com>"
}
],
"thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
},
"thread_properties": {
"duration": null,
"response_time": null,
"num_messages": 1,
"num_participants": 3,
"first_sender": "alice@example.com",
"thread_position": 0
}
}
{
"comment": {
"id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
"timestamp": "2021-08-03T09:57:42Z",
"user_properties": {
"string:Has Signature": "Yes",
"string:Sender": "alice@example.com",
"string:Thread": "<e7784b5b@mail.example.com>",
"string:Message ID": "<e7784b5b@mail.example.com>",
"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\" <bob@company.com>"],
"cc": ["\"Joe\" <joe@company.com>"],
"sent_at": "2021-08-03T09:57:42Z",
"from": "\"Alice Smith\" <alice@example.com>"
}
],
"thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
},
"thread_properties": {
"duration": null,
"response_time": null,
"num_messages": 1,
"num_participants": 3,
"first_sender": "alice@example.com",
"thread_position": 0
}
}
线程属性
以下线程属性可用。
名称 | 说明 |
---|---|
thread_position | 注释在会话中的位置,通过按timestamp 对注释进行排序来计算。 从0 开始。
|
num_messages | 会话中的注释数量。 |
num_participants | 会话中唯一参与者(发件人、收件人、抄送、密件抄送)总数。 |
first_sender | 会话中第一个注释的发件人。 |
duration | 会话中第一个注释与最后一个注释的timestamps 之间的差异 (以秒为单位)。 如果 ,则系统会设置为null num_messages 是 1(即 线程仅包含 1 个注释)。 注意:注释的
timestamp 对应于相应原始电子邮件的sent_at 字段。
|
response_time | 会话中第一个注释与会话中第一个响应之间的差异 (以秒为单位)。 会话中的第一个响应是发件人不是first_sender 的最早注释。 如果会话中没有任何响应(即会话中的所有电子邮件都来自同一发件人),则设置为null 。
|
每次将新注释添加到平台时,都会更新相应线程的线程属性。
thread_position
之外,会话中每条注释的所有属性都相同。
除正文外,通过表单提交的典型支持工单还可能包含主题、发件人信息(例如姓名或电子邮件地址)以及其他可以上传的结构化数据(例如工单主题)。作为注释的用户属性的一部分。
{
"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": "alice.smith@example.com"
}
],
"user_properties": {
"string:Customer Name": "Alice Smith",
"string:Source": "Support Form",
"string:Topic": "Broadband"
}
}
{
"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": "alice.smith@example.com"
}
],
"user_properties": {
"string:Customer Name": "Alice Smith",
"string:Source": "Support Form",
"string:Topic": "Broadband"
}
}
messages
数组中为每个注释设置多条消息的情况(所有其他类型的注释,每个注释一条消息)。 您还可以为每条消息设置发件人和发送消息的时间。 与支持工单类似,您通常拥有结构化数据(例如聊天时长或解决状态),可以将其作为注释的用户属性的一部分上传。
{
"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"
}
]
}
{
"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
...
},
```
```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
...
},
```
```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 内容。
|