EspoCRM 參考實作

本文提供與 Contact Center AI Platform (CCAI Platform) 自訂 CRM 整合的範例，使用 EspoCRM。EspoCRM 是免費的開放原始碼 CRM 應用程式，可透過自訂介面協助企業管理銷售、行銷和客戶服務。這類軟體提供聯絡人管理、活動追蹤、銷售自動化和庫存管理等功能，並可選擇自行代管或雲端部署。

如要設定自己的 EspoCRM 執行個體，請參閱 EspoCRM 安裝頁面。

事前準備

請執行下列步驟：

  • 設定防火牆，允許 CCAI Platform 傳出的流量。

  • 在 EspoCRM 執行個體中建立 API 使用者，例如 google_integration_user。詳情請參閱 EspoCRM 說明文件中的「API」。

  • 在 EspoCRM 執行個體中建立角色，並使用「建立」、「讀取」和「更新」動作存取下列項目：

    • 聯絡人：尋找或建立來電者
    • 案件：搜尋及記錄工單

    詳情請參閱 ExpoCRM 說明文件中的「角色管理」。

設定從 EspoCRM 到 CCAI 平台的連線

如要設定從 EspoCRM 到 CCAI 平台的連線，請按照下列步驟操作：

  1. 在 CCAI Platform 入口網站中，依序點選「Settings」>「Developer Settings」。如果沒有看到「設定」選單，請按一下「選單」。
  2. 在「Agent Platform」部分，選取「Custom CRM」。
  3. 按一下「在 CCAI 平台入口網站中顯示 CRM」切換鈕，將其設為開啟狀態。
  4. 在「顯示網址」欄位中，輸入要嵌入 CCAI Platform 入口網站的網址，例如 https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}。
  5. 在「CRM 查詢方法」中，選取「一般 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 查詢網址」部分，於「記錄查詢網址」欄位中， 輸入要查詢記錄的網址，例如： https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}。
    2. 在「帳戶查詢網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}。
    3. 按一下「儲存」。 ## 設定 API 端點

設定與 EspoCRM 相容的端點，確保整合功能具備查閱帳戶 (聯絡人) 和記錄 (案件) 的元件。如要進一步瞭解相容變數，請參閱 EspoCRM 說明文件中的「API 總覽」。

設定 API 帳戶端點

本節說明如何設定 API 帳戶端點。

設定「依查詢條件尋找帳戶」端點

如要設定「Find an account by query endpoint」(依查詢端點尋找帳戶)，請按照下列步驟操作：

  1. 在 CCAI Platform 中，依序點選「Settings」>「Developer Settings」。如果沒有看到「設定」選單，請按一下「選單」。
  2. 在「CRM」窗格中，前往「API 帳戶」部分。
  3. 如要透過查詢端點尋找帳戶，請按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  4. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  5. 在「方法」部分，選取「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. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「依 ID 尋找帳戶」端點

如要設定「依 ID 尋找帳戶」端點，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API 帳戶」部分。
  2. 在「Find an account by ID endpoint」(依 ID 尋找帳戶端點) 部分，按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}。
    1. 在「方法」部分，選取「GET」。
  4. 將「Response Data Location」(回應資料位置) 設為 data。
  5. 按一下 [儲存]。
  6. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「建立帳戶」端點

如要設定「建立帳戶端點」，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API 帳戶」部分。
  2. 如要建立帳戶端點，請按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  4. 在「方法」部分選取「POST」。

  5. 如要設定要求參數，請按照下列步驟操作：

    1. 如要設定第一個要求參數，請按照下列步驟操作：
      1. 在「要求參數」部分，按一下「新增欄位」。系統會隨即顯示「新增欄位」對話方塊。
      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. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「更新帳戶」端點

如要設定「更新帳戶端點」，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API 帳戶」部分。
  2. 如要更新帳戶端點，請按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Contact。
  4. 在「方法」部分選取「PUT」。

  5. 如要設定要求參數，請按照下列步驟操作：

    1. 如要設定第一個要求參數，請按照下列步驟操作：
      1. 在「要求參數」部分，按一下「新增欄位」。系統會隨即顯示「新增欄位」對話方塊。
      2. 在「Field Key」(欄位鍵) 欄位中，輸入 contactId。
      3. 在「Field Value」(欄位值) 欄位中，輸入 {PHONE_NUMBER}。
      4. 按一下 [儲存]。

    2. 如要設定其餘要求參數，請使用下表中的資訊，重複上一個步驟。您已建立第一個要求參數。

      參數金鑰 參數值
      contactId {PHONE_NUMBER}
      phoneNumber New Caller

  6. 將「回應資料位置」設為 data。

  7. 按一下 [儲存]。

  8. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定 API 記錄端點

本節說明如何設定 API 記錄端點。

設定「依查詢條件尋找記錄」端點

如要設定「依查詢端點尋找記錄」，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API record」部分。
  2. 在「Find a record by query endpoint」(透過查詢端點尋找記錄) 部分，按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case。
  4. 在「方法」部分，選取「GET」。

  5. 如要設定要求參數，請按照下列步驟操作：

    1. 如要設定第一個要求參數，請按照下列步驟操作：
      1. 在「要求參數」部分，按一下「新增欄位」。系統會隨即顯示「新增欄位」對話方塊。
      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. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「依 ID 尋找記錄」端點

這項功能通常用於以 SDK 為基礎的互動，可讓您傳遞特定記錄 ID，將互動與該 ID 建立關聯。如要設定「依 ID 尋找記錄」端點，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API record」部分。
  2. 在「Find a record by ID endpoint」(依 ID 尋找記錄端點) 部分，按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}。
  4. 在「方法」部分，選取「GET」。
  5. 在「Response Data Location」(回應資料位置) 欄位中輸入 data。
  6. 按一下 [儲存]。
  7. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「建立記錄」端點

如要設定「建立記錄端點」，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API record」部分。
  2. 在「建立記錄端點」部分，按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case。
  4. 在「方法」部分選取「POST」。

  5. 如要設定要求參數，請按照下列步驟操作：

    1. 如要設定第一個要求參數，請按照下列步驟操作：
      1. 在「要求參數」部分，按一下「新增欄位」。系統會隨即顯示「新增欄位」對話方塊。
      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. 在「物件 ID 位置」欄位中，輸入 id。

  8. 按一下 [儲存]。

  9. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。

設定「更新記錄」端點

如要設定「更新記錄端點」，請按照下列步驟操作：

  1. 在「CRM」窗格中，前往「API record」部分。
  2. 如要更新記錄端點，請按一下「設定」。系統會顯示「Generic API Endpoint Setup」(一般 API 端點設定) 頁面。
  3. 在「網址」欄位中，輸入要查詢帳戶的網址，例如 https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}。
  4. 在「方法」部分選取「PUT」。

  5. 如要設定要求參數，請按照下列步驟操作：

    1. 如要設定第一個要求參數，請按照下列步驟操作：
      1. 在「要求參數」部分，按一下「新增欄位」。系統會隨即顯示「新增欄位」對話方塊。
      2. 在「Field Key」(欄位鍵) 欄位中，輸入 parentId。
      3. 在「Field Value」(欄位值) 欄位中，輸入 {RECORD_ID}。
      4. 按一下 [儲存]。

    2. 如要設定其餘要求參數，請使用下表中的資訊，重複上一個步驟。您已建立第一個要求參數。

      參數金鑰 參數值
      parentId {RECORD_ID}
      parentType Case
      status New
      description {TICKET_DESCRIPTION}

  6. 在「Response data location」(回應資料位置) 欄位中，輸入 data。

  7. 按一下 [儲存]。

  8. 按一下「返回開發人員設定」，返回「開發人員設定」頁面。