添加 CRM 集成模板

Yeastar P 系列软件版 允许你创建和配置自定义集成模板，通过 API 将 PBX 与 CRM 系统无缝集成，实现数据交换和同步。本文介绍如何创建 CRM 集成模板并完成必要的配置，以满足特定的集成需求。

使用要求和使用限制

使用要求
  • PBX 服务器
    • 固件版本：83.21.0.66 或更高版本。
    • 订阅服务： CRM 集成。
  • CRM 系统：支持 REST API。
使用限制
支持添加最多 10 个自定义 CRM 集成模板。

前提条件

  • 你具有基本的编码技能。
  • 你已获得目标 CRM 的 REST API 文档作为参考，并获取以下信息：
    • 身份验证方式：确定目标 CRM 使用的身份验证方法 (支持无身份验证、Basic 身份验证、OAuth2 身份验证和 Bearer Token 身份验证方法)。

      若使用 OAuth2 或 Bearer Token 身份验证方法，需收集以下验证所需的 API 请求 URL 和数据规范。

      功能 说明
      授权 用于将用户重定向到授权页面进行身份验证和授权的URL。
      获取访问令牌 用于获取访问令牌的 API 请求 URL。
      刷新访问令牌 可选。用于获取刷新令牌的 API 请求 URL。
    • API 请求信息：根据 CRM 的功能和特定需求，收集以下功能所需的 API 请求 URL 和数据规范。
      功能 说明
      搜索联系人 在 CRM 中搜索联系人所需的 API 请求 URL。
      获取用户 可选。获取 CRM 中用户信息的 API 请求 URL。
      注： 如需获取大量用户，还需要收集相关的分页参数 (如 page、pageSize、limit 或 offset)，以便分批获取用户信息。
      创建联系人 可选。向 CRM 中添加新联系人的 API 请求 URL。
      通话记录 可选。在 CRM 中创建通话记录的 API 请求 URL。

操作步骤

  1. 登录 PBX 管理网页，进入 应用对接 > CRM集成。
  2. 在 CRM 列表中，点击 自定义。

    你将进入模板管理页面。

  3. 点击 添加。
  4. 在弹出的窗口中，根据 CRM 系统支持的功能和你的特定需求，完成以下模板配置。
  5. 点击 保存 以生成自定义 CRM 集成模板。

完成常规设置

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

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

(可选) 配置用户关联

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

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

  1. 打开 用户关联 的开关。

  2. 在 获取用户 字段，填入用于获取 CRM 用户列表的 CRM API 请求 URL。

    注：
    • 默认的 HTTP 请求方法是 GET，如果需要使用其他请求方法，可以稍后在模板中手动更改。有关此场景中模板参数的详细描述，请参见 XML 说明 - 用户关联场景.。
    • 如有需要，用户在对接的 身份验证 过程中输入的值也可以在模板中作为变量使用。
    例如，
    https://www.api.example.com/v1/users?type=ActiveUsers
  3. 在 分页类型 下拉列表中，根据 CRM API 的要求选择对应的分页模式。
    注： 对于需要发起多次请求的分页模式，单次同步操作最多支持 100 次查询请求。
    模式 说明
    禁用 PBX 仅发送一次查询请求，且无需使用分页参数。

    当 API 接口单次可返回全部记录或不支持分页功能时，可使用此模式。
    页码分页 PBX 基于页码和页面记录数量发送多次查询请求以获取用户数据。系统会自动递增后续请求中的页码，直至获取全部数据。

    若选择此模式，需配置以下分页参数：

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

    若选择此模式，需配置以下分页参数：

    • 偏移量参数名称：填写接口请求中用于指定分页起始位置的参数名称。
    • 偏移量参数值：指定获取数据的起始位置。

      例如，设为 1 表示从第 1 条记录开始查询；设为 100 表示从第 100 条开始查询。

    • 限制数量参数名称：填写接口请求中用于指定每页记录数量的参数名称。
    • 限制数量参数值：设置单页返回的最大记录数量。
    链接分页 PBX 通过使用接口响应中指向下一页数据的 URL 发送多次请求来获取用户数据，该过程将持续至所有数据获取完成。

    若选择此模式，你需要在 下一页链接路径 字段中指定用于获取链接的 JSON 路径 (如 links.next)。
  4. 在 用户字段映射 栏，通过指定 CRM 响应中相应字段的 JSON 路径 (例如 data.#(key=="value").field) 将 CRM 字段映射到所需的 PBX 字段。
    提示： 关于更多路径语法信息，请参见 GJSON 路径语法说明。
    PBX 字段 Description
    用户唯一ID 用户的唯一 ID。

    例如，users.#.id。
    名字 用户的名字，将显示在 CRM 用户列表中。

    例如，users.#.First_Name。
    姓氏 用户的姓氏，将显示在 CRM 用户列表中。

    例如，users.#.Last_Name。
    邮箱 用户的电子邮件，将显示在 CRM 用户列表中，并可用于自动关联 CRM 用户与 PBX 分机。

    例如，users.#.Email。

配置身份验证方式

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

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

  1. 在 认证方式 下拉列表中，选择 None。
  2. 可选： 点击 添加 以添加自定义字段。这些字段将作为输入框显示在对接页面上，要求用户提供对接所需的信息。
    注：
    • 如果没有添加字段，CRM 将直接完成对接，而无需用户进行任何额外的设置或输入。
    • 最多支持 5 个自定义字段。
    • 在对接认证过程中，用户输入的值可以在模板中作为变量值使用。
    设置 说明
    类型 选择自定义字段的类型。
    • 文本输入框：标准输入框，用户可以输入普通文本。
    • 密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。
    • 下拉选项框：可选列表，允许用户从预定义的选项中选择。
    名称 为字段指定变量名称，模板中可根据需要引用此名称。
    标题 为字段指定标题，将显示在输入框上方。
    下拉选项值 如果 类型 设置为 下拉选项框，在此字段中输入选项。
    注： 使用半角逗号 , 分隔多个选项，例如 option1,option2。
Basic 身份验证
此方法使用凭证 (如用户名和密码或 API 密钥) 来认证请求。在这种情况下，发送到 CRM 的每个 HTTP 请求将包含一个请求头字段，格式为 Authorization: Basic {{.basic_string}}，其中 {{.basic_string}} 是在对接过程中指定的用户名和密码或 API 密钥的 Base64 编码组合。

  1. 在 认证方式 下拉列表中，选择 Basic。
  2. 在 凭证类型 下拉列表中，根据 CRM 系统的要求，选择 用户名和密码 或 API 密钥。
  3. 配置用户输入凭证所需的字段，并根据需要添加其他自定义字段。
    注：
    • 最多支持 5 个字段。
    • 在对接认证过程中，用户输入的值可以在模板中作为变量值使用。
    设置 说明
    类型 选择自定义字段的类型。
    • 文本输入框：标准输入框，用户可以输入普通文本。
    • 密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。
    • 下拉选项框：可选列表，允许用户从预定义的选项中选择。
    名称 为字段指定变量名称，模板中可根据需要引用此名称。
    标题 为字段指定标题，将显示在输入框上方。
    下拉选项值 如果 类型 设置为 下拉选项框，在此字段中输入选项。
    注： 使用半角逗号 , 分隔多个选项，例如 option1,option2。
  4. 在 Base64 编码的凭证 字段中，指定凭证变量的组合格式，用于生成 basic 认证字符串 (basic_string)。

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

OAuth2 身份验证

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

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

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

    注：
    • 如果需要更多字段，可在 XML 模板中手动添加自定义字段。有关此场景中模板参数的详细描述，请参见 XML 说明 - 身份验证场景。
    • 在对接认证过程中，用户输入的值可以在模板中作为变量值使用。
    设置 说明
    类型 选择自定义字段的类型。
    • 文本输入框：标准输入框，用户可以输入普通文本。
    • 密码输入框：专用的输入框，用于敏感信息，输入内容会被隐藏。
    • 下拉选项框：可选列表，允许用户从预定义的选项中选择。
    名称 为字段指定变量名称，模板中可根据需要引用此名称。
    标题 为字段指定标题，将显示在输入框上方。
    下拉选项值 如果 类型 设置为 下拉选项框，在此字段中输入选项。
    注： 使用半角逗号 , 分隔多个选项，例如 option1,option2。
  3. 配置 OAuth2 授权相关设置。

    设置 说明
    授权端点 输入 CRM 的授权 URL，用户将在对接过程中被重定向到此 URL 进行授权。

    例如，

    https://www.api.example.com/auth/v2/authorize?client_id={{.client_id}}
    令牌端点 输入获取访问令牌和刷新令牌的 CRM API 请求端点 URL。

    例如，

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
    请求内容类型 选择令牌获取请求的内容类型。
    访问范围 可选。输入允许 PBX 访问的 CRM 数据范围。
    注： 使用半角逗号 , 分隔多个字段。

    例如，

    contacts.read,contacts.write,calls.read,calls.write,user.read,user.write
    附加查询字符串 可选。如果 CRM 系统使用查询参数进行身份验证而不是范围，在该字段中添加查询参数。

    例如，client_id={{.client_id}}&redirect_uri={{.redirect_uri}}。
  4. 可选： 配置令牌刷新设置。

    设置 说明
    令牌刷新请求方式 刷新令牌 API 的 HTTP 请求方法。
    令牌刷新端点 输入用于刷新访问令牌的 API 请求 URL。
    令牌刷新内容类型 选择令牌刷新请求的内容类型。
    令牌刷新时间 (分钟) 指定系统自动刷新访问令牌的时间间隔 (单位：分钟)。
    注：

    • 如果设置为 0，系统将不会自动刷新令牌。

    • 如果留空，系统默认每 25 分钟自动刷新一次访问令牌。
    令牌刷新请求体 刷新令牌 API 的请求体。
Bearer Token 身份验证
该方法使用 Bearer Token 对请求进行身份验证，Token 通常通过授权流程 (如 OAuth2) 获取。每个发送到 CRM 的 HTTP 请求都必须包含格式为 Authorization: Bearer {{.AccessToken}} 的头字段，其中 {{.AccessToken}} 是 CRM 提供的令牌值。
  1. 在 认证方式 下拉列表中，选择 Bearer Token。

  2. 配置用户输入凭据所需的字段，如有需要可添加额外的自定义字段。

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

    设置 Description
    令牌端点 输入获取访问令牌的 CRM API 请求 URL。

    例如，

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
    从该请求获取的令牌将存储于变量 {{.AccessToken}} 中。
    请求内容类型 选择令牌获取请求的内容类型。
  4. 可选： 配置令牌刷新设置。

    设置 说明
    令牌刷新请求方式 刷新令牌 API 的 HTTP 请求方法。
    令牌刷新端点 输入用于刷新访问令牌的 API 请求 URL。
    令牌刷新内容类型 选择令牌刷新请求的内容类型。
    令牌刷新时间 (分钟) 指定系统自动刷新访问令牌的时间间隔 (单位：分钟)。
    注：

    • 如果设置为 0，系统将不会自动刷新令牌。

    • 如果留空，系统默认每 25 分钟自动刷新一次访问令牌。
    令牌刷新请求体 刷新令牌 API 的请求体。

(可选) 配置请求头

根据需要添加自定义 HTTP 请求头，这些请求头将包含在每个预配置的 CRM 同步请求 (如用户关联、联系人同步等)。
注：
  • 最多支持添加 20 个自定义请求头。
  • 这些自定义请求头不会应用于认证相关请求 (如获取或刷新访问令牌) 及自定义请求。
  • 避免在此处定义 Authorization 请求头，否则会覆盖由 Basic、OAuth2 或 Bearer Token 身份验证流程所获取的请求头的值。

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

(可选) 添加后续请求

若集成需要在特定的预配置请求完成后执行额外操作，可在此处添加后续请求。这些请求将在指定操作完成后自动触发，其响应数据可被提取并存储为全局变量，以便在集成的其他位置复用。
注： 最多可添加 10 个后续请求。

  1. 在 请求配置 > 后续请求 栏，点击 添加。
  2. 配置后续请求的详细信息。
    设置 说明
    触发事件 指定触发此请求的事件。
    请求方式 选择 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 请求。这些配置可用于实现 CRM 联系人搜索、自动联系人同步和来电弹窗功能。
  1. 添加并配置联系人类型，并指定相应的 API 请求。

    • 联系人类型：输入联系人类型的名称。

      这里设置的名称将作为自动联系人同步的选项，展示在用户配置集成功能时的界面上。

    • 联系人匹配查询URL：输入可基于特定条件搜索联系人的 CRM 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}}))
  2. 通过以下任一方式配置来电弹屏。
    指定 URL 格式
    通过指定 URL 格式来配置来电弹屏 URL，可使用变量动态构建 URL。
    1. 在 联系人弹屏地址 下拉列表中，选择 指定 URL 格式。
    2. 在 URL 格式 字段，输入联系人 URL 的表达式。

      在此场景中，可以使用以下变量，其中变量值可自动从 CRM 联系人搜索结果中获取。

      注： 如果提供的变量不满足需求，可稍后手动编辑模板来定义其他自定义变量，并获取相应的值。有关此场景中模板参数的详细描述，请参见 XML 说明 - 获取额外变量。
      例如，
      {{.domain_url}}/{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}
    从联系人字段信息获取
    直接从联系人搜索响应中的特定字段提取联系人 URL。

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

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

    3. 如果现有 PBX 字段不满足需求，可以启用 自定义值 并映射所需的响应字段。该字段可以在模板中通过变量名 {{.CustomValue}} 引用。
      注： 此变量专门用于 构建联系人 URL，不会出现在 PBX 联系人详细信息中。

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

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

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

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

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

  1. 打开 通话记录同步 的开关。
  2. 配置创建通话记录的 API 请求和请求体。
    • 创建通话记录 URL（POST）：输入用于在 CRM 中创建通话记录的 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}}"
      }
    }
  ]
}
  3. 可选： 如需配置在集成中要提供的通话记录同步相关设置，勾选对应的选项以启用，并为每个设置项配置默认值。
    设置项 说明
    主题 若启用，集成中将提供对应配置项，可用于设置所有同步的通话记录的默认主题。
    注：
    描述 若启用，集成中将提供对应配置项，可用于指定同步的通话记录的详情信息。
    例如：
    Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
    注：
    播放通话录音 若启用，集成中将提供对应配置项，可用于决定是否启用在 CRM 系统中播放通话录音的功能。
    未接听的坐席不记录未接来电 若启用，集成中将提供对应配置项，可用于决定队列和响铃组来电的记录是否仅同步至接听坐席的 CRM 中，而对应通话的未接来电记录不会同步至其他未接听坐席的 CRM。