Implementazione di riferimento di EspoCRM

Questo documento fornisce un esempio di integrazione con il CRM personalizzato Contact Center AI Platform (CCAI Platform) utilizzando EspoCRM. EspoCRM è un'applicazione CRM senza costi e open source che aiuta le aziende a gestire le vendite, il marketing e l'assistenza clienti con un'interfaccia personalizzabile. Offre funzionalità come la gestione dei contatti, il monitoraggio delle attività, l'automazione delle vendite e la gestione dell'inventario, con opzioni per l'hosting autonomo o il deployment sul cloud.

Per configurare la tua istanza di EspoCRM, consulta la pagina di installazione di EspoCRM.

Prima di iniziare

Segui questi passaggi:

• Configura il firewall per consentire il traffico dalla piattaforma CCAI.

• Crea un utente API nell'istanza EspoCRM, ad esempio google_integration_user. Per saperne di più, consulta l'API nella documentazione di EspoCRM.

• Crea un ruolo nell'istanza EspoCRM con le azioni Crea, Leggi e Aggiorna che accedono a quanto segue:

  • Contatti: per trovare o creare chiamanti
  • Casi: per cercare e registrare i ticket

  Per saperne di più, consulta Gestione dei ruoli nella documentazione di ExpoCRM.

Importante: assicurati che tutti gli endpoint API che configuri utilizzino un certificato TLS valido.

Configura una connessione da EspoCRM a CCAI Platform

Per configurare una connessione da EspoCRM a CCAI Platform:

1. Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
2. In Agent Platform (Piattaforma agente), seleziona Custom CRM (CRM personalizzato).
3. Fai clic sul pulsante di attivazione/disattivazione Visualizza CRM nel portale della piattaforma CCAI per attivarlo.
4. Nel campo URL di visualizzazione, inserisci l'URL da incorporare nel portale della piattaforma CCAI, ad esempio, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
5. Per Metodo di ricerca CRM, seleziona API generica.
6. Per eseguire l'autenticazione utilizzando un'intestazione personalizzata:
   1. Nella sezione Authentication Method (Metodo di autenticazione), seleziona Custom Header (Intestazione personalizzata).
   2. Fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      1. Nel campo Chiave campo, inserisci X-Api-Key.
      2. Nel campo Valore campo, inserisci la chiave API generata quando hai creato un utente API in EspoCRM.
      3. Fai clic su Salva.
7. Per impostare l'URL di ricerca CRM:
   1. Nella sezione URL di ricerca CRM, nel campo URL di ricerca record, inserisci l'URL per cercare un record, ad esempio, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
   2. Nel campo URL di ricerca account, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}.
   3. Fai clic su Salva. ## Configura gli endpoint API

Configura endpoint compatibili con EspoCRM per assicurarti che l'integrazione disponga dei componenti per la ricerca di account (contatti) e record (richieste). Per ulteriori informazioni sulle variabili compatibili, consulta la panoramica dell'API nella documentazione di EspoCRM.

Configurare gli endpoint dell'account API

Questa sezione spiega come configurare gli endpoint dell'account API.

Configura un endpoint Trova un account tramite query

Per configurare l'endpoint Trova un account tramite query:

1. Nella piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.
2. Nel riquadro CRM, vai alla sezione Account API.
3. Per Trova un account tramite l'endpoint di query, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
4. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Contact.
5. In Metodo, seleziona GET.

6. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci where[0][attribute].
      3. Nel campo Valore campo, inserisci phoneNumber.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti i passaggi precedenti utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave campo	Valore campo
      where[0][attribute]	phoneNumber
      where[0][type]	equals
      where[0][value]	{PHONE_NUMBER}
      sortBy	createdAt
      asc	false

7. Nel campo Response Data Location (Località dei dati di risposta), inserisci data.list.

8. Fai clic su Salva.

9. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura un endpoint Trova un account per ID

Per configurare l'endpoint Trova un account per ID:

1. Nel riquadro CRM, vai alla sezione Account API.
2. Per Trova un account per ID endpoint, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
   1. In Metodo, seleziona GET.
4. Imposta Località dei dati delle risposte su data.
5. Fai clic su Salva.
6. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configurare un endpoint Crea un account

Per configurare l'endpoint Crea un account:

1. Nel riquadro CRM, vai alla sezione Account API.
2. Per Crea un endpoint dell'account, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. In Metodo, seleziona POST.

5. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Per Parametri richiesta, fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci phoneNumber.
      3. Nel campo Valore campo, inserisci {PHONE_NUMBER}.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti il passaggio precedente utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave parametro	Valore parametro
      phoneNumber	{PHONE_NUMBER}
      firstName	New Caller
      lastName	{CALL_ID}
      name	New Caller {CALL_ID}

6. Imposta Posizione dei dati delle risposte su data.

7. Imposta Posizione ID oggetto su id.

8. Fai clic su Salva.

9. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura un endpoint Aggiorna un account

Per configurare l'endpoint Aggiorna un account:

1. Nel riquadro CRM, vai alla sezione Account API.
2. Per Aggiorna un endpoint dell'account, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. Per Metodo, seleziona PUT.

5. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Per Parametri richiesta, fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci contactId.
      3. Nel campo Valore campo, inserisci {PHONE_NUMBER}.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti il passaggio precedente utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave parametro	Valore parametro
      contactId	{PHONE_NUMBER}
      phoneNumber	New Caller

6. Imposta Posizione dei dati delle risposte su data.

7. Fai clic su Salva.

8. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura gli endpoint dei record API

Questa sezione spiega come configurare gli endpoint dei record API.

Configura un endpoint Trova un record tramite query

Per configurare l'endpoint Trova un record tramite query:

1. Nel riquadro CRM, vai alla sezione Record API.
2. Per Trova un record per endpoint di query, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. In Metodo, seleziona GET.

5. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Per Parametri richiesta, fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci where[0][attribute].
      3. Nel campo Valore campo, inserisci contactId.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti il passaggio precedente utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave campo	Valore campo
      where[0][attribute]	contactId
      where[0][type]	equals
      where[0][value]	{ACCOUNT_ID}
      contactId	{ACCOUNT_ID}
      sortBy	createdAt
      asc	false

6. Nel campo Response Data Location (Località dei dati di risposta), inserisci data.list.

7. Fai clic su Salva.

8. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura un endpoint Trova un record per ID

Spesso utilizzato nelle interazioni basate su SDK, consente di passare un ID record specifico a cui associare l'interazione. Per configurare l'endpoint Trova un record per ID, segui questi passaggi:

1. Nel riquadro CRM, vai alla sezione Record API.
2. Per Trova un record per ID endpoint, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. In Metodo, seleziona GET.
5. Nel campo Response Data Location (Località dei dati di risposta), inserisci data.
6. Fai clic su Salva.
7. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura un endpoint Crea un record

Per configurare l'endpoint Crea un record:

1. Nel riquadro CRM, vai alla sezione Record API.
2. Per Crea un endpoint di record, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. In Metodo, seleziona POST.

5. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Per Parametri richiesta, fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci description.
      3. Nel campo Valore campo, inserisci CALL Session:{CALL_ID}.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti il passaggio precedente utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave parametro	Valore parametro
      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. Nel campo Response Data Location (Località dei dati di risposta), inserisci data.

7. Nel campo Posizione ID oggetto, inserisci id.

8. Fai clic su Salva.

9. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.

Configura un endpoint Aggiorna un record

Per configurare l'endpoint Aggiorna un record:

1. Nel riquadro CRM, vai alla sezione Record API.
2. Per Aggiorna un endpoint di record, fai clic su Configurazione. Viene visualizzata la pagina Configurazione endpoint API generico.
3. Nel campo URL, inserisci l'URL per cercare un account, ad esempio https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. Per Metodo, seleziona PUT.

5. Per configurare i parametri della richiesta:

   1. Per configurare il primo parametro della richiesta, segui questi passaggi:
      1. Per Parametri richiesta, fai clic su Aggiungi campo. Viene visualizzata la finestra di dialogo Aggiungi campo.
      2. Nel campo Chiave campo, inserisci parentId.
      3. Nel campo Valore campo, inserisci {RECORD_ID}.
      4. Fai clic su Salva.

   2. Per configurare il resto dei parametri della richiesta, ripeti il passaggio precedente utilizzando le informazioni riportate nella tabella seguente. Hai già creato il primo parametro della richiesta.

      Chiave parametro	Valore parametro
      parentId	{RECORD_ID}
      parentType	Case
      status	New
      description	{TICKET_DESCRIPTION}

6. Nel campo Posizione dei dati di risposta, inserisci data.

7. Fai clic su Salva.

8. Fai clic su Torna alle impostazioni sviluppatore per tornare alla pagina Impostazioni sviluppatore.