添加 Helpdesk 集成模板
Yeastar P 系列软件版 允许你创建和配置自定义集成模板,可通过 API 将 PBX 与 Helpdesk 系统无缝集成,实现数据交换和同步。本文介绍如何创建 Helpdesk 集成模板并完成必要的配置,以满足特定的集成需求。
使用要求和使用限制
- 使用要求
-
- PBX 服务器
- 固件版本:83.21.0.66 或更高版本。
- 订阅服务: CRM 集成。
- Helpdesk 系统:支持 REST API。
- PBX 服务器
- 使用限制
- 支持添加最多 10 个自定义 Helpdesk 集成模板。
前提条件
- 你具有基本的编码技能。
- 你已获得所需 Helpdesk 的 REST API 文档作为参考,并获取以下信息:
- 身份验证方式:确定所需 Helpdesk 使用的身份验证方法 (支持无身份验证、Basic
身份验证、OAuth2 身份验证和 Bearer Token 身份验证方法)。
若使用 OAuth2 或 Bearer Token 身份验证方法,需收集以下验证所需的 API 请求 URL 和数据规范。
功能 说明 授权 用于将用户重定向到授权页面进行身份验证和授权的URL。 获取访问令牌 用于获取访问令牌的 API 请求 URL。 刷新访问令牌 可选。用于获取刷新令牌的 API 请求 URL。 - API 请求信息:根据 Helpdesk 的功能和特定需求,收集了以下功能所需的 API
请求 URL 和数据规范。
API 请求 说明 搜索联系人 在 Helpdesk 中搜索联系人所需的 API 请求 URL。 获取用户 可选。获取 Helpdesk 中用户信息的 API 请求 URL。 注: 如需获取大量用户,还需要收集相关的分页参数 (如page、pageSize、limit或offset),以便分批获取用户信息。创建联系人 可选。向 Helpdesk 中添加新联系人的 API 请求 URL。 创建通话记录 可选。在 Helpdesk 中创建通话记录的 API 请求 URL。 创建新工单 可选。在 Helpdesk 中创建新工单的 API 请求 URL。
- 身份验证方式:确定所需 Helpdesk 使用的身份验证方法 (支持无身份验证、Basic
身份验证、OAuth2 身份验证和 Bearer Token 身份验证方法)。
操作步骤
- 登录 PBX 管理网页,进入 。
- 在 Helpdesk 列表中,点击 自定义。

你将进入模板管理页面。
- 点击 添加。
- 在弹出的窗口中,根据 Helpdesk 系统支持的功能和你的特定需求,完成以下模板配置。
- 点击 保存 以生成自定义 Helpdesk 集成模板。
完成常规设置
在 常规 栏,完成以下模板基本设置。

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

- 打开 用户关联 的开关。

- 在 获取用户 字段,填入用于获取 Helpdesk 用户列表的 Helpdesk API 请求
URL。
注:- 默认的 HTTP 请求方法是
GET,如果需要使用其他请求方法,可以稍后在模板中手动更改。有关此场景中模板参数的详细描述,请参见 XML 说明 - 用户关联场景.。 - 如有需要,用户在对接的 身份验证 过程中输入的值可以在请求中作为变量使用。
例如,https://www.api.example.com/v1/users?type=ActiveUsers - 默认的 HTTP 请求方法是
- 在 分页类型 下拉列表中,根据 Helpdesk API 的要求选择对应的分页模式。注: 对于需要发起多次请求的分页模式,单次同步操作最多支持 100 次查询请求。
模式 说明 禁用 PBX 仅发送一次查询请求,且无需使用分页参数。 当 API 接口单次可返回全部记录或不支持分页功能时,可使用此模式。
页码分页 PBX 基于页码和页面记录数量发送多次查询请求以获取用户数据。系统会自动递增后续请求中的页码,直至获取全部数据。 若选择此模式,需配置以下分页参数:

- 页码参数名称:填写接口请求中用于指定页码的参数名称。
- 页码起始值:设置开始查询数据的初始页码。
- 每页数量参数名称:填写接口请求中用于指定每页记录数量的参数名称。
- 每页数据条数:设置单页返回的最大记录数量。
偏移量分页 PBX 基于起始偏移量和记录数量限制发送多次查询请求以获取用户数据。系统会在后续请求中按记录数量限制值自动增加偏移量,直至获取全部数据。 若选择此模式,需配置以下分页参数:

- 偏移量参数名称:填写接口请求中用于指定分页起始位置的参数名称。
- 偏移量参数值:指定获取数据的起始位置。
例如,设为
1表示从第 1 条记录开始查询;设为100表示从第 100 条开始查询。 - 限制数量参数名称:填写接口请求中用于指定每页记录数量的参数名称。
- 限制数量参数值:设置单页返回的最大记录数量。
链接分页 PBX 通过使用接口响应中指向下一页数据的 URL 发送多次请求来获取用户数据,该过程将持续至所有数据获取完成。 若选择此模式,你需要在 下一页链接路径 中指定用于获取链接的 JSON 路径 (如
links.next)。
- 在 用户字段映射 栏,通过指定 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 系统的要求配置对接的验证方式。- 无身份验证
-
当 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。 - 配置 OAuth2 授权相关设置。

设置 说明 授权端点 输入 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}}。 - 可选: 配置令牌刷新设置。

设置 说明 令牌刷新请求方式 刷新令牌 API 的 HTTP 请求方法。 令牌刷新端点 输入用于刷新访问令牌的 API 请求 URL。 令牌刷新内容类型 选择刷新令牌请求的内容类型。 令牌刷新时间 (分钟) 指定系统自动刷新访问令牌的时间间隔 (单位:分钟)。 注:-
如果设置为 0,系统将不会自动刷新令牌。
-
如果留空,系统默认每 25 分钟自动刷新一次访问令牌。
令牌刷新请求体 刷新令牌 API 的请求体。 -
- 在 认证方式 下拉列表中,选择
OAuth2。
- Bearer Token 身份验证
- 该方法使用 Bearer Token 对请求进行身份验证,Token 通常通过授权流程 (如 OAuth2) 获取。每个发送到 Helpdesk
的 HTTP 请求都必须包含格式为
Authorization: Bearer {{.AccessToken}}的头字段,其中{{.AccessToken}}是 Helpdesk 提供的令牌值。
(可选) 配置请求头
- 最多支持添加 20 个自定义请求头。
- 这些自定义请求头不会应用于认证相关请求 (如获取或刷新访问令牌) 及自定义请求。
- 避免在此处定义
Authorization请求头,否则会覆盖由 Basic、OAuth2 或 Bearer Token 身份验证流程所获取的请求头的值。

- 在 头域 栏,点击 添加。
- 添加并配置请求头。注: 支持最多 20 个自定义请求头。
设置 说明 名称 请求头名称,例如 Content-Type(内容类型) 或Accept(期望的数据格式)。值 请求头的值,可以是具体的值,也可以是变量。 注: 认证方式 中定义的变量可用于此处。例如,如果设置了名为client_id的变量,可在此处的值中通过{{.client_id}}引用。描述 简要说明该请求头的作用或用途,便于参考。
(可选) 添加后续请求

- 在 栏,点击 添加。
- 配置后续请求的详细信息。
设置 说明 触发事件 指定触发此请求的事件。 请求方式 选择 API 的 HTTP 请求方法。 URL 输入该后续请求的端点 URL。 例如:https://api.example.com/rest-services/login头域 定义请求的 HTTP 头域 (JSON 格式)。 支持使用 {{.变量名}} 插入动态值。
例如:
{"Content-Type":"application/json", "X-Custom-Header": "{{.DynamicValue}}"}请求体 定义请求的数据负载 (JSON 格式)。 支持使用 {{.变量名}} 插入动态值。
例如:
{"lastName":"{{.LastName}}","ownerId":"{{.Id}}","phone":"{{.BusinessNumber}}"}响应字段路径 定义从后续请求响应中提取数据的 JSON 路径。 注: 使用半角逗号,分隔多个路径,如$.data.access_token, $.tokens[0].value。目标变量名 定义用于存储相应中获取的数据的系统变量名称 (可为现有变量或新变量)。 注:- 使用半角逗号
,分隔多个变量名,如token,refresh。 -
变量将按照 响应字段路径 中指定路径的顺序进行赋值。例如,第一个变量接收第一个路径中获取的值,第二个变量接收第二个路径中获取的值,依此类推。
- 使用半角逗号
配置联系人搜索以用于同步和来电弹屏
- 添加并配置联系人类型,并指定相应的 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。
- 从联系人字段信息获取
- 直接从联系人搜索响应中的特定字段提取联系人 URL。

- 在 联系人弹屏地址 下拉列表中,选择 从联系人字段信息获取。
- 在 获取URL的联系人字段 中,指定响应中相应字段的
JSON 路径。例如
data.#.contactUrl。
- 在 联系人字段映射 栏,映射 Helpdesk 字段到所需的 PBX 字段,通过指定 JSON 路径
(例如:
data.#(key=="value").field)来对应 Helpdesk 响应中的字段。注: 如果需要为一个字段获取多个变量,用逗号分隔变量。例如data.#(phone=="{{.Phone}}")#.street,data.#(mobile=="{{.Phone}}")#.street。- 映射以下必填字段:

- 联系人 ID:搜索到的联系人的 ID。例如
data.#.id。 - 名字:搜索到的联系人的名字。例如
data.#.first_name。
- 联系人 ID:搜索到的联系人的 ID。例如
- 根据需要启用并映射相应的 PBX 字段。注: 至少需要启用并映射一个电话号码。

- 如果现有 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}}" } } ] }
- 创建通话记录 URL(POST):输入用于在 Helpdesk 中创建通话记录的 API
请求
URL。
- 可选: 如需配置在集成中要提供的通话记录同步相关设置,勾选对应的选项以启用,并为每个设置项配置默认值。
设置项 说明 主题 若启用,集成中将提供对应配置项,可用于设置所有同步的通话记录的默认主题。 注:- 这些字段中设置的值也将作为可用的变量值。
- 有关支持的变量的更多信息,请参见 XML 说明 - 通话记录变量。
描述 若启用,集成中将提供对应配置项,可用于指定同步的通话记录的详情信息。 例如:Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}注:- 这些字段中设置的值也将作为可用的变量值。
- 有关支持的变量的更多信息,请参见 XML 说明 - 通话记录变量。
播放通话录音 若启用,集成中将提供对应配置项,可用于决定是否启用在 Helpdesk 系统中播放通话录音的功能。 未接听的坐席不记录未接来电 若启用,集成中将提供对应配置项,可用于决定队列和响铃组来电的记录是否仅同步至接听坐席的 Helpdesk 中,而对应通话的未接来电记录不会同步至其他未接听坐席的 Helpdesk。
(可选) 配置自动创建新工单

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




