Centro assistenza Aircall | Configura l'instradamento intelligente verso il proprietario del contatto Zendesk usando il widget Ring-to (tramite API) in un flusso di chiamata

Configura l'instradamento intelligente su un numero di telefono condiviso per fare in modo che i chiamanti vengano messi in contatto in modo efficiente con il proprio referente utilizzando il widget Inoltra a (tramite API) in un flusso di chiamata, con autenticazione OAuth di Zendesk.

Nota: Zendesk sta ritirando i token API come metodo di autenticazione. Questo articolo utilizza OAuth, il metodo sostitutivo. Se attualmente utilizzi un token API per questa configurazione, consulta la sezione Perché questo articolo utilizza OAuth anziché un token API qui sotto.

Nota: Il video tutorial potrebbe mostrare la versione precedente della sezione Testa la risposta. Per le indicazioni più aggiornate, fai sempre riferimento ai passaggi riportati in questo articolo.

In questa guida scoprirai:

Perché questo articolo utilizza OAuth anziché un token API.
In che modo l'utilizzo del widget Inoltra a (tramite API) migliora l'efficienza e l'esperienza del cliente.
Come configurare l'instradamento intelligente verso il proprietario del contatto Zendesk.
- Passaggio uno: crea il campo utente personalizzato in Zendesk
- Passaggio due: crea un client OAuth riservato in Zendesk
- Passaggio tre: configura il widget Inoltra a (tramite API) nell'editor di flussi
- Passaggio quattro: testa la configurazione

Nota: Il widget Inoltra a (tramite API) è disponibile solo con il piano Professional. Se non hai il piano Professional, contatta il tuo Customer Success Manager (CSM) per ricevere assistenza.

Perché questo articolo utilizza OAuth anziché un token API

Zendesk sta eliminando gradualmente i token API come metodo di autenticazione per le richieste all'API di Supporto, a favore di OAuth. I token API esistenti continueranno a funzionare durante un periodo di transizione, ma Zendesk finirà per disattivarli completamente.

Importante: Se questo instradamento funziona già con un token API, non aspettare che smetta di funzionare. Crea la configurazione OAuth in un secondo widget Inoltra a (tramite API), verifica che funzioni e solo dopo passa il widget attivo alla nuova configurazione. Consulta la sezione "Attivazione" qui sotto per i passaggi necessari alla migrazione.

Il widget Inoltra a (tramite API) esegue l'autenticazione su Zendesk utilizzando la concessione delle credenziali client OAuth. Aircall richiede un token di accesso dal tuo conto Zendesk utilizzando l'ID client e il segreto client, quindi invia il token all'API Zendesk come intestazione Authorization: Bearer. Aircall memorizza il token nella cache e ne richiede automaticamente uno nuovo alla scadenza, quindi non è necessario cambiare manualmente alcun token.

Nota: Per conoscere la tempistica esatta prevista da Zendesk per il ritiro, consulta l'annuncio di Zendesk sulla rimozione dei token API.

In che modo l'utilizzo del widget Inoltra a (tramite API) migliora l'efficienza e l'esperienza del cliente

L'instradamento intelligente su un numero di telefono condiviso offre vantaggi significativi, migliorando l'efficienza, la precisione e l'esperienza del cliente. Indirizzando in modo intelligente le chiamate in entrata in base ai dati del CRM, l'instradamento intelligente assicura che ogni chiamante venga messo rapidamente in contatto con l'agente più adatto, riducendo i tempi di attesa e migliorando i tassi di risoluzione alla prima chiamata.

Un caso d'uso comune del widget Inoltra a (tramite API) di Aircall in un flusso di chiamata consiste nell'indirizzare i chiamanti VIP in entrata direttamente al proprietario del contatto Zendesk (l'agente dedicato del Supporto clienti). In questo modo si evita che l'intero Team venga interrotto da chiamate di clienti non pertinenti e non è più necessario mettere i chiamanti in attesa durante il trasferimento all'agente assegnato.

Come configurare l'instradamento intelligente verso il proprietario del contatto Zendesk

Passaggio uno: crea il campo personalizzato in Zendesk

Importante: Questo passaggio richiede familiarità con i campi personalizzati e i metodi di autenticazione di Zendesk.

Inizia in Zendesk creando una proprietà personalizzata per memorizzare l'indirizzo e-mail del proprietario del contatto.

Nel Centro amministrativo Zendesk, vai a Persone → Configurazione → Campi utente e seleziona Aggiungi campo.
- Tipo di campo: Testo
- Nome visualizzato: E-mail del proprietario
- Chiave del campo: owner_email
Il campo verrà aggiunto automaticamente a tutti i profili degli utenti finali. Dopo averlo creato e reso visibile nel profilo dell'utente finale, compilalo con un indirizzo e-mail. Ti servirà in seguito per testare la validità del percorso nel widget Inoltra a (tramite API).

Nota: L'indirizzo e-mail inserito deve corrispondere a quello di un utente Aircall esistente, altrimenti non sarà possibile instradargli la chiamata.

Passaggio due: crea un client OAuth riservato in Zendesk

Importante: La concessione delle credenziali client è disponibile solo per i client OAuth riservati. Per questa configurazione non è possibile utilizzare un client pubblico. Per creare un client OAuth sono necessari i diritti di amministratore Zendesk.

Nel Centro amministrativo Zendesk, vai a App e integrazioni > API > Client OAuth, quindi fai clic su Aggiungi client OAuth.
Compila i campi:
- Nome: un nome a tua scelta, ad esempio "Aircall - Instrada a (tramite API)"
- Identificatore: compilato automaticamente in base al nome. Questo valore è il tuo ID client. Se vuoi, puoi modificarlo.
- Tipo di client: Riservato. È obbligatorio.
- URL di reindirizzamento: la concessione delle credenziali client non utilizza questo valore. Se non è possibile salvare il modulo senza un URL, inserisci un URL HTTPS assoluto, ad esempio https://localhost.
- Ambiti: facoltativo. Se lasci vuoto questo campo, il client può richiedere qualsiasi ambito. Se lo imposti, rappresenta un limite massimo: il widget non può richiedere un ambito non incluso in questo elenco. In tal caso, includi l'ambito che inserirai nel widget al passaggio tre.
- Fai scadere i token: puoi lasciare questa opzione invariata. Per i client OAuth creati a partire dal 30 aprile 2026, la casella di controllo è disabilitata perché, per impostazione predefinita, i token emessi da tali client hanno già una scadenza.
Fai clic su Salva. La pagina si aggiorna e viene visualizzato un campo Segreto.
Copia l'Identificatore e il Segreto e conservali in un luogo sicuro.

Importante: Il Segreto viene visualizzato per intero una sola volta. Dopo aver lasciato la pagina, potrai visualizzarne solo i primi nove caratteri. Se lo perdi, dovrai creare un nuovo client OAuth.

Importante: Le azioni eseguite con un token di credenziali client vengono attribuite all'utente Zendesk che ha creato il client OAuth, solitamente un amministratore. Ciò influisce sui registri di controllo. Significa inoltre che, se in seguito l'utente viene eliminato, sottoposto a downgrade o perde in altro modo le autorizzazioni necessarie per gestire i client OAuth, i token emessi da questo client smettono di funzionare e l'instradamento non riesce. Se uno di questi aspetti è importante per te, prima di continuare crea il client OAuth da un account di servizio dedicato.

Passaggio tre: configura il widget Instrada a (tramite API) nell'editor di flussi

Importante: Questo passaggio richiede familiarità con l'API REST di Zendesk e i flussi di chiamata.

Vai a Dashboard Aircall > Numeri e apri il numero del flusso di chiamata da configurare.

È importante notare che gli utenti Aircall ai quali verranno instradate le chiamate tramite l'API non devono essere assegnati alla configurazione del flusso di chiamata. Se sono assegnati, qualora non rispondano alla chiamata trasferita riceveranno le relative notifiche di chiamata persa nella Lista delle cose da fare. Tuttavia, non riceveranno queste notifiche se non sono assegnati al numero.

Vai al numero di telefono per il quale desideri configurare il widget Instrada a (tramite API). Aggiungi il widget Instrada a (tramite API) nel punto desiderato della configurazione del flusso di chiamata per aprire l'editor del widget.

Imposta Autenticazione su OAuth, quindi fai clic su Imposta credenziali. Compila il modulo delle credenziali come segue:

URL di accesso	`https://MyDomainName.zendesk.com/oauth/tokens` (sostituisci `MyDomainName` con il tuo sottodominio Zendesk; utilizza il sottodominio Zendesk principale, non un dominio con mapping dell'host)
ID client	L'Identificatore del tuo client OAuth
Segreto client	Il Segreto del tuo client OAuth
Ambito	`users:read read` per iniziare. Zendesk non pubblica una mappatura tra ambiti ed endpoint, quindi considera questo valore un punto di partenza e verificalo con il test del passaggio quattro. Se il test restituisce un errore relativo all'ambito, Zendesk indica i nomi degli ambiti richiesti: inseriscili esattamente come indicato.

Alcuni suggerimenti per configurare OAuth:
- Scegli prima il valore di Autenticazione, quindi inserisci le credenziali. Se modifichi l'opzione Autenticazione, tutte le credenziali già memorizzate nel widget vengono cancellate e dovrai inserirle nuovamente.
- Se nel modulo delle credenziali OAuth non visualizzi il campo Ambito, aggiorna la Dashboard Aircall. Il campo Ambito è obbligatorio per Zendesk e, se non è presente, Zendesk rifiuta la richiesta del token.
- Ambito è un elenco separato da spazi. Cerca di utilizzare l'insieme più ristretto possibile che funzioni. È stato osservato che Zendesk richiede un ambito generico "read" insieme all'ambito specifico della risorsa, motivo per cui sopra viene suggerito "users:read read".

Torna all'editor del widget e completa la configurazione della richiesta:
- URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
  (Sostituisci “MyDomainName” con il nome di dominio Zendesk effettivo.)
- Metodo: GET
Configura le impostazioni della risposta come segue:
- Tipo di risposta: Utente (ID o e-mail)
- Percorso: users[0].user_fields.owner_email

Passaggio 4: verifica la configurazione

Esegui una verifica nell'apposito campo Verifica risposta:

Inserisci un numero di telefono valido nel formato internazionale E.164.
Assicurati che venga restituito un payload JSON.
Verifica che il Percorso sia valido per trovare il valore utilizzato per instradare la chiamata in entrata.
Verifica che l'indirizzo e-mail del contatto esistente corrisponda a quello di un utente Aircall esistente.

Suggerimento: Modifica le impostazioni di squillo direttamente sotto il campo di verifica in base alle esigenze operative della tua azienda.

Ora puoi iniziare a verificare le chiamate in entrata per l'instradamento intelligente al proprietario del contatto Zendesk tramite il widget Ring-to (via API).

Passaggio alla produzione

Una volta completate le verifiche e confermato che l'instradamento funziona come previsto, assicurati di compilare il campo E-mail del proprietario in Zendesk per ogni profilo utente finale per il quale desideri instradare automaticamente le chiamate.

Se in precedenza autenticavi questo widget con un token API, passa ora alle credenziali OAuth nel widget in produzione e rimuovi il vecchio token API dal Centro amministrativo Zendesk dopo aver confermato che la configurazione OAuth funziona.

Risoluzione dei problemi

Problema	Causa e soluzione
Errore durante la richiesta del token di accesso oppure HTTP 401 durante la ricerca	Le credenziali sono state rifiutate. Verifica che il client OAuth sia Riservato e che l'ID client corrisponda esattamente all'Identificatore. Se il Segreto è stato copiato nuovamente dopo aver lasciato la pagina del Centro amministrativo, viene troncato a nove caratteri: crea un nuovo client e utilizza il Segreto completo.
Una singola verifica o chiamata non riesce, ma la stessa verifica riesce subito dopo	Questo può accadere nel momento in cui un token di accesso memorizzato nella cache scade e viene rinnovato. Riprova la verifica. Se il problema si ripresenta regolarmente anziché occasionalmente, consideralo un effettivo problema di credenziali o ambito e segui le indicazioni nelle righe seguenti.
`{"error":"Forbidden","description":"You are missing the following required scopes: ..."}`	Il token è stato emesso, ma non include l'ambito necessario per l'endpoint. Modifica le credenziali OAuth del widget e imposta Ambito sugli ambiti indicati nel messaggio di errore.
HTTP 400 con `invalid_scope`	L'ambito richiesto dal widget non è incluso nell'elenco Ambiti configurato nel client OAuth in Zendesk. Aggiungi l'ambito agli ambiti consentiti del client oppure modifica l'Ambito del widget affinché rientri tra questi.
Le credenziali sembrano essere state cancellate	La modifica dell'opzione Autenticazione cancella le credenziali memorizzate. Inseriscile nuovamente dopo aver selezionato il metodo.
La verifica restituisce un payload, ma la chiamata non viene instradata	Il valore nel Percorso configurato deve corrispondere a un utente Aircall esistente. Verifica che il valore E-mail del proprietario nel profilo Zendesk corrisponda all'indirizzo e-mail di un utente Aircall.
L'instradamento funzionava in precedenza, ma si è interrotto senza alcuna modifica alla configurazione	Verifica che l'utente Zendesk che ha creato il client OAuth esista ancora e disponga ancora dell'autorizzazione per gestire i client OAuth. I token delle credenziali client operano per conto di tale utente e smettono di funzionare se l'utente perde questo accesso.

Servizi professionali

Se hai bisogno di ulteriore assistenza per implementare questa configurazione di instradamento intelligente o desideri scoprire automazioni simili per migliorare le tue attività, consulta il nostro team Successo del cliente per prenotare una sessione con i nostri consulenti tecnici.

Nota: Zendesk sta ritirando i token API come metodo di autenticazione. Questo articolo utilizza OAuth, il metodo sostitutivo. Se attualmente utilizzi un token API per questa configurazione, consulta la sezione Perché questo articolo utilizza OAuth anziché un token API qui sotto.

Nota: Il video tutorial potrebbe mostrare la versione precedente della sezione Testa la risposta. Per le indicazioni più aggiornate, fai sempre riferimento ai passaggi riportati in questo articolo.

In questa guida scoprirai:

Perché questo articolo utilizza OAuth anziché un token API.
In che modo l'utilizzo del widget Inoltra a (tramite API) migliora l'efficienza e l'esperienza del cliente.
Come configurare l'instradamento intelligente verso il proprietario del contatto Zendesk.
- Passaggio uno: crea il campo utente personalizzato in Zendesk
- Passaggio due: crea un client OAuth riservato in Zendesk
- Passaggio tre: configura il widget Inoltra a (tramite API) nell'editor di flussi
- Passaggio quattro: testa la configurazione

Nota: Il widget Inoltra a (tramite API) è disponibile solo con il piano Professional. Se non hai il piano Professional, contatta il tuo Customer Success Manager (CSM) per ricevere assistenza.

Perché questo articolo utilizza OAuth anziché un token API

Importante: Se questo instradamento funziona già con un token API, non aspettare che smetta di funzionare. Crea la configurazione OAuth in un secondo widget Inoltra a (tramite API), verifica che funzioni e solo dopo passa il widget attivo alla nuova configurazione. Consulta la sezione "Attivazione" qui sotto per i passaggi necessari alla migrazione.

Nota: Per conoscere la tempistica esatta prevista da Zendesk per il ritiro, consulta l'annuncio di Zendesk sulla rimozione dei token API.

In che modo l'utilizzo del widget Inoltra a (tramite API) migliora l'efficienza e l'esperienza del cliente

Come configurare l'instradamento intelligente verso il proprietario del contatto Zendesk

Passaggio uno: crea il campo personalizzato in Zendesk

Importante: Questo passaggio richiede familiarità con i campi personalizzati e i metodi di autenticazione di Zendesk.

Inizia in Zendesk creando una proprietà personalizzata per memorizzare l'indirizzo e-mail del proprietario del contatto.

Nel Centro amministrativo Zendesk, vai a Persone → Configurazione → Campi utente e seleziona Aggiungi campo.
- Tipo di campo: Testo
- Nome visualizzato: E-mail del proprietario
- Chiave del campo: owner_email
Il campo verrà aggiunto automaticamente a tutti i profili degli utenti finali. Dopo averlo creato e reso visibile nel profilo dell'utente finale, compilalo con un indirizzo e-mail. Ti servirà in seguito per testare la validità del percorso nel widget Inoltra a (tramite API).

Nota: L'indirizzo e-mail inserito deve corrispondere a quello di un utente Aircall esistente, altrimenti non sarà possibile instradargli la chiamata.

Passaggio due: crea un client OAuth riservato in Zendesk

Importante: La concessione delle credenziali client è disponibile solo per i client OAuth riservati. Per questa configurazione non è possibile utilizzare un client pubblico. Per creare un client OAuth sono necessari i diritti di amministratore Zendesk.

Nel Centro amministrativo Zendesk, vai a App e integrazioni > API > Client OAuth, quindi fai clic su Aggiungi client OAuth.
Compila i campi:
- Nome: un nome a tua scelta, ad esempio "Aircall - Instrada a (tramite API)"
- Identificatore: compilato automaticamente in base al nome. Questo valore è il tuo ID client. Se vuoi, puoi modificarlo.
- Tipo di client: Riservato. È obbligatorio.
- URL di reindirizzamento: la concessione delle credenziali client non utilizza questo valore. Se non è possibile salvare il modulo senza un URL, inserisci un URL HTTPS assoluto, ad esempio https://localhost.
- Ambiti: facoltativo. Se lasci vuoto questo campo, il client può richiedere qualsiasi ambito. Se lo imposti, rappresenta un limite massimo: il widget non può richiedere un ambito non incluso in questo elenco. In tal caso, includi l'ambito che inserirai nel widget al passaggio tre.
- Fai scadere i token: puoi lasciare questa opzione invariata. Per i client OAuth creati a partire dal 30 aprile 2026, la casella di controllo è disabilitata perché, per impostazione predefinita, i token emessi da tali client hanno già una scadenza.
Fai clic su Salva. La pagina si aggiorna e viene visualizzato un campo Segreto.
Copia l'Identificatore e il Segreto e conservali in un luogo sicuro.

Importante: Il Segreto viene visualizzato per intero una sola volta. Dopo aver lasciato la pagina, potrai visualizzarne solo i primi nove caratteri. Se lo perdi, dovrai creare un nuovo client OAuth.

Importante: Le azioni eseguite con un token di credenziali client vengono attribuite all'utente Zendesk che ha creato il client OAuth, solitamente un amministratore. Ciò influisce sui registri di controllo. Significa inoltre che, se in seguito l'utente viene eliminato, sottoposto a downgrade o perde in altro modo le autorizzazioni necessarie per gestire i client OAuth, i token emessi da questo client smettono di funzionare e l'instradamento non riesce. Se uno di questi aspetti è importante per te, prima di continuare crea il client OAuth da un account di servizio dedicato.

Passaggio tre: configura il widget Instrada a (tramite API) nell'editor di flussi

Importante: Questo passaggio richiede familiarità con l'API REST di Zendesk e i flussi di chiamata.

Vai a Dashboard Aircall > Numeri e apri il numero del flusso di chiamata da configurare.

È importante notare che gli utenti Aircall ai quali verranno instradate le chiamate tramite l'API non devono essere assegnati alla configurazione del flusso di chiamata. Se sono assegnati, qualora non rispondano alla chiamata trasferita riceveranno le relative notifiche di chiamata persa nella Lista delle cose da fare. Tuttavia, non riceveranno queste notifiche se non sono assegnati al numero.

Vai al numero di telefono per il quale desideri configurare il widget Instrada a (tramite API). Aggiungi il widget Instrada a (tramite API) nel punto desiderato della configurazione del flusso di chiamata per aprire l'editor del widget.

Imposta Autenticazione su OAuth, quindi fai clic su Imposta credenziali. Compila il modulo delle credenziali come segue:

URL di accesso	`https://MyDomainName.zendesk.com/oauth/tokens` (sostituisci `MyDomainName` con il tuo sottodominio Zendesk; utilizza il sottodominio Zendesk principale, non un dominio con mapping dell'host)
ID client	L'Identificatore del tuo client OAuth
Segreto client	Il Segreto del tuo client OAuth
Ambito	`users:read read` per iniziare. Zendesk non pubblica una mappatura tra ambiti ed endpoint, quindi considera questo valore un punto di partenza e verificalo con il test del passaggio quattro. Se il test restituisce un errore relativo all'ambito, Zendesk indica i nomi degli ambiti richiesti: inseriscili esattamente come indicato.

Alcuni suggerimenti per configurare OAuth:
- Scegli prima il valore di Autenticazione, quindi inserisci le credenziali. Se modifichi l'opzione Autenticazione, tutte le credenziali già memorizzate nel widget vengono cancellate e dovrai inserirle nuovamente.
- Se nel modulo delle credenziali OAuth non visualizzi il campo Ambito, aggiorna la Dashboard Aircall. Il campo Ambito è obbligatorio per Zendesk e, se non è presente, Zendesk rifiuta la richiesta del token.
- Ambito è un elenco separato da spazi. Cerca di utilizzare l'insieme più ristretto possibile che funzioni. È stato osservato che Zendesk richiede un ambito generico "read" insieme all'ambito specifico della risorsa, motivo per cui sopra viene suggerito "users:read read".

Torna all'editor del widget e completa la configurazione della richiesta:
- URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
  (Sostituisci “MyDomainName” con il nome di dominio Zendesk effettivo.)
- Metodo: GET
Configura le impostazioni della risposta come segue:
- Tipo di risposta: Utente (ID o e-mail)
- Percorso: users[0].user_fields.owner_email

Passaggio 4: verifica la configurazione

Esegui una verifica nell'apposito campo Verifica risposta:

Inserisci un numero di telefono valido nel formato internazionale E.164.
Assicurati che venga restituito un payload JSON.
Verifica che il Percorso sia valido per trovare il valore utilizzato per instradare la chiamata in entrata.
Verifica che l'indirizzo e-mail del contatto esistente corrisponda a quello di un utente Aircall esistente.

Suggerimento: Modifica le impostazioni di squillo direttamente sotto il campo di verifica in base alle esigenze operative della tua azienda.

Ora puoi iniziare a verificare le chiamate in entrata per l'instradamento intelligente al proprietario del contatto Zendesk tramite il widget Ring-to (via API).

Passaggio alla produzione

Risoluzione dei problemi

Problema	Causa e soluzione
Errore durante la richiesta del token di accesso oppure HTTP 401 durante la ricerca	Le credenziali sono state rifiutate. Verifica che il client OAuth sia Riservato e che l'ID client corrisponda esattamente all'Identificatore. Se il Segreto è stato copiato nuovamente dopo aver lasciato la pagina del Centro amministrativo, viene troncato a nove caratteri: crea un nuovo client e utilizza il Segreto completo.
Una singola verifica o chiamata non riesce, ma la stessa verifica riesce subito dopo	Questo può accadere nel momento in cui un token di accesso memorizzato nella cache scade e viene rinnovato. Riprova la verifica. Se il problema si ripresenta regolarmente anziché occasionalmente, consideralo un effettivo problema di credenziali o ambito e segui le indicazioni nelle righe seguenti.
`{"error":"Forbidden","description":"You are missing the following required scopes: ..."}`	Il token è stato emesso, ma non include l'ambito necessario per l'endpoint. Modifica le credenziali OAuth del widget e imposta Ambito sugli ambiti indicati nel messaggio di errore.
HTTP 400 con `invalid_scope`	L'ambito richiesto dal widget non è incluso nell'elenco Ambiti configurato nel client OAuth in Zendesk. Aggiungi l'ambito agli ambiti consentiti del client oppure modifica l'Ambito del widget affinché rientri tra questi.
Le credenziali sembrano essere state cancellate	La modifica dell'opzione Autenticazione cancella le credenziali memorizzate. Inseriscile nuovamente dopo aver selezionato il metodo.
La verifica restituisce un payload, ma la chiamata non viene instradata	Il valore nel Percorso configurato deve corrispondere a un utente Aircall esistente. Verifica che il valore E-mail del proprietario nel profilo Zendesk corrisponda all'indirizzo e-mail di un utente Aircall.
L'instradamento funzionava in precedenza, ma si è interrotto senza alcuna modifica alla configurazione	Verifica che l'utente Zendesk che ha creato il client OAuth esista ancora e disponga ancora dell'autorizzazione per gestire i client OAuth. I token delle credenziali client operano per conto di tale utente e smettono di funzionare se l'utente perde questo accesso.