Implementación de referencia de EspoCRM

En este documento, se proporciona un ejemplo de integración con un CRM personalizado de Contact Center AI Platform (CCAI Platform) que usa EspoCRM. EspoCRM es una aplicación de CRM de código abierto y gratuita que ayuda a las empresas a administrar las ventas, el marketing y la asistencia al cliente con una interfaz personalizable. Ofrece funciones como administración de contactos, seguimiento de actividades, automatización de ventas y administración de inventario, con opciones para el alojamiento propio o la implementación en la nube.

Para configurar tu propia instancia de EspoCRM, consulta la página de instalación de EspoCRM.

Antes de comenzar

Haz lo siguiente:

• Configura tu firewall para permitir el tráfico de la Plataforma de la CCAI.

• Crea un usuario de la API en tu instancia de EspoCRM, por ejemplo, google_integration_user. Para obtener más información, consulta la API en la documentación de EspoCRM.

• Crea un rol en tu instancia de EspoCRM con las acciones Crear, Leer y Actualizar que acceden a lo siguiente:

  • Contactos: Para encontrar o crear llamantes
  • Cases: Para buscar y registrar tickets

  Para obtener más información, consulta Administración de roles en la documentación de ExpoCRM.

Importante: Asegúrate de que todos los extremos de API que configures usen un certificado TLS válido.

Configura una conexión de EspoCRM a CCAI Platform

Para configurar una conexión de EspoCRM a CCAI Platform, sigue estos pasos:

1. En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador. Si no ves el menú Configuración, haz clic en Menú.
2. En Agent Platform, selecciona Custom CRM.
3. Haz clic en el botón de activación Mostrar CRM en el portal de la plataforma de CCAI para activarlo.
4. En el campo URL visible, ingresa la URL que se incorporará en el portal de CCAI Platform, por ejemplo, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
5. En Método de búsqueda de CRM, selecciona API genérica.
6. Para autenticarte con un encabezado personalizado, haz lo siguiente:
   1. En la sección Authentication Method, selecciona Custom Header.
   2. Haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      1. En el campo Clave del campo, ingresa X-Api-Key.
      2. En el campo Field Value, ingresa la clave de API que se generó cuando creaste un usuario de API en tu EspoCRM.
      3. Haz clic en Guardar.
7. Para establecer la URL de búsqueda del CRM, haz lo siguiente:
   1. En la sección URL de búsqueda de CRM, en el campo URL de búsqueda de registros, ingresa la URL para buscar un registro, por ejemplo, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
   2. En el campo URL de búsqueda de la cuenta, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}.
   3. Haz clic en Guardar. ## Configura los extremos de la API

Configura extremos compatibles con EspoCRM para asegurarte de que tu integración tenga los componentes necesarios para buscar cuentas (contactos) y registros (casos). Para obtener más información sobre las variables compatibles, consulta Descripción general de la API en la documentación de EspoCRM.

Configura los extremos de la cuenta de la API

En esta sección, se explica cómo configurar los extremos de la cuenta de la API.

Configura un extremo de Find an account by query

Para configurar el extremo de Find an account by query, sigue estos pasos:

1. En la CCAI Platform, haz clic en Settings > Developer Settings. Si no ves el menú Configuración, haz clic en Menú.
2. En el panel CRM, ve a la sección Cuenta de API.
3. En Find an account by query endpoint, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
4. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
5. En Method, selecciona GET.

6. Para configurar los parámetros de la solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. Haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa where[0][attribute].
      3. En el campo Valor del campo, ingresa phoneNumber.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite los pasos anteriores con la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave del campo	Valor del campo
      where[0][attribute]	phoneNumber
      where[0][type]	equals
      where[0][value]	{PHONE_NUMBER}
      sortBy	createdAt
      asc	false

7. En el campo Ubicación de los datos de respuesta, ingresa data.list.

8. Haz clic en Guardar.

9. Haz clic en Volver a Configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Find an account by ID

Para configurar el extremo Find an account by ID, sigue estos pasos:

1. En el panel CRM, ve a la sección Cuenta de API.
2. En Find an account by ID endpoint, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
   1. En Method, selecciona GET.
4. Establece la Ubicación de los datos de respuesta en data.
5. Haz clic en Guardar.
6. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Create an account

Para configurar el endpoint Create an account, sigue estos pasos:

1. En el panel CRM, ve a la sección Cuenta de API.
2. En Crear un extremo de cuenta, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. En Method, selecciona POST.

5. Para configurar los parámetros de solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. En Parámetros de la solicitud, haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa phoneNumber.
      3. En el campo Valor del campo, ingresa {PHONE_NUMBER}.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite el paso anterior y usa la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave de parámetro	Valor del parámetro
      phoneNumber	{PHONE_NUMBER}
      firstName	New Caller
      lastName	{CALL_ID}
      name	New Caller {CALL_ID}

6. Establece la Ubicación de los datos de respuesta en data.

7. Establece la Ubicación del ID del objeto en id.

8. Haz clic en Guardar.

9. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Update an account

Para configurar el endpoint Update an account, sigue estos pasos:

1. En el panel CRM, ve a la sección Cuenta de API.
2. En Actualiza un extremo de la cuenta, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. En Method, selecciona PUT.

5. Para configurar los parámetros de solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. En Parámetros de la solicitud, haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa contactId.
      3. En el campo Valor del campo, ingresa {PHONE_NUMBER}.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite el paso anterior y usa la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave de parámetro	Valor del parámetro
      contactId	{PHONE_NUMBER}
      phoneNumber	New Caller

6. Establece la Ubicación de los datos de respuesta en data.

7. Haz clic en Guardar.

8. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura los extremos de registro de la API

En esta sección, se explica cómo configurar los extremos de registro de la API.

Configura un extremo de Find a record by query

Para configurar el extremo Find a record by query, sigue estos pasos:

1. En el panel CRM, ve a la sección Registro de API.
2. En Find a record by query endpoint, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. En Method, selecciona GET.

5. Para configurar los parámetros de solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. En Parámetros de la solicitud, haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa where[0][attribute].
      3. En el campo Valor del campo, ingresa contactId.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite el paso anterior y usa la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave del campo	Valor del campo
      where[0][attribute]	contactId
      where[0][type]	equals
      where[0][value]	{ACCOUNT_ID}
      contactId	{ACCOUNT_ID}
      sortBy	createdAt
      asc	false

6. En el campo Ubicación de los datos de respuesta, ingresa data.list.

7. Haz clic en Guardar.

8. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Find a record by ID

Se usa a menudo en las interacciones basadas en el SDK y te permite pasar un ID de registro específico para asociar la interacción. Para configurar el extremo Find a record by ID, sigue estos pasos:

1. En el panel CRM, ve a la sección Registro de API.
2. En Find a record by ID endpoint, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. En Method, selecciona GET.
5. En el campo Ubicación de los datos de respuesta, ingresa data.
6. Haz clic en Guardar.
7. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Create a record

Para configurar el endpoint de Create a record, sigue estos pasos:

1. En el panel CRM, ve a la sección Registro de API.
2. En Crear un extremo de registro, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. En Method, selecciona POST.

5. Para configurar los parámetros de solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. En Parámetros de la solicitud, haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa description.
      3. En el campo Valor del campo, ingresa CALL Session:{CALL_ID}.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite el paso anterior y usa la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave de parámetro	Valor del parámetro
      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. En el campo Ubicación de los datos de respuesta, ingresa data.

7. En el campo Ubicación del ID del objeto, ingresa id.

8. Haz clic en Guardar.

9. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.

Configura un extremo de Update a record

Para configurar el endpoint Update a record, sigue estos pasos:

1. En el panel CRM, ve a la sección Registro de API.
2. En Update a record endpoint, haz clic en Configuración. Aparecerá la página Configuración genérica del extremo de la API.
3. En el campo URL, ingresa la URL para buscar una cuenta, por ejemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. En Method, selecciona PUT.

5. Para configurar los parámetros de solicitud, haz lo siguiente:

   1. Para configurar el primer parámetro de la solicitud, sigue estos pasos:
      1. En Parámetros de la solicitud, haz clic en Agregar campo. Aparecerá el cuadro de diálogo Agregar campo.
      2. En el campo Clave del campo, ingresa parentId.
      3. En el campo Valor del campo, ingresa {RECORD_ID}.
      4. Haz clic en Guardar.

   2. Para configurar el resto de los parámetros de la solicitud, repite el paso anterior y usa la información de la siguiente tabla. Ya creaste el primer parámetro de la solicitud.

      Clave de parámetro	Valor del parámetro
      parentId	{RECORD_ID}
      parentType	Case
      status	New
      description	{TICKET_DESCRIPTION}

6. En el campo Ubicación de los datos de respuesta, ingresa data.

7. Haz clic en Guardar.

8. Haz clic en Volver a la configuración para desarrolladores para regresar a la página Configuración para desarrolladores.