EspoCRM リファレンス実装

このドキュメントでは、EspoCRM を使用した Contact Center AI Platform（CCAI Platform）カスタム CRM との統合の例を示します。EspoCRM は、カスタマイズ可能なインターフェースで販売、マーケティング、顧客サポートの管理を支援する無料のオープンソース CRM アプリケーションです。連絡先管理、アクティビティ トラッキング、営業の自動化、在庫管理などの機能が提供され、セルフホスティングまたはクラウド デプロイのオプションがあります。

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

始める前に

手順は次のとおりです。

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

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

  • 次のものにアクセスする 作成、読み取り、更新アクションを使用して、EspoCRM インスタンスにロールを作成します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  6. [回答データのロケーション] を data に設定します。

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

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

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

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

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

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

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

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

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [リクエスト パラメータ] で、[フィールドを追加] をクリックします。[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 レコード] セクションに移動します。
  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] ページに戻ります。

Create a record エンドポイントを構成する

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

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

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

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [リクエスト パラメータ] で、[フィールドを追加] をクリックします。[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. [オブジェクト ID の場所] フィールドに「id」と入力します。

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

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

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

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

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

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

    1. 最初のリクエスト パラメータを構成する手順は次のとおりです。
      1. [リクエスト パラメータ] で、[フィールドを追加] をクリックします。[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] ページに戻ります。