EspoCRM reference implementation

This document provides an example integration with Contact Center AI Platform (CCAI Platform) custom CRM using EspoCRM. EspoCRM is a free, open-source CRM application that helps businesses manage sales, marketing, and customer support with a customizable interface. It offers features like contact management, activity tracking, sales automation, and inventory management, with options for self-hosting or cloud deployment.

To set up your own instance of EspoCRM, see the EspoCRM installation page .

Before you begin

Do the following:

• Configure your firewall to permit traffic from CCAI Platform.

• Create an API user in your EspoCRM instance—for example, google_integration_user . For more information, see API in the EspoCRM Documentation.

• Create a role in your EspoCRM instance with the Create, Read, and Updateactions that accesses the following:

  • Contacts: to find or create callers
  • Cases: to search for and log tickets

  For more information, see Role Management in the ExpoCRM documentation.

Configure a connection from EspoCRM to CCAI Platform

To configure a connection from EspoCRM to CCAI Platform, follow these steps:

1. In the CCAI Platform portal, click Settings > Developer Settings. If you don't see the Settingsmenu, click Menu.
2. For Agent Platform, select Custom CRM.
3. Click the Display CRM in CCAI Platform portal Portaltoggle to the on position.
4. In the Display URLfield, enter the URL to embed in the CCAI Platform portal–for example, https:// YOUR_ESPO_DOMAIN /#Case/view/{RECORD_ID} .
5. For CRM lookup method, select Generic API.
6. To authenticate using a custom header, do the following:
   1. In the Authentication Methodsection, select Custom Header.
   2. Click Add field. The Add Fielddialog appears.
      1. In the Field Keyfield, enter X-Api-Key .
      2. In the Field Valuefield, enter the API key generated when you created an API user in your EspoCRM.
      3. Click Save.
7. To set the CRM lookup URL, do the following:
   1. In the CRM lookup URLsection, in the Record lookup URLfield, enter the URL to look up a record—for example, https:// YOUR_ESPO_DOMAIN /#Case/view/{RECORD_ID} .
   2. In the Account lookup URLfield, enter the URL to look up an account—for example, https:// YOUR_ESPO_DOMAIN /#Contact/view/{ACCOUNT_ID} .
   3. Click Save. ## Configure API endpoints

Configure endpoints that are compatible with EspoCRM to ensure that your integration has the components for looking up accounts (contacts) and records (cases). For more information about compatible variables, see API Overview in the EspoCRM documentation.

Configure API account endpoints

This section explains how to configure API account endpoints.

Configure a Find an account by query endpoint

To configure the Find an account by query endpoint, follow these steps:

1. In the CCAI Platform, click Settings > Developer Settings. If you don't see the Settingsmenu, click Menu.
2. In the CRMpane, go to the API accountsection.
3. For Find an account by query endpoint, click Setup. The Generic API Endpoint Setuppage appears.
4. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Contact .
5. For Method, select GET.

6. To configure request parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. Click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter where[0][attribute] .
      3. In the Field Valuefield, enter phoneNumber .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous steps using the information in the following table. You've already created the first request parameter.

      Field Key	Field Value
      where[0][attribute]	phoneNumber
      where[0][type]	equals
      where[0][value]	{PHONE_NUMBER}
      sortBy	createdAt
      asc	false

7. In the Response Data Locationfield, enter data.list .

8. Click Save.

9. Click Back to Developer Settingsto return to the Developer Settingspage.

Configure a Find an account by ID endpoint

To configure the Find an account by ID endpoint, follow these steps:

1. In the CRMpane, go to the API accountsection.
2. For Find an account by ID endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Contact/{ACCOUNT_ID} .
   1. For Method, select GET.
4. Set the Response Data Locationto data .
5. Click Save.
6. Click Return to developer settingsto return to the Developer Settingspage.

Configure a Create an account endpoint

To configure the Create an account endpoint, follow these steps:

1. In the CRMpane, go to the API accountsection.
2. For Create an account endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Contact .
4. For Method, select POST.

5. To configure Request Parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. For Request Parameters, click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter phoneNumber .
      3. In the Field Valuefield, enter {PHONE_NUMBER} .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous step, using the information in the following table. You've already created the first request parameter.

      Parameter Key	Parameter Value
      phoneNumber	{PHONE_NUMBER}
      firstName	New Caller
      lastName	{CALL_ID}
      name	New Caller {CALL_ID}

6. Set the Response data locationto data .

7. Set the Object ID locationto id .

8. Click Save.

9. Click Return to developer settingsto return to the Developer Settingspage.

Configure an Update an account endpoint

To configure the Update an account endpoint, follow these steps:

1. In the CRMpane, go to the API accountsection.
2. For Update an account endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Contact .
4. For Method, select PUT.

5. To configure Request Parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. For Request Parameters, click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter contactId .
      3. In the Field Valuefield, enter {PHONE_NUMBER} .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous step, using the information in the following table. You've already created the first request parameter.

      Parameter Key	Parameter Value
      contactId	{PHONE_NUMBER}
      phoneNumber	New Caller

6. Set the Response data locationto data .

7. Click Save.

8. Click Return to developer settingsto return to the Developer Settingspage.

Configure API record endpoints

This section explains how to configure API record endpoints.

Configure a Find a record by query endpoint

To configure the Find a record by query endpoint, follow these steps:

1. In the CRMpane, go to the API recordsection.
2. For Find a record by query endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Case .
4. For Method, select GET.

5. To configure Request Parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. For Request Parameters, click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter where[0][attribute] .
      3. In the Field Valuefield, enter contactId .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous step, using the information in the following table. You've already created the first request parameter.

      Field Key	Field Value
      where[0][attribute]	contactId
      where[0][type]	equals
      where[0][value]	{ACCOUNT_ID}
      contactId	{ACCOUNT_ID}
      sortBy	createdAt
      asc	false

6. In the Response Data Locationfield, enter data.list .

7. Click Save.

8. Click Return to developer settingsto return to the Developer Settingspage.

Configure a Find a record by ID endpoint

Often used in SDK based interactions, this lets you pass a specific record ID to associate the interaction with. To configure the Find a record by ID endpoint, follow these steps:

1. In the CRMpane, go to the API recordsection.
2. For Find a record by ID endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Case/{RECORD_ID} .
4. For Method, select GET.
5. In the Response Data Locationfield, enter data .
6. Click Save.
7. Click Return to developer settingsto return to the Developer Settingspage.

Configure a Create a record endpoint

To configure the Create a record endpoint, follow these steps:

1. In the CRMpane, go to the API recordsection.
2. For Create a record endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Case .
4. For Method, select POST.

5. To configure Request Parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. For Request Parameters, click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter description .
      3. In the Field Valuefield, enter CALL Session:{CALL_ID} .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous step, using the information in the following table. You've already created the first request parameter.

      Parameter Key	Parameter Value
      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. In the Response Data Locationfield, enter data .

7. In the Object ID Locationfield, enter id .

8. Click Save.

9. Click Return to developer settingsto return to the Developer Settingspage.

Configure an Update a record endpoint

To configure the Update a record endpoint, follow these steps:

1. In the CRMpane, go to the API recordsection.
2. For Update a record endpoint, click Setup. The Generic API Endpoint Setuppage appears.
3. In the URLfield, enter the URL to look up an account–for example, https:// YOUR_ESPO_DOMAIN /api/v1/Case/{RECORD_ID} .
4. For Method, select PUT.

5. To configure Request Parameters, do the following:

   1. To configure the first request parameter, follow these steps:
      1. For Request Parameters, click Add field. The Add Fielddialog appears.
      2. In the Field Keyfield, enter parentId .
      3. In the Field Valuefield, enter {RECORD_ID} .
      4. Click Save.

   2. To configure the rest of the request parameters, repeat the previous step, using the information in the following table. You've already created the first request parameter.

      Parameter Key	Parameter Value
      parentId	{RECORD_ID}
      parentType	Case
      status	New
      description	{TICKET_DESCRIPTION}

6. In the Response data locationfield, enter data .

7. Click Save.

8. Click Return to developer settingsto return to the Developer Settingspage.