> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt. # EspoCRM Con gli [strumenti webhook](/docs/it/reception-ai/integrations/webhooks) 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**. > **Warning** > > 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](/docs/it/reception-ai/receptionist/testing) come nuovo chiamante che richiede un preventivo. Il lead appare in EspoCRM con lo stato **New** e l'origine **Call**. > **Tip** > > Aggiungi una [procedura](/docs/it/reception-ai/receptionist/rules-and-procedures) affinché il tuo receptionist > effettui prima una ricerca e aggiunga un lead solo quando non trova corrispondenze. > **Warning** > > 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**. |