EspoCRM リファレンス実装

このドキュメントでは、EspoCRM を使用して Contact Center AI プラットフォーム（CCAI プラットフォーム）のカスタム CRM と統合する例について説明します。EspoCRM は、カスタマイズ可能なインターフェースで販売、マーケティング、カスタマー サポートを管理できる無料のオープンソース CRM アプリケーションです。連絡先管理、アクティビティ トラッキング、セールス オートメーション、在庫管理などの機能が用意されており、セルフホスティングまたはクラウド デプロイのオプションがあります。

EspoCRM の独自のインスタンスを設定するには、EspoCRM のインストール ページをご覧ください。

始める前に

手順は次のとおりです。

  • CCAI プラットフォームからのトラフィックを許可するようにファイアウォールを構成します。

  • EspoCRM インスタンスに API ユーザー（google_integration_user など）を作成します。詳細については、 EspoCRM ドキュメントの API をご覧ください。

  • 次のものにアクセスする Create、Read、および Update アクションを使用して、EspoCRM インスタンスにロールを作成します。

    • Contacts: 発信者を検索または作成する
    • Cases: チケットを検索して記録する

    詳細については、ExpoCRM ドキュメントのロール 管理をご覧ください。

EspoCRM から CCAI プラットフォームへの接続を構成する

EspoCRM から CCAI プラットフォームへの接続を構成する手順は次のとおりです。

  1. CCAI プラットフォーム ポータルで、設定 > デベロッパー設定 をクリックします。[設定] メニューが表示されない場合は、メニュー をクリックします。
  2. [Agent Platform] で [Custom CRM] を選択します。
  3. [Display CRM in CCAI Platform portal Portal] 切り替えボタンをオンにします。
  4. [Display URL] フィールドに、 CCAI プラットフォーム ポータルに埋め込む URL（ https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID} など）を入力します。
  5. [CRM lookup method] で [Generic API] を選択します。
  6. カスタム ヘッダーを使用して認証するには、次の操作を行います。
    1. [Authentication Method] セクションで [Custom Header] を選択します。
    2. [フィールドを追加] をクリックします。[フィールドを追加] ダイアログが表示されます。
      1. [フィールド キー] フィールドに「X-Api-Key」と入力します。
      2. [フィールド値] フィールドに、EspoCRM で API ユーザーを作成したときに生成された API キーを入力します。
      3. [保存] をクリックします。
  7. CRM 検索 URL を設定する手順は次のとおりです。
    1. [CRM lookup URL] セクションの [Record lookup URL] フィールドに、レコードを検索する URL（https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID} など）を入力します。
    2. [Account lookup URL] フィールドに、アカウントを検索する URL（https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID} など）を入力します。
    3. [保存] をクリックします。 ## API エンドポイントを構成する

EspoCRM と互換性のあるエンドポイントを構成して、統合にアカウント（連絡先）とレコード（ケース）を検索するためのコンポーネントが含まれるようにします。互換性のある変数の詳細については、EspoCRM ドキュメントのAPI の概要をご覧ください。

API アカウント エンドポイントを構成する

このセクションでは、API アカウント エンドポイントを構成する方法について説明します。

クエリでアカウントを検索するエンドポイントを構成する

[クエリでアカウントを検索するエンドポイント] を構成する手順は次のとおりです。

  1. CCAI プラットフォームで、設定 > デベロッパー 設定 をクリックします。[設定] メニューが表示されない場合は、メニュー をクリックします。
  2. [CRM] ペインで、[API account] セクションに移動します。
  3. [Find an account by query endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  4. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Contact など）を入力します。
  5. [Method] で [GET] を選択します。

  6. リクエスト パラメータを構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [フィールドを追加] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「where[0][attribute]」と入力します。
      3. [フィールド値] フィールドに「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] をクリックして、[Developer Settings] ページに戻ります。

ID でアカウントを検索するエンドポイントを構成する

[ID でアカウントを検索するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API account] セクションに移動します。
  2. [Find an account by ID endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID} など）を入力します。
    1. [Method] で [GET] を選択します。
  4. [Response Data Location] を data に設定します。
  5. [保存] をクリックします。
  6. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。

アカウントを作成するエンドポイントを構成する

[アカウントを作成するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API account] セクションに移動します。
  2. [**Create an account endpoint**] で [**Setup**] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Contact など）を入力します。
  4. [Method] で [POST] を選択します。

  5. [Request Parameters] を構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [Request Parameters] で [Add field] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「phoneNumber」と入力します。
      3. [フィールド値] フィールドに「{PHONE_NUMBER}」と入力します。
      4. [保存] をクリックします。

    2. 残りのリクエスト パラメータを構成するには、次の表の情報を使用して、上記の手順を繰り返します。最初のリクエスト パラメータはすでに作成済みです。

      パラメータキー パラメータ値
      phoneNumber {PHONE_NUMBER}
      firstName New Caller
      lastName {CALL_ID}
      name New Caller {CALL_ID}

  6. [Response data location] を data に設定します。

  7. [Object ID location] を id に設定します。

  8. [保存] をクリックします。

  9. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。

アカウントを更新するエンドポイントを構成する

[アカウントを更新するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API account] セクションに移動します。
  2. [Update an account endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Contact など）を入力します。
  4. [Method] で [PUT] を選択します。

  5. [Request Parameters] を構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [Request Parameters] で [Add field] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「contactId」と入力します。
      3. [フィールド値] フィールドに「{PHONE_NUMBER}」と入力します。
      4. [保存] をクリックします。

    2. 残りのリクエスト パラメータを構成するには、次の表の情報を使用して、上記の手順を繰り返します。最初のリクエスト パラメータはすでに作成済みです。

      パラメータキー パラメータ値
      contactId {PHONE_NUMBER}
      phoneNumber New Caller

  6. [Response data location] を data に設定します。

  7. [保存] をクリックします。

  8. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。

API レコード エンドポイントを構成する

このセクションでは、API レコード エンドポイントを構成する方法について説明します。

クエリでレコードを検索するエンドポイントを構成する

[クエリでレコードを検索するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API record] セクションに移動します。
  2. [Find a record by query endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Case など）を入力します。
  4. [Method] で [GET] を選択します。

  5. [Request Parameters] を構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [Request Parameters] で [Add field] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「where[0][attribute]」と入力します。
      3. [フィールド値] フィールドに「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] をクリックして、[Developer Settings] ページに戻ります。

ID でレコードを検索するエンドポイントを構成する

SDK ベースのインタラクションでよく使用されます。これにより、特定のレコード ID を渡してインタラクションを関連付けることができます。 [**ID でレコードを検索するエンドポイント**] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API record] セクションに移動します。
  2. [Find a record by ID endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID} など）を入力します。
  4. [Method] で [GET] を選択します。
  5. [Response Data Location] フィールドに「data」と入力します。
  6. [保存] をクリックします。
  7. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。

レコードを作成するエンドポイントを構成する

[レコードを作成するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API record] セクションに移動します。
  2. [Create a record endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Case など）を入力します。
  4. [Method] で [POST] を選択します。

  5. [Request Parameters] を構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [Request Parameters] で [Add field] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「description」と入力します。
      3. [フィールド値] フィールドに「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」と入力します。

  8. [保存] をクリックします。

  9. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。

レコードを更新するエンドポイントを構成する

[レコードを更新するエンドポイント] を構成する手順は次のとおりです。

  1. [CRM] ペインで、[API record] セクションに移動します。
  2. [Update a record endpoint] で [Setup] をクリックします。[Generic API Endpoint Setup] ページが表示されます。
  3. [URL] フィールドに、アカウントを検索する URL（ https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID} など）を入力します。
  4. [Method] で [PUT] を選択します。

  5. [Request Parameters] を構成する手順は次のとおりです。

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [Request Parameters] で [Add field] をクリックします。[フィールドを追加] ダイアログが表示されます。
      2. [フィールド キー] フィールドに「parentId」と入力します。
      3. [フィールド値] フィールドに「{RECORD_ID}」と入力します。
      4. [保存] をクリックします。

    2. 残りのリクエスト パラメータを構成するには、次の表の情報を使用して、上記の手順を繰り返します。最初のリクエスト パラメータはすでに作成済みです。

      パラメータキー パラメータ値
      parentId {RECORD_ID}
      parentType Case
      status New
      description {TICKET_DESCRIPTION}

  6. [Response data location] フィールドに「data」と入力します。

  7. [保存] をクリックします。

  8. [Return to developer settings] をクリックして、[Developer Settings] ページに戻ります。