集成模板 XML 说明

Yeastar P 系列软件版 允许你创建 CRM / Helpdesk 集成模板，在模板中定义必要的设置，包括特定的 API 端点、数据字段和集成所需的功能场景。本文提供了 XML 模板中设置元素的详细说明。

模板约定

模板遵循 XML 1.1 标准规范。本节描述了模板的语法和约定。

变量

模板支持使用变量来处理动态数据。当模板执行时，模板中引用的变量将被替换为它们各自的值。

下表展示了集成模板中变量值的来源，以及如何在模板中引用这些变量。

项目 说明
来源 模板中的变量值可以从以下来源获取：
  • PBX 系统中的预定义变量
  • 用户在对接过程中输入的参数值
  • 从请求响应中获取的值

    可通过指定 JSON 路径从返回的响应体中获取特定值，如下示例所示：

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

    • 要获取某个响应值，可以使用以下语法：

      <Output Name="UserUniqueId" Path="data.#.id"></Output>

    • 若要获取满足特定条件的值，可以使用以下语法

      <Output Name="BusinessNumber2" Path="identities.#(type=="phone_number")#|1.value"></Output>
引用格式 模板中的变量遵循 Go 语言的 text/template 语法规范，基本用法如下：
  • 标准变量：{{.varname}}
  • 条件判断：{{ if .varname }} Welcome, member! {{ else }} Please sign up. {{ end }}
  • 结合变量的函数调用：{{ Capitalize .varname }}
函数
集成模板支持以下函数，可以与变量一起使用，从而动态地操作或格式化变量值。
函数 说明
TimeFormat 该函数用于自定义时间戳的格式。

格式：{{ TimeFormat Timestamp_variable "format_string" "Whether_to_convert_to_UTC_time" }}

示例：{{ TimeFormat .StartTimeUnix "yyyy-MM-ddTHH:mm:ss.000Zz" "1" }}

假设 {{.StartTimeUnix}} 的值为 1672531199，则调用函数后最终输出为 2023-01-01T00:59:59.000Z。
ToMillis 该函数用于将秒时间戳转换为毫秒时间戳。

格式: {{ ToMillis Timestamp_variable}}

示例：{{ ToMillis .StartTimeUnix }}

假设 {{.StartTimeUnix}} 的值为 1672531199，，则调用函数后最终输出为 1672531199000。
Capitalize 该函数用于将字符串的首字母大写。

格式：{{ Capitalize variable_string}}

示例：{{ Capitalize .variable_string }}

假设 {{.variable_string}} 的值为 hello world，则调用函数后最终输出为 Hello world.
UrlEncode 该函数用于对字符串进行 URL 编码。

格式：{{ UrlEncode .variable }}

示例：{{ UrlEncode .variable}}

假设 {{.variable}} 的值为 hello world!，则调用函数后最终输出为 hello%20world%21.
元素
模板提供以下主要元素，以定义集成交互，确保模板能够与第三方系统无缝连接并根据集成要求处理数据。
以下示例展示了模板的主要结构。
<Information>
  <Scenarios>
    <Scenario Id="1" Type="REST">
      <Parameters>
        <Parameter Name="example" Value="example"></Parameter>
        ...
      </Parameters>
      <Requests>
        <Request Name="ExampleRequest" Method="GET" URL="https://api.example.com/getuser">
           <Outputs>
            <Output Name="ContactId" Path="data.#.id" Type="string"></Output>
            ...
          </Outputs>
        </Request>
      </Requests>
    </Scenario>
  </Scenarios>
</Information>
主要元素 说明
Information

<Information> 元素是此 XML 模板的根元素，通过其属性提供基本信息和配置概览。它还包含 <Scenarios> 子元素，用于描述模板的功能场景和集成功能。

有关属性的详细信息，请参见 模板属性。
Scenarios

<Scenarios> 元素提供了一组 <Scenario> 子元素，其包含了更深层次的子元素，如 <Parameters>、<Requests> 和 <Outputs>，用于描述集成的具体功能场景。PBX 将加载配置的场景并执行场景中定义的 HTTP 请求或操作。

集成模板支持以下场景：

注： 如果指定的场景无法满足您的需求，您可以手动编辑模板配置以进行补充使用。更多信息，请参见 扩展配置。
Parameters <Parameters> 元素用于定义与场景或请求相关的参数集合。这些参数通常包括执行场景所需的动态值或配置设置，可以在请求的 URL、主体或头部中传递。
Requests <Requests> 元素提供了一组请求，用于在指定场景中实现特定功能。
Outputs <Outputs> 元素包含一组 <Output> 元素，定义从 API 响应中提取的数据。

模板属性

<Information> 元素提供模板的属性信息，包括基本模板信息和配置概览，具体属性如下：

属性 说明
Provider 模板类型，固定值为 crm 或 helpdesk。
Name 模板名称。
Key 模板的唯一标识符。
Logo Logo 文件名称。
Remark 模板的描述或备注。
Version 模板版本号，例如：1.0.0。
AuthType 集成使用的身份验证方法。
  • none：无身份验证。
  • basic：Basic 身份验证。
  • oauth2：OAuth2 身份验证。
MaxConcurrentRequest 允许向 CRM/Helpdesk 发送的最大并发 HTTP 请求数量。
UserAssociation 是否启用用户关联功能。
  • 0：禁用。
  • 1：启用。
CallJournal 是否启用通话日志同步功能。
  • 0：禁用。
  • 1：启用。
CreateNewContact 是否启用新建联系人功能。
  • 0：禁用。
  • 1：启用。
CreateNewTicket 是否启用自动创建新工单功能。
  • 0：禁用。
  • 1：启用。

身份验证场景

此场景定义了 CRM/Helpdesk 系统使用的身份验证方法。该场景的结构及其关键元素如下所示：

 <Scenario Id="AuthMethod" Type="AUTH">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="AuthMethod" Value="oauth2"></Parameter>
    <Parameter Name="AuthEndPoint" Value="https://api.example.com/oauth/v2/auth?client_id={{.client_id}}"></Parameter>
    <Parameter Name="TokenEndPoint" Value="https://api.example.com/oauth/v2/token?client_id={{.client_id}}&amp;client_secret={{.client_secret}}"></Parameter>
    <Parameter Name="AdditionalQueryString"></Parameter>
    <Parameter Name="Scope" Value="contacts.read,contacts.write,calls.read,calls.write,user.read,user.write"></Parameter>
    <Parameter Name="CredentialType"></Parameter>
    <Parameter Name="Base64EncodedCredential"></Parameter>
    <Parameter Father="CustomFieldList" Name="client_id" Editor="password" Title="Client ID"></Parameter>
    <Parameter Father="CustomFieldList" Name="client_secret" Editor="password" Title="Client Secret"></Parameter>
   </Parameters>
   <Requests></Requests>
  </Scenario>

下面是对场景中具体元素的详细解释。

Scenario 元素
<Scenario> 元素具有以下属性：
属性 说明
Id 场景的唯一标识符，值应固定为 AuthMethod。
Type 场景的类型，该场景的值为 AUTH，表示该场景将执行身份验证操作。
Parameter 元素
属性 说明
Name 身份验证参数 的名称。
Value 身份验证参数 的值。
Father 父参数的名称 (应固定为 CustomFieldList)，用于组织自定义输入字段，允许用户在配置 UI 中展示的自定义输入字段中输入相关参数值。
注： 自定义输入字段中捕获的变量可供模板中的所有后续请求使用。
  • Name：自定义输入字段的变量名称，可用于在模板中引用变量。
  • Editor：自定义输入字段的类型。

    有效值：

    • string：标准输入框，用户可以输入普通文本。
    • password：专用的输入框，用于敏感信息，输入内容会被隐藏。
    • list：可选列表，允许用户从预定义的选项中选择。
  • Title：自定义输入字段的标题。
  • Value：预定义的选项列表。
身份验证参数
参数 说明
AuthMethod 身份验证方法。

有效值：

  • none：CRM 不需要身份验证时使用此方法，或者当 CRM/Helpdesk 只需要相关变量进行数据交换时使用，例如 API 密钥或 webhook URL。
  • basic：此方法通过凭证进行请求身份验证，例如用户名和密码或 API 密钥。这些凭证将被 base64 编码成一个基本字符串，并包含在每个 HTTP 请求的头部字段中，发送给 CRM/Helpdesk。
  • oauth2：此方法使用令牌来授予访问权限，而无需暴露凭证。它需要通过特定的 API 请求从 CRM/Helpdesk 获取必要的头部和其他参数 (例如 OAuth 访问令牌)。
AuthEndPoint CRM/Helpdesk 的授权 URL，用于启动授权过程。
注： 此参数仅适用于 oauth2 身份验证方法。
TokenEndPoint 获取访问令牌和刷新令牌的 CRM/Helpdesk API 请求 URL。
注： 此参数仅适用于 oauth2 身份验证方法。
AdditionalQueryString 如果 CRM/Helpdesk 使用查询参数进行身份验证而非范围，可以在此参数中添加查询变量。
注： 此参数仅适用于 oauth2 身份验证方法。
Scope 指定 PBX 允许访问的 CRM/Helpdesk 数据范围。
注： 此参数仅适用于 oauth2 身份验证方法。
CredentialType 身份验证凭证的类型。
注： 此参数仅适用于 basic 身份验证方法。
有效值：
  • username_password
  • api_key
Base64EncodedCredential 定义凭证变量的组合格式，用于生成 Basic 身份验证字符串。
注： 此参数仅适用于 basic 身份验证方法。

例如，{{.username:.password}} 或 {{.api_key:}}。

用户关联场景

此场景用于从 CRM/Helpdesk 系统中搜索并获取用户列表。该场景的结构及其关键元素如下所示：

<Scenario Id="UserAssociation" Type="REST">
   <Parameters></Parameters>
   <Requests>
    <Request Name="UserAssociation" Method="GET" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/v1/users?type=ActiveUsers">
     <Parameters></Parameters>
     <Outputs>
      <Output Name="UserUniqueId" Path="users.#.id" Type=""></Output>
      <Output Name="FirstName" Path="users.#.First_Name" Type=""></Output>
      <Output Name="LastName" Path="users.#.Last_Name" Type=""></Output>
      <Output Name="Email" Path="users.#.Email" Type=""></Output>
     </Outputs>
    </Request>
   </Requests>
</Scenario>

以下是该场景中具体元素的详细说明。

Scenario 元素
<Scenario> 元素具有以下属性：
属性 说明
Id 场景的唯一标识符，值应固定为 UserAssociation。
Type 场景的类型，值为 REST，表示该场景将通过 HTTP 请求执行 REST API。
Request 元素
<Request> 元素具有以下属性：
属性 说明
Name 请求的名称，用于标识场景中的请求。值应固定为 UserAssociation。
Method 用于请求的 HTTP 方法，在此场景中，默认 HTTP 方法为 GET，如有需要可自行修改。
ResponseType 请求的预期响应格式，应为 JSON 格式（application/json）。
RequestEncoding 请求的编码方式，在此场景中，值为空。
URLFormat API 端点的请求 URL。
Output 元素
<Output> 元素具有以下属性：
属性 说明
Name 输出变量的名称，表示 需要从响应数据中获取的变量。
Path 在 API 响应中所需数据字段的位置，使用路径语法访问嵌套数据。例如：users.#.id。
Type 输出变量的数据类型，在此模板中，类型固定为 string。
变量
变量 说明
UserUniqueId CRM/Helpdesk 用户的唯一 ID。
FirstName 用户的名字。
LastName 用户的姓氏。
Email 用户的邮箱。

自动联系人同步场景

此场景用于在 CRM/Helpdesk 系统中搜索联系人，且返回的信息可用于实现 CRM 联系人搜索、自动联系人同步和来电弹屏。该场景的结构及其关键元素如下所示：

  <Scenario Id="SyncContactAuto" Type="REST">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="ContactUrlType" Value="retrieve_from_contact"></Parameter>
    <Parameter Name="URLFormat"></Parameter>
    <Parameter Name="ContactFieldForUri" Value="data.#.contactUrl"></Parameter>
    <Parameter Name="ContactsIdEnable" Value="1"></Parameter>
    <Parameter Name="FirstNameEnable" Value="1"></Parameter>
    <Parameter Name="BusinessNumberEnable" Value="1"></Parameter>
    <Parameter Name="CustomValueEnable" Value="0"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="Contacts" Method="GET" ResponseType="application/json" RequestEncoding="" URLFormat="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}}))">
     <Parameters></Parameters>
     <Outputs>
      <Output Name="ContactsId" Path="data.#.id" Type=""></Output>
      <Output Name="FirstName" Path="data.#.First_Name" Type=""></Output>
      <Output Name="BusinessNumber" Path="data.#.Phone" Type=""></Output>
      ...
      <Output Name="CustomValue" Path="data.#.Owner" Type=""></Output>
     </Outputs>
    </Request>
   </Requests>
  </Scenario>

以下是该场景中具体元素的详细说明。

Scenario 元素
<Scenario> 元素具有以下属性：：
属性 说明
Id 场景的唯一标识符，值应固定为 SyncContactAuto。
Type 场景的类型，值为 REST，表示该场景将通过 HTTP 请求执行 REST API。
Parameter 元素
<Parameter> 元素具有以下属性：
属性 说明
Name 场景中 配置项 的名称。
Value 配置项的值。
配置项
设置 说明
ContactUrlType 指定获取联系人 URL 的方式，用于来电弹屏。

有效值：

  • specify_url_format：通过指定 URL 格式来配置来电弹屏 URL。
  • retrieve_from_contact：从联系人搜索响应的特定字段中获取联系人 URL。
URLFormat 联系人 URL 的表达式。
以下变量可以用来构建 URL。
  • 从 身份验证过程 的自定义字段输入中获取的变量。
  • ContactSyncType：联系人类型，来自于用来搜索特定类型联系人的请求的名称。
  • ContactId：联系人 ID，从本场景的响应数据中获取。
  • CustomValue：自定义字段，从本场景的响应数据中获取。
例如，{{.crm_url}}/crm/{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}.
注： 如果提供的变量无法满足你的需求，你可以定义额外的请求并获取所需的变量值。有关更多信息，请参见 扩展配置 - 获取其他变量。
ContactFieldForUri 用于从响应数据中获取联系人 URL 对应字段的 JSON 路径。

例如 .data.#.contactUrl。
ContactsIdEnable 是否从响应数据中获取联系人的 ID。此配置项的值应设置为 1。
FirstNameEnable 是否从响应数据中获取联系人的名称。此配置项的值应设置为 1。
LastNameEnable 是否从响应数据中获取联系人的姓氏。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
CompanyEnable 是否从响应数据中获取联系人的公司信息。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
EmailEnable 是否从响应数据中获取联系人的邮箱。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
BusinessNumberEnable 是否从响应数据中获取联系人的业务电话号码。
注： 至少需要获取一个电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
BusinessNumber2Enable 是否从响应数据中获取联系人的第二个业务电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
BusinessFaxNumberEnable 是否从响应数据中获取联系人的业务传真号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
MobileNumberEnable 是否从响应数据中获取联系人的手机电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
MobileNumber2Enable 是否从响应数据中获取联系人的第二个手机电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
HomeNumberEnable 是否从响应数据中获取联系人的家庭电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
HomeNumber2Enable 是否从响应数据中获取联系人的第二个家庭电话号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
HomeFaxNumberEnable 是否从响应数据中获取联系人的家庭传真号码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
OtherNumberEnable 是否从响应数据中获取联系人的其他电话号码（除业务电话和家庭电话外）。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
ZipCodeEnable 是否从响应数据中获取联系人的邮政编码。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
StreetEnable 是否从响应数据中获取联系人的街道地址。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
CityEnable 是否从响应数据中获取联系人的城市。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
StateEnable 是否从响应数据中获取联系人的州 / 省。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
CountryEnable 是否从响应数据中获取联系人的国家。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
RemarkEnable 是否从响应数据中获取联系人的备注。
有效值：
  • 0：不获取该数据。
  • 1：需要获取该数据。
CustomValueEnable 是否启用用于构建联系人 URL 的自定义变量。
有效值：
  • 0：禁用。
  • 1：启用。
Request 元素
<Request> 元素具有以下属性：
属性 说明
Name 请求的名称，用于标识场景中的请求。
注： 此处的值应为实际要搜索的联系人类型，并将作为 ContactSyncType 变量引用。
Method 用于请求的 HTTP 方法，在此场景中，默认 HTTP 方法为 GET，如有需要可自行修改。
ResponseType 请求的预期响应格式，应为 JSON 格式（application/json）。
RequestEncoding 请求的编码方式，在此场景中，值为空。
URLFormat API 端点的请求 URL。
Output 元素
<Output> 元素具有以下属性：
属性 说明
Name 输出变量的名称，表示需要从响应数据中获取的变量。
Path 在 API 响应中所需数据字段的位置，使用路径语法访问嵌套数据。例如：users.#.id。
Type 输出变量的数据类型，在此模板中，类型固定为 string。
变量
变量 说明
ContactsId (必需) 联系人的唯一 ID。
FirstName (必需) 联系人的名字。
LastName 联系人的姓氏。
Company 联系人的公司信息。
Email 联系人的邮箱。
BusinessNumber 联系人的业务电话号码。
注： 至少需要启用并获取一个电话号码。
BusinessNumber2 联系人的第二个业务电话号码。
BusinessFaxNumber 联系人的业务传真号码。
MobileNumber 联系人的手机号码。
MobileNumber2 联系人的的第二个手机号码。
HomeNumber 联系人的家庭电话号码。
HomeNumber2 联系人的第二个家庭电话号码。
HomeFaxNumber 联系人的家庭传真号码。
OtherNumber 联系人的其他电话号码。
ZipCode 邮政编码。
Street 街道地址。
City 城市。
State 州/省。
Country 国家。
Remark 备注。
CustomValue 用于构建联系人 URL 的自定义变量。

自动联系人创建场景

此场景用于在来电者的号码与现有联系人不匹配时，在 CRM/Helpdesk 系统中创建一个新的联系人。该场景的结构及其关键元素如下所示：

 <Scenario Id="CreateNewContact" Type="REST">
   
   <Parameters></Parameters>
   <Requests>
    <Request Name="Contacts" Method="POST" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/v1/Contacts">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"data": [{"Last_Name":"{{.LastName}}","First_Name":"{{.FirstName}}","Phone":"{{.BusinessNumber}}";}]}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
  </Scenario>

以下是场景中各个元素的详细说明：

Scenario 元素
<Scenario> 元素具有以下属性：
属性 说明
Id 场景的唯一标识符，值应固定为 CreateNewContact。
Type 场景的类型，值为 REST，表示该场景将通过 HTTP 请求执行 REST API。
Request 元素
<Request> 元素具有以下属性：
属性 说明
Name 请求的名称，用于标识场景中的请求。
注： 该值应为要在 CRM / Helpdesk 系统中创建的特定联系人类型的实际名称。
Method 请求使用的 HTTP 方法。此场景中的 HTTP 方法为 POST。
ResponseType 请求的预期响应格式，应为 JSON 格式（application/json）。
RequestEncoding 请求的编码方式，在此场景中，值为空。
URLFormat API 端点的请求 URL。
Parameter 元素
<Parameter> 元素嵌套在 <Request> 元素中，定义了请求体中包含的参数。
属性 说明
Name 参数的名称，应固定为 Data。
Type 参数的类型，应固定为 Body。
Value 定义了通过请求体传递的必需参数，包含在 data 结构中。参数值可以从 PBX 系统中预定义的变量中获取。
注： 格式应遵循 XML 参数标准。例如，如果需要换行符，必须使用转义字符 &#xA; 来表示换行符。
变量
注： 此处只列出必需的变量。如果需要其他参数和变量，请参见 扩展配置 - 获取额外变量。
变量 说明
{{.LastName}} 联系人的姓氏。
{{.FirstName}} 联系人的名字。
{{.BusinessNumber}} 联系人的电话号码。

自动工单创建场景 (仅适用于 Helpdesk 系统)

此场景用于在 Helpdesk 系统中创建一个新的工单。该场景的结构及其关键元素如下所示：

<Scenario Id="CreateNewTicket" Type="REST" >
   <Presets></Presets>
   <Parameters>
    <Parameter Name="EnableSubject" Value="1"></Parameter>
    <Parameter Name="Subject" Value="{{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}"></Parameter>
    <Parameter Name="EnableDescription" Value="1"></Parameter>
    <Parameter Name="Description" Value="{{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="CreateNewTicket" Method="POST" Weight="0" ResponseType="application/json" RequestEncoding="" URLFormat="https://{{.domain}}/api/v1/tickets">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"subject":"{{.Subject}}","contactId":"{{.ContactId}}","phone":"{{.ContactNumber}}","description":"{{.Description}}";}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
</Scenario>

以下是场景中各个元素的详细说明：

Scenario 元素
<Scenario> 元素具有以下属性：
属性 说明
Id 场景的唯一标识符，值应固定为 CreateNewTicket。
Type 场景的类型，值为 REST，表示该场景将通过 HTTP 请求执行 REST API。
Parameter 元素
属性 说明
Name 场景中使用的 配置项 名称。
Value 配置项的值。
配置项
设置 说明
EnableSubject 是否允许用户自定义工单的主题。
有效值：
  • 0：禁用。
  • 1：启用。
Subject 指定主题的默认值。
注： 默认值为 {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}。关于更多支持的变量，请参见 参数变量列表。
EnableDescription 是否允许用户自定义工单的描述。
有效值：
  • 0：禁用。
  • 1：启用。
Description 指定描述的默认值。
注： 默认值为 {{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}。关于更多支持的变量，请参见 参数变量列表。
Request 元素
<Request> 元素具有以下属性：
属性 说明
Name 请求的名称，用于标识场景中的请求。值应固定为 CreateNewTicket。
Method 请求使用的 HTTP 方法。此场景中的 HTTP 方法为 POST。
ResponseType 请求的预期响应格式，应为 JSON 格式（application/json）。
RequestEncoding 请求的编码方式，在此场景中，值为空。
URLFormat API 端点的请求 URL。
Parameter 元素
<Parameter> 元素嵌套在 <Request> 元素中，定义了请求体中包含的参数。
属性 说明
Name 参数的名称，应固定为 Data。
Type 参数的类型，应固定为 Body。
Value 定义了通过请求体传递的必需参数。参数值可以从 PBX 系统中预定义的变量中获取。
注： 格式应遵循 XML 参数标准。例如，如果需要换行符，必须使用转义字符 &#xA; 来表示换行符。
变量
注： 此处只列出必需的变量。如果需要其他参数和变量，请参见 扩展配置 - 获取额外变量。
变量 说明
从 AuthMethod 场景获取的变量 从用户在身份验证过程中输入捕获的变量。
{{.Subject}} 工单的主题。

该变量值来自 Subject 参数。
{{.Description}} 工单的描述。

该变量值来自 Description 参数。
{{.Time}} 来电的时间 (跟随PBX 系统的时间格式)。
{{.StartTimeUnix }} 通话开始时间的 Unix 时间戳
{{.EndTimeUnix}} 通话结束时间的 Unix 时间戳。
{{.Call_From}} 主叫的名称和号码。

格式：主叫名称 <主叫号码>。
{{.CallerName}} 主叫的名称。
{{.CallerNumber}} 主叫的号码。
{{.CalleeName}} 被叫的名称。
{{.CalleeNumber}} 被叫的号码。
{{.CrmId}} 与 PBX 分机绑定的 CRM / Helpdesk 用户的唯一 ID。
{{.ExtensionFirstName}} 分机用户的名称。
{{.ExtensionLastName}} 分机用户的姓氏。
{{.ExtensionEmail}} 分机用户的邮箱。
{{.ContactSyncType}} 联系人的类型。
{{.ContactNumber}} 联系人的号码。
{{.ContactId}} 联系人的唯一 ID。
{{.TicketId}} 基于通话创建的工单的唯一 ID。
注： 要获取工单 ID，需要在模板中进行额外配置。有关更多信息，请参见 扩展配置 - 获取工单 ID。
{{.CallDuration}} 通话持续的时间 (从开始到结束的时间)。
{{.Talk_Duration}} 来电接通到通话结束的时间 (格式：hh:mm:ss)。
{{.Talk_Duration_Sec}} 来电接通到通话结束的时间 (以秒为单位)。
{{.Communication_Type}} 通话的方向。
可能取值：
  • Inbound：外线呼入。
  • Outbound：外线呼出。
{{.Call_Status}} 通话的处理状态。
可能取值：
  • Missed：未接来电。
  • Completed：已成功接通并完成的来电。
{{.Call_Log_Status}} 通话的状态。

可能取值：

  • Missed Call：未接来电。
  • Outgoing Call：外线呼出。
  • Incoming Call：外线呼入。
  • Voicemail：未接来电并转入语音信箱。
{{.CallDisposition}} 通话的处理结果。

可能取值：

  • MISSED：未接来电。
  • VOICEMAIL：转入语音信箱。
  • BUSY：对方忙。
  • ANSWERED：已接通来电。
  • NO ANSWER：未接来电。

通话记录同步场景

该场景用于将绑定用户的通话活动同步到 CRM / Helpdesk 中的场景。以下是该场景的结构及其关键元素的详细说明。

  <Scenario Id="CallJournal" Type="REST">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="EnableSubject" Value="1"></Parameter>
    <Parameter Name="Subject" Value="Extension Call"></Parameter>
    <Parameter Name="EnableDescription" Value="1"></Parameter>
    <Parameter Name="Description" Value="Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}"></Parameter>
    <Parameter Name="EnablePlayCallRecording" Value="1"></Parameter>
    <Parameter Name="PlayCallRecording" Value="0"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="CallJournal" Method="POST" Weight="0" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/crm/v2/Calls">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"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}}"}}]}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
  </Scenario>

以下是场景中各个元素的详细说明：

Scenario 元素
<Scenario> 元素具有以下属性：
属性 说明
Id 场景的唯一标识符，值应固定为 CallJournal。
Type 场景的类型，值为 REST，表示该场景将通过 HTTP 请求执行 REST API。
Parameter 元素
属性 说明
Name 场景中 配置项 的名称。
Value 配置项的值。
配置项
设置 说明
EnableSubject 是否允许用户自定义通话记录的主题。
有效值：
  • 0：禁用。
  • 1：启用。
Subject 指定默认的主题。
注： 默认值为 Extension Call，你也可以使用支持的变量来指定主题。
EnableDescription 是否允许用户自定义通话记录的描述。
有效值：
  • 0：禁用。
  • 1：启用。
Description 指定默认的描述。
注： 默认值为 {{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}。更多支持的变量，请参见 参数变量列表。
EnablePlayCallRecording 是否允许用户配置在CRM中播放通话录音的选项。
有效值：
  • 0：禁用。
  • 1：启用。
PlayCallRecording 指定通话录音播放选项的默认状态。
有效值：
  • 0：禁用。
  • 1：启用。
Request 请求
<Request> 元素具有以下属性：
属性 说明
Name 请求的名称，用于标识该请求。值应固定为 CallJournal。
Method 要使用的HTTP方法。在此场景中，HTTP方法为 POST。
ResponseType 请求的预期响应格式，应为 JSON 格式（application/json）。
RequestEncoding 请求的编码方式，在此场景中，值为空。
URLFormat API 端点的请求 URL。
Parameter 元素
内嵌在 <Request> 中的 <Parameter> 元素用于定义请求体中包含的参数。
属性 说明
Name 参数的名称，应固定为 Data。
Type 参数的类型，应固定为Body。
Value 定义请求体中传递的所需参数，参数值可以从 PBX 系统中预定义的 变量 中获取。
注： 格式应遵循 XML 参数标准。例如，如果需要换行符，必须使用转义字符 &#xA; 来表示换行符。
变量
注： 此处只列出必需的变量。如果需要其他参数和变量，请参见 扩展配置 - 获取额外变量。
变量 说明
从 AuthMethod 场景获取的变量 从用户在身份验证过程中输入捕获的变量。
{{.Subject}} 通话的主题。

该变量值从 Subject 参数 中获取。
{{.Description}} 通话的描述。

该变量值从 Description 参数 中获取。
{{.Time}} 来电的时间 (跟随PBX 系统的时间格式)。
{{.StartTimeUnix }} 通话开始时间的 Unix 时间戳
{{.EndTimeUnix}} 通话结束时间的 Unix 时间戳。
{{.Call_From}} 主叫的名称和号码。

格式：主叫名称 <主叫号码>。
{{.CallerName}} 主叫的名称。
{{.CallerNumber}} 主叫的号码。
{{.CalleeName}} 被叫的名称。
{{.CalleeNumber}} 被叫的号码。
{{.CrmId}} 与 PBX 分机绑定的 CRM / Helpdesk 用户的唯一 ID。
{{.ExtensionFirstName}} 分机用户的名称。
{{.ExtensionLastName}} 分机用户的姓氏。
{{.ExtensionEmail}} 分机用户的邮箱。
{{.ContactSyncType}} 联系人的类型。
{{.ContactNumber}} 联系人的号码。
{{.ContactId}} 联系人的唯一 ID。
{{.TicketId}} 基于通话创建的工单的唯一 ID。
注： 要获取工单 ID，需要在模板中进行额外配置。有关更多信息，请参见 扩展配置 - 获取工单 ID。
{{.CallDuration}} 通话持续的时间 (从开始到结束的时间)。
{{.Talk_Duration}} 来电接通到通话结束的时间 (格式：hh:mm:ss)。
{{.Talk_Duration_Sec}} 来电接通到通话结束的时间 (以秒为单位)。
{{.Communication_Type}} 通话的方向。
可能取值：
  • Inbound：外线呼入。
  • Outbound：外线呼出。
{{.Call_Status}} 通话的处理状态。
可能取值：
  • Missed：未接来电。
  • Completed：已成功接通并完成的来电。
{{.Call_Log_Status}} 通话的状态。

可能取值：

  • Missed Call：未接来电。
  • Outgoing Call：外线呼出。
  • Incoming Call：外线呼入。
  • Voicemail：未接来电并转入语音信箱。
{{.CallDisposition}} 通话的处理结果。

可能取值：

  • MISSED：未接来电。
  • VOICEMAIL：转入语音信箱。
  • BUSY：对方忙。
  • ANSWERED：已接通来电。
  • NO ANSWER：未接来电。
{{.EnableCallRecording}} 是否启用了通话录音。
可能取值：
  • 0：禁用。
  • 1：启用。

扩展配置

除了配置页面中指定的场景外，你还可以手动添加自定义配置，以满足特定需求。
重要： 修改后，如果再通过 PBX 管理网页更新模板，自定义配置内容可能会被覆盖。
设置自定义请求头
如果需要自定义请求头，你可以添加 Parameter 元素，并将类型 (Type) 设置为 Header，这将在请求体中添加 Header。
如以下示例所示，使用 X-Auth-Token 头传递 API key。其中，Father 属性 (固定为 PopulateTemplateString) 用于组合一组相关参数，而 Type (固定为 Header) 表示该参数将作为 HTTP 头部传递。Name 和 Value 则用于指定头部的名称和值。综上，此请求中将包含头部 X-Auth-Token:{{.api_key}}。
 <Requests>
        <Request Name="contacts" Method="GET" ResponseType="application/json" URLFormat="https://api.example.come/contacts/search?number={{.Phone}}">
          <Parameters>
            <Parameter Father="PopulateTemplateString" Name="X-Auth-Token" Type="Header" Value="{{.api_key}}" />  
          </Parameters>
          <Outputs>
           ...
          </Outputs>
        </Request>
识别令牌错误
在 AuthMethod 场景中，你可以添加一个参数 TokenInvalid 来帮助识别请求中的问题是否与令牌相关。
你可以参考以下示例，将参数的 Value 设置为与令牌相关的错误代码或特定内容。如果返回的 HTTP 状态码不是 200，并且响应体中包含指定的内容，则错误将被识别为 TokenInvalid。
   <Scenario Id="AuthMethod" Type="AUTH">
      <Presets />
      <Parameters>
        <Parameter Name="AuthMethod" Value="oauth2" />
        ...
        <Parameter Father="TokenErrorMap" Type="TokenInvalid" Name="TokenInvalid" Value="INVALID_TOKEN" />
        ...
      </Parameters>
      <Requests />
      <Responses />
    </Scenario>
获取额外变量

若系统提供的变量不满足你的需求，或需在集成过程中全局使用某些通用信息，则可以定义一个 GetGlobalInfo 场景，并设置相关请求来获取所需的变量。

在对接完成或 PBX 启动时，系统将向 CRM / Helpdesk 系统发送一次 GetGlobalInfo 场景中设置的请求，并将获取的变量存储在 Output 元素中 ( 此处的 Output 元素名称直接对应变量名)。这些变量可以在除身份验证场景外的其他场景中引用。

如下示例所示，GetGlobalInfo 场景包含了获取部门 ID 和门户名称的请求。

<Scenario Id="GetGlobalInfo" Type="REST">
      <Presets />
      <Parameters />
      <Requests>
        <Request Name="GetDepartments" Method="GET" ResponseType="application/json" URLFormat="https://desk.example.{{.domain_suffix}}/api/v1/departments">
          <Parameters />
          <Outputs>
            <Output Name="DepartmentId" Path="data.#.id" />
          </Outputs>
        </Request>
        <Request Name="GetOrganizations" Method="GET" ResponseType="application/json" URLFormat="https://desk.example.{{.domain_suffix}}/api/v1/organizations">
          <Parameters />
          <Outputs>
            <Output Name="PortalName" Path="data.#(portalName!="").portalName" />
          </Outputs>
        </Request>
      </Requests>
</Scenario>
补充联系人查询信息
如果初始的联系人信息查询未返回所需的所有信息，可能需要通过返回的联系人 ID 或其他联系人信息进行进一步查询。
如下示例所示，在联系人同步场景中，初始查询请求未返回所需的电话号码。
<Scenario Id="SyncContactAuto" Type="REST">
   <Presets />
   <Parameters>
     <Parameter Name="ContactUrlType" Value="specify_url_format" />
        ...
     </Parameters>
     <Requests>
       <Request Name="contacts" Method="GET" ResponseType="application/json" URLFormat="https://{{.subdomain}}.example.com/api/v2/users?query=phone:{{UrlEncode .Phone}}&role[]=end-user">
         <Parameters />
         <Outputs Next="GetIdentities">
            <Output Name="ContactsId" Path="users.#.id" />
            <Output Name="FirstName" Path="users.#.name" />
            <Output Name="BusinessNumber" Path="users.#.phone" />
            ...   
            //以下电话号码字段返回为空                      
            <Output Name="BusinessNumber2" Path=""></Output>       
            <Output Name="BusinessFaxNumber" Path=""></Output>
            <Output Name="MobileNumber" Path=""></Output>
            <Output Name="MobileNumber2" Path=""></Output>
            <Output Name="HomeNumber" Path=""></Output>
            <Output Name="HomeNumber2" Path=""></Output>
            ...
          </Outputs>
        </Request>
      </Requests>
    </Scenario>
在这种情况下，你可以通过链式调用场景，执行进一步的查询来获取所需的号码，参考以下操作说明。
  1. 在初始查询场景中添加 Next 属性
    在联系人同步场景的初始查询请求的 <Outputs> 元素中添加 Next 属性，其属性值必须是你在后续的 Common 场景 中配置的请求名称。在此示例中，请求名称为 GetIdentities。
    <Outputs Next="GetIdentities">
  2. 创建 Common 场景

    创建一个名为 Common 的场景，且类型 (Type) 需设置为 REST (名称和类型需固定)，然后添加名为 GetIdentities 的请求，并使用初始查询请求中获得的变量 {{.ContactsId}} 进一步查询联系人的其他信息。

    <Scenario Id="Common" Type="REST">
  <Presets></Presets>
  <Parameters></Parameters>
  <Requests>
    <Request Name="GetIdentities" Method="GET" URLFormat="https://{{.subdomain}}.example.com/api/v2/users/{{.ContactsId}}/identities"  ResponseType="application/json">
      <Parameters></Parameters>
      <Outputs>
        <Output Name="BusinessNumber2" Path="identities.#(type=="phone_number")#|1.value"></Output>
        <Output Name="BusinessFaxNumber" Path="identities.#(type=="phone_number")#|2.value"></Output>
        <Output Name="MobileNumber" Path="identities.#(type=="phone_number")#|3.value"></Output>
        <Output Name="MobileNumber2" Path="identities.#(type=="phone_number")#|4.value"></Output>
        <Output Name="HomeNumber" Path="identities.#(type=="phone_number")#|5.value"></Output>
        <Output Name="HomeNumber2" Path="identities.#(type=="phone_number")#|6.value"></Output>
        <Output Name="HomeFaxNumber" Path="identities.#(type=="phone_number")#|7.value"></Output>
        <Output Name="OtherNumber" Path="identities.#(type=="phone_number")#|8.value"></Output>
       </Outputs>
    </Request>
   </Requests>
</Scenario>

    由于该请求在初始查询场景中通过 Next 属性被引用，初始查询中的变量将传递给该请求。该请求将执行进一步查询并将 Output 的数据回填到初始查询请求的响应中，以完成信息的获取。

获取 TicketId 以执行后续操作
在 Helpdesk 集成模板中，你可以通过额外设置来获取工单 ID (TicketId) 以用于后续操作，如更新工单或在通话记录中使用该变量。
如以下示例所示，若设置在通话之前创建 (即电话响铃时) 创建工单，创建的工单可能会缺少某些信息。在这种情况下，你可以稍后使用 TicketId 在相应的通话记录中更新工单信息，参考以下操作说明。
<Scenario Id="CreateNewTicket" Type="REST">
   <Presets />
   <Parameters>
      <Parameter Name="EnableSubject" Value="1" />
      ...
      <Parameter Name="NeedSyncContact" Value="1" />
    </Parameters>
    <Requests>
       <Request Name="CreateNewTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets">
         <Parameters>
          <Parameter Name="Data" Type="Body" Value="{"departmentId":"{{.DepartmentId}}","subject":"{{.Subject}}","contactId":"{{.ContactId}}","phone":"{{.ContactNumber}}","description":"{{.Description}}"}" />
         </Parameters>
         <Outputs>
           <Output Name="TicketId" Path="id" />
         </Outputs>
        </Request>
        <Request Name="UpdateTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets/{{.TicketId}}/comments">
          <Parameters>
            <Parameter Name="Data" Type="Body" Value="{"isPublic":"true","content":"{{.Description}}"}" />
          </Parameters>
        <Outputs />
       </Request>
    </Requests>
</Scenario>
  1. 获取 TicketID

    在 CreateNewTicket 场景中，添加一个 <Output> 元素以提取 CreateNewTicket 请求的响应中返回的工单 ID。

    <Outputs>
  <Output Name="TicketId" Path="id" />
</Outputs>
    这将允许系统存储 TicketId 以供将来使用。
  2. 更新工单
    添加请求，以使用上一步获取的工单 ID 在相应的通话记录中更新工单信息。
    <Request Name="UpdateTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets/{{.TicketId}}/comments">
   <Parameters>
     <Parameter Name="Data" Type="Body" Value="{"isPublic":"true","content":"{{.Description}}"}" />
   </Parameters>
   <Outputs />
</Request>