添加 Helpdesk 集成模板

使用要求和使用限制

使用要求

PBX 服务器：PBX 服务器满足以下要求。
- 固件版本：83.18.0.102 或更高版本
- 订阅服务： CRM 集成
Helpdesk 系统：支持 REST API。

使用限制: 支持添加最多 10 个自定义 Helpdesk 集成模板。

前提条件

你具有基本的编码技能。

你已获得所需 Helpdesk 的 REST API 文档作为参考，并获取以下信息：

身份验证方式：确定所需 Helpdesk 使用的身份验证方法 (支持无身份验证、Basic 身份验证或 OAuth2 身份验证方法)。

API 请求信息：根据 Helpdesk 的功能和特定需求，收集了以下功能所需的 API 请求 URL 和数据规范。


API 请求	说明
搜索联系人	在 Helpdesk 中搜索联系人所需的 API 请求 URL。
获取用户	可选。获取 Helpdesk 中用户信息的 API 请求 URL。
创建联系人	可选。向 Helpdesk 中添加新联系人的 API 请求 URL。
创建通话记录	可选。在 Helpdesk 中创建通话记录的 API 请求 URL。
创建新工单	可选。在 Helpdesk 中创建新工单的 API 请求 URL。

操作步骤

登录 PBX 管理网页，进入应用对接 > Helpdesk集成。
在 Helpdesk 列表中，点击自定义。
你将进入模板管理页面。
点击添加。
在弹出的窗口中，根据 Helpdesk 系统支持的功能和你的特定需求，完成以下模板配置。
点击保存以生成自定义 Helpdesk 集成模板。

完成常规设置

在常规栏，完成以下模板基本设置。

Logo：上传 Helpdesk 的 logo。此 logo 将显示在集成页面的 Helpdesk 列表中。
注： Logo 文件需满足以下要求：
- 文件格式：PNG (推荐)、JPG 或 JPEG
- 建议分辨率：150 × 150
- 文件大小：不超过 500KB
Helpdesk 名称：填写 Helpdesk 的名称。
最大并发请求数：指定允许对 Helpdesk 发起的最大并发 HTTP 请求数。
备注：可选。输入 Helpdesk 模板的描述，该描述将在模板管理页面中显示。

(可选) 配置用户关联

在用户关联栏，启用并配置该功能,以支持将 Helpdesk 用户与 PBX 分机关联。

注：如果启用，在对接过程中会要求将 Helpdesk 用户与 PBX 分机进行关联，如下图所示。只有关联了分机的用户才能使用 Helpdesk 集成功能。

打开用户关联的开关。
在获取用户字段，填入用于获取 Helpdesk 用户列表的 Helpdesk API 请求 URL。
注：
- 默认的 HTTP 请求方法是 GET，如果需要使用其他请求方法，可以稍后在模板中手动更改。有关此场景中模板参数的详细描述，请参见 XML 说明 - 用户关联场景.。
- 如有需要，用户在对接的身份验证过程中输入的值可以在请求中作为变量使用。
例如，
```
https://www.api.example.com/v1/users?type=ActiveUsers
```

在用户字段映射栏，通过指定 Helpdesk 响应中相应字段的 JSON 路径 (例如 data.#(key=="value").field) 将 Helpdesk 字段映射到所需的 PBX 字段。

提示：关于更多路径语法信息，请参见 GJSON 路径语法说明。


PBX 字段	Description
用户唯一ID	用户的唯一 ID。例如，`users.#.id`。
名字	用户的名字，将显示在 Helpdesk 用户列表中。例如，`users.#.First_Name`。
姓氏	用户的姓氏，将显示在 Helpdesk 用户列表中。例如，`users.#.Last_Name`。
邮箱	用户的电子邮件，将显示在 Helpdesk 用户列表中，并可用于自动关联 Helpdesk 用户与 PBX 分机。例如，`users.#.Email`。

配置身份验证方式

在配置身份验证方式栏，基于 Helpdesk 系统的要求配置对接的验证方式。

无身份验证
Basic 身份验证
OAuth2 身份验证

无身份验证

当 Helpdesk 不要求身份验证，或仅需要相关变量进行集成时（例如用于请求的 API 密钥或用于实时数据传输的 webhook URL）使用此方法。

在认证方式下拉列表中，选择 None。

可选： 点击添加以添加自定义字段。这些字段将作为输入框显示在对接页面上，要求用户提供对接所需的信息。

注：

如果没有添加字段，Helpdesk 将直接完成对接，而无需用户进行任何额外的设置或输入。
最多支持 5 个自定义字段。
在对接认证过程中，用户输入的值可以在模板中作为变量值使用。


设置	说明
类型	选择自定义字段的类型。文本输入框：标准输入框，用户可以输入普通文本。密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。下拉选项框：可选列表，允许用户从预定义的选项中选择。
名称	为字段指定变量名称，模板中可根据需要引用此名称。
标题	为字段指定标题，将显示在输入框上方。
下拉选项值	如果类型设置为下拉选项框，在此字段中输入选项。注：使用半角逗号 `,` 分隔多个选项，例如 `option1,option2`。

Basic 身份验证

此方法使用凭证（如用户名和密码或 API 密钥）来认证请求。在这种情况下，发送到 Helpdesk 的每个 HTTP 请求将包含一个请求头字段，格式为

Authorization: Basic
                                    {{.basic_string}}

，其中 {{.basic_string}} 是在对接过程中指定的用户名和密码或 API 密钥的 Base64 编码组合。

在认证方式下拉列表中，选择 Basic。
在凭证类型下拉列表中，根据 Helpdesk 系统的要求，选择用户名和密码或 API 密钥。

配置用户输入凭证所需的字段，并根据需要添加其他自定义字段。

注：

最多支持 5 个字段。
在对接认证过程中，用户输入的值可以在模板中作为变量值使用。


设置	说明
类型	选择自定义字段的类型。文本输入框：标准输入框，用户可以输入普通文本。密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。下拉选项框：可选列表，允许用户从预定义的选项中选择。
名称	为字段指定变量名称，模板中可根据需要引用此名称。
标题	为字段指定标题，将显示在输入框上方。
下拉选项值	如果类型设置为下拉选项框，在此字段中输入选项。注：使用半角逗号 `,` 分隔多个选项，例如 `option1,option2`。

在 Base64 编码的凭证字段中，指定凭证变量的组合格式，用于生成 basic 认证字符串 (basic_string).
例如，{{.username:.password}} 或 {{.api_key:}}。

OAuth2 身份验证

此方法使用令牌授权访问，而无需暴露凭证。若使用此方式，则需要通过特定的 API 请求从 Helpdesk 获取必要的头部信息和其他参数 (如 OAuth 访问令牌)。

在认证方式下拉列表中，选择 OAuth2。

配置用户输入凭证所需的字段。

注：

如果需要更多字段，可稍后在模板中手动添加自定义字段。有关此场景中模板参数的详细描述，请参见 XML 说明 - 认证场景。
在对接认证过程中，用户输入的值可以在模板中作为变量值使用。


设置	说明
类型	选择自定义字段的类型。文本输入框：标准输入框，用户可以输入普通文本。密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。下拉选项框：可选列表，允许用户从预定义的选项中选择。
名称	为字段指定变量名称，模板中可根据需要引用此名称。
标题	为字段指定标题，将显示在输入框上方。
下拉选项值	如果类型设置为下拉选项框，在此字段中输入选项。注：使用半角逗号 `,` 分隔多个选项，例如 `option1,option2`。

在授权端点字段，输入 Helpdesk 的授权 URL，用户将在对接过程中被重定向到此 URL 进行授权。
例如，
```
https://www.api.example.com/auth/v2/authorize?client_id={{.client_id}}
```
在令牌端点字段，输入获取访问令牌和刷新令牌的 Helpdesk API 请求 URL。
例如，
```
https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
```
可选： 在访问范围（可选）字段，输入允许 PBX 访问的 Helpdesk 数据范围。
注：使用半角逗号 , 分隔多个字段。
例如，
```
contacts.read,contacts.write,calls.read,calls.write,user.read,user.write
```
可选： 如果 Helpdesk 系统使用查询参数进行身份验证而不是范围，你可以在附加查询字符串（可选）字段中添加查询参数。
例如，client_id={{.client_id}}&redirect_uri={{.redirect_uri}}。

保存模板设置后，Helpdesk 对接的认证页面中将自动展示 PBX 的认证信息，用户可使用此信息在 Helpdesk 系统中创建应用程序，并获取所需的授权信息，以便在 PBX 输入授权信息完成对接。

配置联系人搜索以用于同步和来电弹屏

在自动同步联系人栏，指定用户在配置集成功能时可选择的联系人类型，并指定搜索指定类型联系人所需的 API 请求。这些配置可用于实现 Helpdesk 联系人搜索、自动联系人同步和来电弹窗功能。

添加并配置联系人类型，并指定相应的 API 请求。
- 联系人类型：输入联系人类型的名称。
  这里设置的名称将作为自动联系人同步的选项，展示在用户配置集成功能时的界面上。
- 联系人匹配查询URL：输入用于根据特定条件搜索联系人的 Helpdesk API 请求 URL。
  在此场景中，可以使用以下变量作为条件参数的值：
  - 在对接认证过程中从用户输入获取的变量。
  - {{.Phone}}：与呼入或呼出通话相关的电话号码，或者用户输入用于联系人搜索的号码。
  例如，
```
https://www.api.example.com/v1/Contacts/search?criteria=((Phone:equals:{{.Phone}})or(Home_Phone:equals:{{.Phone}})or(Mobile:equals:{{.Phone}})or(Asst_Phone:equals:{{.Phone}}))
```
通过以下任一方式配置来电弹屏。
指定 URL 格式

通过指定 URL 格式来配置来电弹屏 URL，可使用变量动态构建 URL。
1. 在联系人弹屏地址下拉列表中，选择指定 URL 格式。
2. 在 URL 格式字段，输入联系人 URL 的表达式。
  在此场景中，可以使用以下变量，其中变量值可自动从 Helpdesk 联系人搜索结果中获取。
  
  在对接认证过程中从用户输入获取的变量。
  
  {{.ContactSyncType}}：查询到的联系人类型。
  
  {{.ContactId}}：联系人 ID。
  
  {{.CustomValue}}：在联系人字段映射栏映射的自定义字段。
  
  注：如果提供的变量不满足需求，可稍后手动编辑模板来定义其他自定义变量，并获取相应的值。有关此场景中模板参数的详细描述，请参见 XML 说明 - 获取额外变量。
  
  例如，
  {{.domain_url}}/{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}
从联系人字段信息获取
直接从联系人搜索响应中的特定字段提取联系人 URL。
1. 在联系人弹屏地址下拉列表中，选择从联系人字段信息获取。
2. 在获取URL的联系人字段中，指定响应中相应字段的 JSON 路径。例如 data.#.contactUrl。
在联系人字段映射栏，映射 Helpdesk 字段到所需的 PBX 字段，通过指定 JSON 路径 (例如：data.#(key=="value").field )来对应 Helpdesk 响应中的字段。
注：如果需要为一个字段获取多个变量，用逗号分隔变量。例如 data.#(phone=="{{.Phone}}")#.street,data.#(mobile=="{{.Phone}}")#.street。
1. 映射以下必填字段：
  - 联系人 ID：搜索到的联系人的 ID。例如 data.#.id。
  - 名字：搜索到的联系人的名字。例如 data.#.first_name。
2. 根据需要启用并映射相应的 PBX 字段。
  注：至少需要启用并映射一个电话号码。
3. 如果现有 PBX 字段不满足需求，可以启用自定义值并映射所需的响应字段。该字段可以在模板中通过变量名 {{.CustomValue}} 引用。
  注：此变量专门用于构建联系人 URL，不会出现在 PBX 联系人详细信息中。

(可选) 配置新联系人创建

若要在来电者的号码与现有的 Helpdesk 联系人不匹配时，在 Helpdesk 中创建一个新联系人，启用并配置创建新联系人。

打开创建新联系人的开关。
添加并配置用户在配置集成功能时可选择的联系人类型。
- 联系人类型：指定联系人类型。
- 创建联系人URL (POST)：输入用于创建新联系人的 Helpdesk API 请求 URL。
  例如，
```
https://www.api.example.com/v1/Contacts
```
- 创建联系人请求体：输入请求体 (JSON 格式)，用于传递联系人信息。
  在此场景中，可以使用以下变量：
  - 在对接认证过程中从用户输入获取的变量。
  - {{.LastName}}：必填。联系人的姓氏。
  - {{.FirstName}}：必填。联系人的名字。
  - {{.BusinessNumber}}：必填。联系人的电话号码。
  注：如果提供的变量不满足需求，可稍后手动编辑模板来定义其他自定义变量，并获取相应的值。有关此场景中模板参数的详细描述，请参见 XML 说明 - 获取额外变量。
  例如，
```
{
  "data": [
    {
      "Last_Name": "{{.LastName}}",
      "First_Name": "{{.FirstName}}",
      "Phone": "{{.BusinessNumber}}"
    }
  ]
}
```

(可选) 配置通话记录同步

若要启用通话记录功能，以自动将通话活动和详细信息记录到 Helpdesk 中，启用并配置通话记录同步。

打开通话记录同步的开关。

配置创建通话记录的 API 请求和请求体。

创建通话记录 URL（POST）：输入用于在 Helpdesk 中创建通话记录的 API 请求 URL。
例如，
```
https://www.api.example.com/v2/Calls
```

创建通话记录请求数据：输入请求体 (JSON 格式)，用于传递通话详情。

注：有关请求体中支持的变量，请参见 XML 说明 - 通话记录变量。

例如，

{
  "data": [
    {
      "{{.Owner}}{{.WhoModule}}": {
        "Description": "{{.Description}}",
        "Voice_Recording__s": "{{.RecordPath}}",
        "Call_Start_Time": "{{TimeFormat .StartTimeUnix 'yyyy-MM-ddTHH:mm:ss-z' '1'}}",
        "Subject": "{{.Subject}}",
        "Call_Type": "Inbound",
        "Call_Result": "{{.Call_Log_Status}}",
        "Call_Duration": "{{.Talk_Duration_Sec}}"
      }
    }
  ]
}

若要允许用户自定义通话记录的特定设置，包括日志详细信息和通话录音播放选项，启用以下选项并根据需要配置默认值。
注：
- 这些字段中设置的值也将作为可用的变量值。
- 有关支持的变量的更多信息，请参见 XML 说明 - 通话记录变量。
- 主题：若启用，输入通话记录的默认主题。所有通话记录将使用指定的主题创建。
- 描述：若启用，指定通话记录的详细信息。
  例如，
```
Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
```
- 播放通话录音：决定是否允许用户配置在 Helpdesk 中播放通话录音的选项。

(可选) 配置自动创建新工单

如果你希望基于通话自动创建新工单，请启用并配置自动创建工单。

注：若后续使用中设置为在通话开始前 (即电话响铃时) 创建工单，创建的工单可能会缺少一些信息。在这种情况下，你需要手动编辑模板以更新已创建工单的信息。有关更多信息，请参见 XML 描述 - 扩展配置。

打开自动创建工单的开关。
配置创建新工单的 API 请求和请求体。
- 创建新工单 URL（POST）：输入用于在 Helpdesk 中创建工单的 API 请求 URL。
  例如，
```
https://www.api.example.com/api/v1/tickets
```
- 创建新工单请求体：输入请求体 (JSON 格式)，用于传递工单详情。
  
  注：有关请求体中支持的变量，请参见 XML 说明 - 新工单创建变量。
  例如，
```
{
   "subject":"{{.Subject}}",
   "contactId":"{{.ContactId}}",
   "phone":"{{.ContactNumber}}",
   "description":"{{.Description}}"
}
```
若要允许用户自定义新工单的主题和描述，启用以下选项并根据需要配置默认值。
注：
- 这些字段中设置的值也将作为可用的变量值。
- 有关支持的变量的更多信息，请参见 XML 说明 - 新工单创建变量。
- 主题：若启用，输入工单的默认主题。
  例如，
```
{{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}
```
- 描述：若启用，指定工单的详细信息。
  例如，
```
{{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
```