将消息传送元数据用于 Zendesk Web Widget和 SDK

我的服务模式是什么？

消息传送元数据使用对话字段和对话标签（也称为 自定义工单字段 和 自定义工单标签）来收集关于支持问题或产品或服务的更多信息。您也可以通过在管理中心创建触发器，使用这些元数据在专员工作区中更好地转接工单。如果您希望终端用户看到自定义字段，可以将消息传送元数据添加到工单中，然后再将其添加到帮助中心。

您还可以使用对话字段和标签，通过客户端 API 从Web Widget和 Zendesk SDK 向专员发送消息传送元数据。这样系统会自动将相关信息（例如产品 SKU、确认号或订单 ID）传输给专员。这些额外的元数据有助于提供全面的背景信息，并提高支持质量。

消息传送元数据的优势包括：

• 更好的专员背景信息。专员依赖于其专员工作区视图中显示的正确背景信息。终端用户提供缺失的数据或数据可能容易出错。通过以编程方式提供相关信息，您可以减少询问信息的错误和时间。
• 改进版路由。企业依靠工单字段和标签中的信息将工单快速转接到正确的专员组。提供的数据越完整，转发工单到正确专员组的效率就越高。
• 为终端用户提供最佳体验。终端用户无需重新输入已有的客户端数据。
• 改进的自行程序工作流程。智能机器人生成器可以利用额外的数据提供更好的终端用户体验。
• 与 Web Widget Support SDK（支持工单字段和标签）的功能相同。

本文章包含以下主题：

• 消息传送元数据概览
• 配置消息传送元数据
• 添加对话字段
• 使用元数据 API
• 智能机器人生成器（旧版人工智能专员）

消息传送元数据概览

假设您有一家在线商店，并且一名终端用户正在查看一款特定的鞋子。在此页面上，有产品的 SKU、尺寸和颜色选项。当终端用户对此鞋有疑问时，有必要了解上述信息，以便专员确切知道终端用户对哪只鞋感兴趣。如果没有自定义工单字段，在线专员或人工智能专员在回答问题之前必须询问终端用户所有这些信息。

借助消息传送元数据，您可以以编程方式从页面获取此数据，或让终端用户填写表格或组合获取此数据。例如，您可以通过自定义工单字段API 从产品页面检索产品 SKU。终端用户可能已经选择了颜色和尺寸，因此人工智能专员可以使用自定义工单字段进行查询，并显示其默认值。终端用户可以更新这些值，也可以保留默认值。

这与在 人工智能专员标准回复 或 智能机器人生成器（旧版）中使用变量和自定义字段不同。使用消息传送元数据：

• 终端用户无需手动输入其访问页面上的数据。例如，如果终端用户在退货单表格上，且订单 ID 存在于该页面上，您可以以编程方式检索该号码，而不是让终端用户自行输入。
• 可以自动添加额外的背景信息来协助专员。例如，如果终端用户打开了购物车，您可以将对话字段“活跃的购物车”设置为 true。
• 您可以控制人工智能专员遵循的路径。例如，如果终端用户访问品牌 A 的页面，您可以在 字段中进行设置，使智能机器人遍历品牌 A 路径。

配置消息传送元数据

对话字段需要在管理中心进行配置，以便终端用户在创建字段时设置其值。在使用元数据 API 之前，对话标签不需要任何先决条件步骤。

使用消息传送元数据的第一步是确定要收集哪些数据以及如何使用这些数据。这完全取决于您的用例。当您的开发者在 Zendesk Web Widget和 SDK上以编程方式设置工单字段和标签值时，您必须充分理解终端用户的体验。

了解数据后，将执行以下步骤：

1. Zendesk 管理员创建一个自定义工单字段，并将字段名称和 ID 以及使用情况和所需收集的数据传递给开发者。
2. 开发者使用字段 ID 将值连接到该字段，以编码对元数据 API 的调用。
3. 数据在运行时在元数据 API 中以编程方式设置，并在下一个会话中可用。
4. 工单字段和标签数据会在工单创建时添加到 Support 工单。

注意：消息传送元数据仅应用于一张工单。如果创建的后续工单涉及相同对话，消息传送元数据将仅应用到第一张工单。

工单字段和标签元数据将在工单创建时应用到工单。例如，如果您将小组件配置为与在线专员（而不是人工智能专员）即时在线交谈，那么打开小组件会立即创建一张新工单，并且只有在创建工单之前已设置的工单字段和工单标签才会显示。已添加到其中。

工单关闭后，后端的消息传送元数据（例如工单）将重置为空的空状态。目前，消息传送元数据保留在客户端，将在未来版本中解决这个问题。

添加对话字段

使用任何Support模式的客户都可以创建对话字段，但您必须配置 消息传送 ，并正在使用消息传送Web Widget或 SDK 用于消息传送。

不支持系统工单字段，例如优先级字段。当从帮助中心访问它们时，它们显示在默认联系表格（和任何其他工单表格）中，但不会显示在Web Widget中。

注意：正则表达式、日期和 多选自 定义字段可通过元数据 API 进行设置，但不会在对话中显示。

您可以在 Zendesk专员工作区中查看工单信息或使用 Zendesk API 来验证对话字段是否已设置。例如，请参阅 使用消息传送元数据 。

添加对话字段

1. 在管理中心，单击侧栏中的对象和规则图标 ()，然后选择工单 > 字段。
2. 单击添加字段。
3. 选择字段类型，然后输入显示名称。
4. （可选）为自定义字段输入描述。这仅对管理员可见。
5. 在权限下，选择客户可编辑。
   注意：由于这些值可以通过客户端公开 API 调用进行设置，因此应始终将数据视为终端用户提供的数据。不建议对敏感数据使用这些 API。
6. 输入 向客户显示的标题。
7. 如果专员必须填写该字段以解决工单，请选择解决工单必填。此选项并非可用于所有字段类型。
   注意：专员合并工单时无需填写必填字段，因为合并的工单会绕过“已解决”，直接转到“已关闭”。如果业务规则将工单更改为“已解决”，此设置也会被绕过，因为解决工单的是系统进程，而不是专员。
8. 如果终端用户必须填写该字段以提交工单，请选择提交请求必填。
9. 根据您的字段类型，配置任何其他选项。
10. （可选）为自定义字段指定默认值。
    注意：下拉列表中的默认值仅适用于由专员通过Support界面创建的新工单，或由用户在显示工单表格的任何地方创建的新工单。如果您将现有的工单表格更改为带有默认选项下拉列表的表格，则默认选项不会显示，并显示为空白。
11. 单击 保存 ，或者要创建另一个自定义字段，单击下拉图标，选择 保存并添加另一个。
12. 保存您刚创建的字段 ID，因为您在使用元数据 API 时会需要它。

创建后，开发者可以使用 /api/v2/ticket_fields API 用于查看对话字段数据。响应示例如下：

[
 {
   url: "https://z3n-lhills.zendesk.com/api/v2/ticket_fields/10093547287955.json",
   id: 10093547287955,
   type: "integer",
   title: "Bike Order id",
   raw_title: "Bike Order id",
   description:
     "An API will populate this bike order id value",
   raw_description:
     "An API will populate this bike order id value",
   position: 9999,
   active: true,
   required: false,
   collapsed_for_agents: false,
   regexp_for_validation: "\A[-+]?\d+\z",
   title_in_portal: "Bike Order Id",
   raw_title_in_portal: "Bike Order Id",
   visible_in_portal: true,
   editable_in_portal: true,
   required_in_portal: false,
   tag: null,
   created_at: "2022-10-04T04:48:05Z",
   updated_at: "2022-10-04T04:48:05Z",
   removable: true,
   agent_description: "Order id from our bikes catalog",
 },
]

清除对话字段

有时您可能必须清除对话字段值。这取决于您的用例，当检索的数据不再有效时，就会进行这种操作。例如，假设您正在使用对话字段从终端用户的在线购物车收集数据。如果终端用户删除了其购物车中的所有商品，您收集的数据将不再有效，您可以清除这些对话字段值。

您可以使用 清除对话字段 clearConversationFields( ) API。

添加对话标签

标签是您可用于为工单和主题添加更多背景信息的词语或词语组合。您可以将工单标签应用到工单、用户和组织。例如，用“sales”或“about_sales”等工单标签，标记所有实际为销售查询的请求。然后您可以创建一个视图或报告来跟踪这些请求。

如需更多信息，请参阅 关于标签。

使用元数据 API

有关使用元数据 API 的示例，请参阅开发者文档中的 使用消息传送元数据 。

设置对话字段和工单标签

您可使用 设置对话字段值 setConversationFields API。例如，如果您的自定义工单字段ID 是 10093547287955，并将其值设置为字符串“548832222”，那么您可以调用：

zE('messenger:set', 'conversationFields', [{ id: '10093547287955', value: '548832222'}]);

如果您使用自定义下拉字段或任何将字段值与标签关联的字段，设置自定义字段值也会在生成的工单中设置自定义标签值。

	用于设置对话字段的客户端 API
Web Widget	zE('messenger:set', 'conversationFields', [{ id: '{field ID}', value: '{value}'}])
iOS	Zendesk.instance.setConversationFields(["{field ID}” : “{field ID}"])
Android	Zendesk.instance.setConversationFields(listOf( TicketField(id="{field ID}", value="{value}" )))
Unity	ZendeskSdk.Instance.Messaging.SetConversationFieldsAsync(Dictionary<string, object> ticketFields)

以下是 的响应范例 setConversationFields：

conversation: {
  ...
  metadata: {
        "zen:ticket_field": "30289064739483",
        ...
  },
}

注意：{field ID} 必须是字符串。否则将转为字符串。 {value} 必须是字符串、数字或布尔值。

您可使用 设置对话标签值 setConversationTags API。类似于 setConversationFields API 中，如果您设置了与可编辑自定义字段关联的自定义标签，则设置该自定义字段。如果自定义标签与私密（不可编辑）自定义字段关联，则将不设置该自定义字段。

	用于设置对话标签的客户端 API
Web Widget	zE('messenger:set', 'conversationTags', ['{tag value}', '{tag value}'])
iOS	Zendesk.instance.setConversationTags(["{tag value}", "{tag value}"])
Android	Zendesk.instance.setConversationTags(listOf("{tag value}", "{tag value}"))
Unity	ZendeskSdk.Instance.Messaging.SetConversationTags(List<string> tags)

以下是使用 的响应示例 setConversationTags：

conversation: {
  ...
  metadata: {
    "zen:ticket:tags": "likes-nike-trainers, frequent-shopper",
  },
}

清除对话字段和工单标签

当客户端背景信息更改时，您可以清除对话字段值和标签。例如，终端用户从产品页面转到您的主要商店登录页面。您从该产品页面收集的任何数据都已不再有效。

为此，请使用 ClearConversationFields 和 ClearConversationTags API。这将清除所有对话字段和工单标签。您无法清除单个字段或标签。

	用于清除对话字段和工单标签的客户端 API
Android	Zendesk.instance.clearConversationFields() Zendesk.instance.removeConversationTags()
Unity	ZendeskSdk.Instance.Messaging.ClearConversationFields() ZendeskSdk.Instance.Messaging.ClearConversationTags()

智能机器人生成器（旧版人工智能专员）

使用元数据 API 更新的字段将使用现有数据进行填充，并可由执行此步骤的终端用户进行编辑。如需了解更多信息，请参阅 了解答案工作流程步骤类型 和 创建自定义工单字段。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。