Centro assistenza Aircall | Widget del flusso di chiamata: documentazione tecnica di Squilla a (tramite API)

Il widget Instradamento intelligente: Chiama (tramite API) utilizza una risposta API per determinare a quale utente Aircall, team, numero interno o numero esterno instradare una chiamata, in base ai dati archiviati al di fuori di Aircall.

Questo widget offre funzionalità di instradamento dinamico potenti e flessibili collegando Aircall a sistemi di terze parti, come CRM o Help desk.

Importante: Il widget Chiama (tramite API) è disponibile solo con il Piano Professional. Per effettuare l'upgrade, contatta il tuo account manager Aircall.

Prerequisiti

Prima di configurare il widget, assicurati che siano soddisfatti i seguenti requisiti.

Credenziali di autenticazione

Il metodo di autenticazione dipende dalla piattaforma esterna dalla quale intendi recuperare i dati. I metodi supportati includono:

Autenticazione di base
Token Bearer
Chiave API
OAuth

Esempio (API Aircall):

Nel Dashboard di Aircall, vai a Integrazioni > Chiavi API.
Genera una nuova chiave API.
Salva sia l'ID della chiave API sia il token.
Nella configurazione del widget Chiama (tramite API), vai a Credenziali e imposta:
- Nome utente = ID della chiave API
- Password = token API

Per ulteriori informazioni su come trovare la tua chiave API Aircall, consulta l'articolo Dove trovare la mia chiave API Aircall.

Conoscenza dell'API della piattaforma

Devi conoscere la struttura e gli endpoint dell'API pubblica della piattaforma esterna.

Sebbene Dove trovare la mia chiave API Aircall utilizzi l'API Aircall come esempio, puoi utilizzare anche piattaforme come HubSpot, Salesforce, Zendesk, Intercom, Pipedrive o CRM interni.

Conoscenza di JSON

Il widget utilizza JSON (JavaScript Object Notation) per scambiare dati con le API. È necessario conoscere le strutture JSON di base per configurare correttamente i percorsi dei dati.

Suggerimento: Se hai bisogno di assistenza per configurare il widget, il nostro team tecnico può fornire consulenza e supporto per l'implementazione. Contatta il nostro team di Account Management.

Considerazioni sull'utilizzo

Il widget Chiama (tramite API) consente l'instradamento dinamico («intelligente») delle chiamate in base a dati esterni. Può interrogare qualsiasi sistema che supporti API REST e metodi di autenticazione standard.

Nota: Le richieste effettuate da Chiama (tramite API) scadono dopo 10 secondi. Assicurati che il tuo endpoint risponda entro questo limite di tempo, altrimenti il widget potrebbe non riuscire a recuperare la destinazione dell'instradamento.

La risposta API deve restituire i dati in un formato che Aircall possa interpretare per l'instradamento. I tipi di risposta supportati includono:

Tipo di risposta	Descrizione
Utente	Instrada la chiamata a un Agente specifico utilizzando il suo ID utente Aircall o il suo indirizzo e-mail.
Team	Instrada la chiamata a un Team Aircall specifico utilizzando il relativo ID Team.
Numero Aircall	Instrada internamente la chiamata a un altro numero Aircall utilizzando il relativo ID numero.
Numero esterno	Instrada esternamente la chiamata a un numero di telefono (che deve essere nel formato internazionale E.164).
Destinazione dinamica (ID)	Consente all'API esterna di specificare dinamicamente sia il tipo sia l'ID della destinazione.

Quando utilizzi la Destinazione dinamica (ID), devi definire due percorsi JSON nel widget:

Percorso del tipo di destinazione (utente, Team, numero o esterno)
Percorso del valore della destinazione (l'ID univoco della destinazione)

Nota: Per le risposte Destinazione dinamica, il widget accetta solo i seguenti valori per il tipo di destinazione: agent, team, internal ed external.

Se la destinazione individuata è un Team, si applicano le regole di squillo standard. Se è un utente o un numero, tali regole non si applicano.

Qualsiasi logica avanzata (ad esempio, instradamento condizionale o definizione delle priorità) deve essere elaborata nel tuo sistema esterno prima che venga restituita la risposta API.

Passaggi di configurazione

Il widget determina se chiamare un Utente, un Team, un Numero Aircall, un Numero esterno o una Destinazione dinamica (ID) in base alla chiamata API configurata.

Passaggi:

Nell'editor di flussi, aggiungi un widget Chiama (tramite API).
Scegli il metodo HTTP (GET o POST), a seconda della sezione dell'API che desideri utilizzare.
- Esempio: quando utilizzi l'endpoint Cerca chiamate dell'API Aircall, seleziona GET.
Inserisci l'URL dell'API, ad esempio:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Questa operazione cerca le chiamate più recenti associate al numero di telefono del chiamante.
Utilizza variabili come callerNumber, targetNumber o callUUID per inserire dinamicamente nella richiesta dati specifici della chiamata. Per un elenco completo dei parametri di query, consulta la documentazione dell'API Aircall.

Configurazione della risposta

Nella sezione Configurazione della risposta, definisci come analizzare la risposta API per determinare la destinazione dell'instradamento.

Tipi di risposta supportati:

Utente (ID o e-mail)
Team (ID)
Numero Aircall (interno)
Numero esterno (formato E.164)
Destinazione dinamica (ID)

Esempio di percorso JSON:

calls[0].user.id

Questo percorso fa riferimento al primo elemento dell'array “calls” e recupera l'ID dell'utente.

Esempio di risposta JSON della destinazione dinamica:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}

Percorso del tipo di destinazione: calls[0].target_type
Percorso del valore di destinazione: calls[0].target_id

Se il tipo di destinazione è team, le regole di squillo verranno applicate di conseguenza.

Test della configurazione

Utilizza il campo Test della risposta per simulare le richieste API e verificare che i percorsi configurati restituiscano i valori corretti.

Esempio di input di test:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Ogni chiave nel JSON corrisponde a una variabile utilizzata nell'URL o nel corpo della richiesta. Quando esegui il test, il widget sostituisce queste variabili e visualizza i risultati analizzati.

Se si verifica un errore, consulta la sezione Errori nella documentazione dell'API Aircall per indicazioni sulla risoluzione dei problemi.

Impostazioni di squillo

Dopo aver configurato e testato l'integrazione API, modifica le Impostazioni di squillo per definire come distribuire le chiamate. Queste impostazioni funzionano come quelle del widget standard Chiama.

Per ulteriori dettagli, consulta il nostro articolo del Centro assistenza Panoramica dell'instradamento del flusso di chiamata

Suggerimento: Se ti interessa sfruttare questa funzionalità ma non disponi delle competenze tecniche necessarie, contatta il nostro team di gestione account, che ti metterà in contatto con il nostro team tecnico per ricevere assistenza e indicazioni sull'implementazione.

Questo widget offre funzionalità di instradamento dinamico potenti e flessibili collegando Aircall a sistemi di terze parti, come CRM o Help desk.

Importante: Il widget Chiama (tramite API) è disponibile solo con il Piano Professional. Per effettuare l'upgrade, contatta il tuo account manager Aircall.

Prerequisiti

Prima di configurare il widget, assicurati che siano soddisfatti i seguenti requisiti.

Credenziali di autenticazione

Il metodo di autenticazione dipende dalla piattaforma esterna dalla quale intendi recuperare i dati. I metodi supportati includono:

Autenticazione di base
Token Bearer
Chiave API
OAuth

Esempio (API Aircall):

Nel Dashboard di Aircall, vai a Integrazioni > Chiavi API.
Genera una nuova chiave API.
Salva sia l'ID della chiave API sia il token.
Nella configurazione del widget Chiama (tramite API), vai a Credenziali e imposta:
- Nome utente = ID della chiave API
- Password = token API

Per ulteriori informazioni su come trovare la tua chiave API Aircall, consulta l'articolo Dove trovare la mia chiave API Aircall.

Conoscenza dell'API della piattaforma

Devi conoscere la struttura e gli endpoint dell'API pubblica della piattaforma esterna.

Conoscenza di JSON

Il widget utilizza JSON (JavaScript Object Notation) per scambiare dati con le API. È necessario conoscere le strutture JSON di base per configurare correttamente i percorsi dei dati.

Suggerimento: Se hai bisogno di assistenza per configurare il widget, il nostro team tecnico può fornire consulenza e supporto per l'implementazione. Contatta il nostro team di Account Management.

Considerazioni sull'utilizzo

Nota: Le richieste effettuate da Chiama (tramite API) scadono dopo 10 secondi. Assicurati che il tuo endpoint risponda entro questo limite di tempo, altrimenti il widget potrebbe non riuscire a recuperare la destinazione dell'instradamento.

La risposta API deve restituire i dati in un formato che Aircall possa interpretare per l'instradamento. I tipi di risposta supportati includono:

Tipo di risposta	Descrizione
Utente	Instrada la chiamata a un Agente specifico utilizzando il suo ID utente Aircall o il suo indirizzo e-mail.
Team	Instrada la chiamata a un Team Aircall specifico utilizzando il relativo ID Team.
Numero Aircall	Instrada internamente la chiamata a un altro numero Aircall utilizzando il relativo ID numero.
Numero esterno	Instrada esternamente la chiamata a un numero di telefono (che deve essere nel formato internazionale E.164).
Destinazione dinamica (ID)	Consente all'API esterna di specificare dinamicamente sia il tipo sia l'ID della destinazione.

Quando utilizzi la Destinazione dinamica (ID), devi definire due percorsi JSON nel widget:

Percorso del tipo di destinazione (utente, Team, numero o esterno)
Percorso del valore della destinazione (l'ID univoco della destinazione)

Nota: Per le risposte Destinazione dinamica, il widget accetta solo i seguenti valori per il tipo di destinazione: agent, team, internal ed external.

Se la destinazione individuata è un Team, si applicano le regole di squillo standard. Se è un utente o un numero, tali regole non si applicano.

Qualsiasi logica avanzata (ad esempio, instradamento condizionale o definizione delle priorità) deve essere elaborata nel tuo sistema esterno prima che venga restituita la risposta API.

Passaggi di configurazione

Il widget determina se chiamare un Utente, un Team, un Numero Aircall, un Numero esterno o una Destinazione dinamica (ID) in base alla chiamata API configurata.

Passaggi:

Nell'editor di flussi, aggiungi un widget Chiama (tramite API).
Scegli il metodo HTTP (GET o POST), a seconda della sezione dell'API che desideri utilizzare.
- Esempio: quando utilizzi l'endpoint Cerca chiamate dell'API Aircall, seleziona GET.
Inserisci l'URL dell'API, ad esempio:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Questa operazione cerca le chiamate più recenti associate al numero di telefono del chiamante.
Utilizza variabili come callerNumber, targetNumber o callUUID per inserire dinamicamente nella richiesta dati specifici della chiamata. Per un elenco completo dei parametri di query, consulta la documentazione dell'API Aircall.

Configurazione della risposta

Nella sezione Configurazione della risposta, definisci come analizzare la risposta API per determinare la destinazione dell'instradamento.

Tipi di risposta supportati:

Utente (ID o e-mail)
Team (ID)
Numero Aircall (interno)
Numero esterno (formato E.164)
Destinazione dinamica (ID)

Esempio di percorso JSON:

calls[0].user.id

Questo percorso fa riferimento al primo elemento dell'array “calls” e recupera l'ID dell'utente.

Esempio di risposta JSON della destinazione dinamica:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}

Percorso del tipo di destinazione: calls[0].target_type
Percorso del valore di destinazione: calls[0].target_id

Se il tipo di destinazione è team, le regole di squillo verranno applicate di conseguenza.

Test della configurazione

Utilizza il campo Test della risposta per simulare le richieste API e verificare che i percorsi configurati restituiscano i valori corretti.

Esempio di input di test:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Ogni chiave nel JSON corrisponde a una variabile utilizzata nell'URL o nel corpo della richiesta. Quando esegui il test, il widget sostituisce queste variabili e visualizza i risultati analizzati.

Se si verifica un errore, consulta la sezione Errori nella documentazione dell'API Aircall per indicazioni sulla risoluzione dei problemi.

Impostazioni di squillo

Per ulteriori dettagli, consulta il nostro articolo del Centro assistenza Panoramica dell'instradamento del flusso di chiamata

Suggerimento: Se ti interessa sfruttare questa funzionalità ma non disponi delle competenze tecniche necessarie, contatta il nostro team di gestione account, che ti metterà in contatto con il nostro team tecnico per ricevere assistenza e indicazioni sull'implementazione.