EspoCRM 参考实现

本文档提供了一个使用 EspoCRM 与 Contact Center AI 平台 (CCAI Platform) 自定义 CRM 集成的示例。EspoCRM 是一款免费的开源 CRM 应用，可帮助企业通过可自定义的界面管理销售、营销和客户支持。它提供联系人管理、活动跟踪、销售自动化和库存管理等功能，并提供自托管或云部署选项。

如需设置自己的 EspoCRM 实例，请参阅 EspoCRM 安装 页面。

准备工作

执行以下操作：

  • 配置防火墙以允许来自 CCAI Platform 的流量。

  • 在 EspoCRM 实例中创建 API 用户，例如 google_integration_user。如需了解详情，请参阅 API在 EspoCRM 文档中。

  • 在 EspoCRM 实例中创建一个角色，该角色具有 Create 、Read 和 Update 操作，可访问以下内容：

    • 联系人：用于查找或创建来电者
    • Cases：用于搜索和记录工单

    如需了解详情，请参阅 ExpoCRM 文档中的角色 管理。

配置从 EspoCRM 到 CCAI Platform 的连接

如需配置从 EspoCRM 到 CCAI Platform 的连接，请按以下步骤操作：

  1. 在 CCAI Platform 门户中，依次点击 设置 > 开发者设置。如果您没有看到设置 菜单，请点击菜单 。
  2. 对于 Agent Platform ，选择 Custom CRM 。
  3. 点击 Display CRM in CCAI Platform portal Portal （在 CCAI Platform 门户中显示 CRM 门户）切换开关以切换到开启位置。
  4. 在 Display 网址（显示网址）字段中，输入要嵌入到 CCAI Platform 门户中的网址，例如 https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}。
  5. 对于 CRM lookup method（CRM 查找方法），选择 Generic API（通用 API）。
  6. 如需使用自定义标头进行身份验证，请执行以下操作：
    1. 在 Authentication Method （身份验证方法）部分，选择 Custom Header （自定义标头）。
    2. 点击添加字段 。系统随即会显示添加字段 对话框。
      1. 在 Field Key （字段的键）字段中，输入 X-Api-Key。
      2. 在 Field Value （字段值）字段中，输入在 EspoCRM 中创建 API 用户时生成的 API 密钥。
      3. 点击保存 。
  7. 如需设置 CRM 查找网址，请执行以下操作：
    1. 在 CRM lookup 网址（CRM 查找网址）部分的 Record lookup 网址（记录查找网址）字段中， 输入用于查找记录的网址，例如 https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}。
    2. 在 Account lookup 网址 （账号查找网址）字段中，输入用于查找 账号的网址，例如 https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}。
    3. 点击保存 。 ## 配置 API 端点

配置与 EspoCRM 兼容的端点，以确保您的集成具有查找账号（联系人）和记录（案例）的组件。如需详细了解兼容的变量，请参阅 EspoCRM 文档中的 API 概览。

配置 API 账号端点

本部分介绍了如何配置 API 账号端点。

配置“按查询查找账号”端点

如需配置按查询查找账号端点，请按以下步骤操作：

  1. 在 CCAI Platform 中，依次点击 设置 > 开发者 设置。如果您没有看到设置 菜单，请点击菜单 。
  2. 在 CRM 窗格中，前往 API account （API 账号）部分。
  3. 对于 Find an account by query endpoint（按查询查找账号端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  4. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  5. 对于 Method（方法），选择 GET 。

  6. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 点击添加字段 。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 where[0][attribute]。
      3. 在 Field Value （字段值）字段中，输入 phoneNumber。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      字段的键 字段值
      where[0][attribute] phoneNumber
      where[0][type] equals
      where[0][value] {PHONE_NUMBER}
      sortBy createdAt
      asc false

  7. 在 Response Data Location （响应数据位置）字段中，输入 data.list。

  8. 点击保存 。

  9. 点击 Back to Developer Settings （返回开发者设置），以返回开发者设置 页面。

配置“按 ID 查找账号”端点

如需配置按 ID 查找账号端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API account （API 账号）部分。
  2. 对于 Find an account by ID endpoint（按 ID 查找账号端点），点击 Setup。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
    1. 对于 Method（方法），选择 GET 。
  4. 将 Response Data Location （响应数据位置）设置为 data。
  5. 点击保存 。
  6. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置“创建账号”端点

如需配置创建账号端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API account （API 账号）部分。
  2. 对于 Create an account endpoint（创建账号端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  4. 对于 Method（方法），选择 POST 。

  5. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 对于 Request Parameters（请求参数），点击添加字段。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 phoneNumber。
      3. 在 Field Value （字段值）字段中，输入 {PHONE_NUMBER}。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      参数键 参数值
      phoneNumber {PHONE_NUMBER}
      firstName New Caller
      lastName {CALL_ID}
      name New Caller {CALL_ID}

  6. 将响应数据位置 设置为 data。

  7. 将对象 ID 位置 设置为 id。

  8. 点击保存 。

  9. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置“更新账号”端点

如需配置更新账号端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API account （API 账号）部分。
  2. 对于 Update an account endpoint（更新账号端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  4. 对于 Method（方法），选择 PUT 。

  5. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 对于 Request Parameters（请求参数），点击添加字段。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 contactId。
      3. 在 Field Value （字段值）字段中，输入 {PHONE_NUMBER}。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      参数键 参数值
      contactId {PHONE_NUMBER}
      phoneNumber New Caller

  6. 将响应数据位置 设置为 data。

  7. 点击保存 。

  8. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置 API 记录端点

本部分介绍了如何配置 API 记录端点。

配置“按查询查找记录”端点

如需配置按查询查找记录端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API record （API 记录）部分。
  2. 对于 Find a record by query endpoint（按查询查找记录端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case。
  4. 对于 Method（方法），选择 GET 。

  5. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 对于 Request Parameters（请求参数），点击添加字段。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 where[0][attribute]。
      3. 在 Field Value （字段值）字段中，输入 contactId。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      字段的键 字段值
      where[0][attribute] contactId
      where[0][type] equals
      where[0][value] {ACCOUNT_ID}
      contactId {ACCOUNT_ID}
      sortBy createdAt
      asc false

  6. 在 Response Data Location （响应数据位置）字段中，输入 data.list。

  7. 点击保存 。

  8. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置“按 ID 查找记录”端点

此端点通常用于基于 SDK 的互动，可让您传递特定记录 ID 以将互动与该记录相关联。如需配置 按 ID 查找记录端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API record （API 记录）部分。
  2. 对于 Find a record by ID endpoint（按 ID 查找记录端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}。
  4. 对于 Method（方法），选择 GET 。
  5. 在 Response Data Location （响应数据位置）字段中，输入 data。
  6. 点击保存 。
  7. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置“创建记录”端点

如需配置创建记录端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API record （API 记录）部分。
  2. 对于 Create a record endpoint（创建记录端点），点击设置 。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case。
  4. 对于 Method（方法），选择 POST 。

  5. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 对于 Request Parameters（请求参数），点击添加字段。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 description。
      3. 在 Field Value （字段值）字段中，输入 CALL Session:{CALL_ID}。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      参数键 参数值
      description Call Session: {CALL_ID}
      name Inbound Call from {ANI}
      contactId {ACCOUNT_ID}
      status New
      cchatId {CHAT_ID}
      ccallId {CALL_ID}
      cChannel {CHANNEL}
      Type {SESSION_TYPE}

  6. 在 Response Data Location （响应数据位置）字段中，输入 data。

  7. 在 Object ID Location （对象 ID 位置）字段中，输入 id。

  8. 点击保存 。

  9. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。

配置“更新记录”端点

如需配置更新记录端点，请按以下步骤操作：

  1. 在 CRM 窗格中，前往 API record （API 记录）部分。
  2. 对于 Update a record endpoint（更新记录端点），点击设置。系统随即会显示 Generic API Endpoint Setup （通用 API 端点设置）页面。
  3. 在 网址 字段中，输入用于查找账号的网址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}。
  4. 对于 Method（方法），选择 PUT 。

  5. 如需配置请求参数，请执行以下操作：

    1. 如需配置第一个请求参数，请按以下步骤操作：
      1. 对于 Request Parameters（请求参数），点击添加字段。系统随即会显示添加字段 对话框。
      2. 在 Field Key （字段的键）字段中，输入 parentId。
      3. 在 Field Value （字段值）字段中，输入 {RECORD_ID}。
      4. 点击保存 。

    2. 如需配置其余请求参数，请使用下表中的信息重复上述步骤。您已创建第一个请求参数。

      参数键 参数值
      parentId {RECORD_ID}
      parentType Case
      status New
      description {TICKET_DESCRIPTION}

  6. 在响应数据位置 字段中，输入 data。

  7. 点击保存 。

  8. 点击 Return to developer settings （返回开发者设置），以返回开发者设置 页面。