EspoCRM | ElevenLabs Documentation

Con gli strumenti webhook qui sotto, il tuo receptionist può riconoscere i chiamanti già presenti in EspoCRM e aggiungere nuovi chiamanti come lead, includendo nome, numero di telefono e richieste, così il tuo team può ricontattarli. L’API di EspoCRM utilizza una chiave API statica e body delle richieste JSON, quindi funziona allo stesso modo sia per EspoCRM Cloud sia per le installazioni self-hosted.

Prima di iniziare

Crea un ruolo

In EspoCRM, vai a Amministrazione → Ruoli e crea un ruolo in grado di leggere e creare Lead e leggere Contatti. Lascia disabilitati tutti gli altri ambiti.

Crea un utente API

Vai a Amministrazione → Utenti API e crea un utente. Imposta il metodo di autenticazione su Chiave API e assegna il ruolo appena creato. Salva, quindi copia la chiave API dalla vista dettagli dell’utente.

Ogni strumento qui sotto invia la chiave in un header della richiesta denominato X-Api-Key. Imposta Tipo su Secret.

La chiave API può leggere e modificare tutto ciò che il suo ruolo consente. Mantieni il ruolo limitato e rigenera la chiave in EspoCRM se viene compromessa.

Trova l’indirizzo di EspoCRM

Gli URL dei tuoi strumenti iniziano con l’indirizzo che apri nel browser per usare EspoCRM, seguito da /api/v1/. Le tabelle qui sotto usano https://YOUR-CRM.example.com; sostituiscilo con il tuo.

Crea gli strumenti

Per ogni strumento, vai a Integrazioni, seleziona Aggiungi integrazione, scegli Strumento webhook e imposta Assegna agli agenti su Receptionist. Imposta Valore su Valore fisso per ogni parametro contrassegnato con “Sempre” qui sotto.

Trova un lead

Campo	Valore
Nome	`find_espocrm_lead`
Descrizione	”Trova il chiamante tra i nostri lead in base al numero di telefono. Usalo all’inizio di una chiamata per verificare se ci ha già contattato.”
Metodo	GET
URL	`https://YOUR-CRM.example.com/api/v1/Lead`
Header richiesta	`X-Api-Key`: la tua chiave API
Parametri query	`textFilter` (stringa, obbligatorio): “Il numero di telefono del chiamante con il prefisso internazionale, ad esempio +14155550123.” `select` (stringa): Sempre `id,name,status`. `maxSize` (intero): Sempre `5`.

Per riconoscere anche i clienti esistenti, crea un secondo strumento denominato find_espocrm_contact con le stesse impostazioni e l’URL https://YOUR-CRM.example.com/api/v1/Contact.

Aggiungi un nuovo lead

Campo	Valore
Nome	`create_espocrm_lead`
Descrizione	”Aggiungi il chiamante come nuovo lead quando `find_espocrm_lead` non lo trova.”
Metodo	POST
URL	`https://YOUR-CRM.example.com/api/v1/Lead`
Header richiesta	`X-Api-Key`: la tua chiave API
Parametri body	`firstName` (stringa, obbligatorio): “Il nome del chiamante.” `lastName` (stringa, obbligatorio): “Il cognome del chiamante.” `phoneNumber` (stringa, obbligatorio): “Il numero di telefono del chiamante in formato internazionale, ad esempio +14155550123.” `emailAddress` (stringa): “L’indirizzo email del chiamante, se lo ha fornito.” `description` (stringa, obbligatorio): “Di cosa ha bisogno il chiamante e quando desidera essere richiamato.” `status` (stringa): Sempre `New`. `source` (stringa): Sempre `Call`.

Per assegnare i nuovi lead a un unico commerciale, aggiungi assignedUserId (stringa) come valore fisso con l’ID di quell’utente. Puoi vedere l’ID nella barra degli indirizzi quando apri l’utente in EspoCRM.

Seleziona Abilita su ogni strumento, quindi testa il tuo receptionist come nuovo chiamante che richiede un preventivo. Il lead appare in EspoCRM con lo stato New e l’origine Call.

Aggiungi una procedura affinché il tuo receptionist effettui prima una ricerca e aggiunga un lead solo quando non trova corrispondenze.

La ricerca trova corrispondenze anche nei nomi e negli indirizzi email, quindi un chiamante potrebbe provare a cercare qualcun altro. Aggiungi una regola che impedisca al tuo receptionist di leggere ai chiamanti i record del CRM e mantieni select limitato a id,name,status.

Limitazioni

textFilter usa la stessa ricerca della casella di ricerca di EspoCRM: cerca nei nomi, negli indirizzi email e nei numeri di telefono. Una ricerca per numero di telefono può trovare anche un record diverso il cui numero inizia con le stesse cifre, quindi il tuo receptionist dovrebbe confermare il nome del chiamante.
Con questi strumenti, il tuo receptionist non può aggiungere una nota o un’attività a un lead o contatto esistente. La descrizione del nuovo lead contiene i dettagli della chiamata.
Gli strumenti non impostano i team. EspoCRM gestisce i team come elenco di ID team (teamsIds) e uno strumento webhook compila sempre un elenco dalla conversazione, quindi non può inserire ogni lead nello stesso team e il tuo receptionist non dovrebbe scegliere i team. Usa invece assignedUserId per indirizzare i lead.

Risoluzione dei problemi

Problema	Cosa verificare
401 da EspoCRM	L’header deve essere denominato `X-Api-Key` e contenere la chiave dalla vista dettagli dell’utente API. Verifica che l’utente API sia attivo.
403 da EspoCRM	Il ruolo dell’utente API non può leggere o creare lead. Modifica il ruolo in Amministrazione → Ruoli.
409 durante l’aggiunta di un lead	EspoCRM ha trovato un possibile duplicato, ad esempio un lead con lo stesso nome o indirizzo email. Il tuo receptionist dovrebbe prima effettuare una ricerca.
I chiamanti noti non vengono trovati	Salva i numeri di telefono in formato internazionale, ad esempio `+14155550123`, e verifica che il numero sia associato a un lead o contatto, non solo a un account.
Errori di `status` o `source`	I valori devono corrispondere esattamente alle opzioni Stato e Origine dei lead, configurate in Amministrazione → Gestore entità → Lead.