Webhook
L’integrazione Strumento webhook espone i tuoi endpoint HTTP come strumenti che la tua receptionist o il tuo assistente aziendale può chiamare durante le conversazioni. L’IA decide quando chiamare l’endpoint in base alla conversazione.
Come funzionano gli strumenti webhook
Quando crei uno strumento webhook, definisci:
- Un endpoint HTTP da chiamare.
- Una descrizione di cosa fa, così l’IA sa quando usarlo.
- I parametri che l’IA deve raccogliere dalla conversazione.
Durante una chiamata, quando la conversazione corrisponde allo scopo dello strumento, la receptionist raccoglie i parametri, chiama l’endpoint e usa la risposta per continuare la conversazione.
Creare uno strumento webhook
Vai a Integrazioni, seleziona Aggiungi integrazione e scegli Strumento webhook. Configura i campi seguenti e seleziona Abilita. Puoi aggiungere più strumenti webhook.
Parametri
Ogni parametro include:
- Chiave: il nome del campo. Usa lettere, numeri, trattini bassi, trattini,
@e punti singoli. Le parentesi quadre non sono consentite, quindi non puoi chiamare direttamente un’API che prevede chiavi comefilter[name]. - Tipo:
string,number,integeroboolean. I parametri del body possono essere ancheobjectoarray. - Valore: Dalla conversazione, compilato dall’IA, oppure un Valore fisso, inviato con ogni richiesta.
- Descrizione: il valore che l’IA deve estrarre dalla conversazione.
- Obbligatorio: indica se l’IA deve raccoglierlo prima della chiamata.
Usa integer per i numeri interi, ad esempio conteggi, ID e flag 0/1. Un valore number fisso viene inviato
con una virgola decimale, quindi 1 arriva come 1.0, che alcune API rifiutano.
Un parametro configurato in ElevenAgents per ottenere il proprio valore da una variabile viene mostrato come di sola lettura, con una nota che indica che è impostato nella piattaforma degli agenti. Viene inviato come configurato lì.
Oggetti ed elenchi
Molte API prevedono campi correlati raggruppati insieme, ad esempio un contatto con un elenco di numeri di telefono. I parametri del body possono inviarli:
- Un
objectraggruppa i campi. Seleziona Aggiungi campo per aggiungerli; ogni campo ha la propria chiave, il proprio tipo e il proprio valore. - Un
arrayè un elenco. In Ogni elemento, scegli il tipo degli elementi. Un elenco di oggetti consente all’IA di inviare più voci con la stessa struttura, ad esempio una per numero di telefono.
I campi possono essere nidificati fino a cinque livelli. Un oggetto o un elenco proviene sempre dalla conversazione, ma un campo all’interno di un oggetto può avere un Valore fisso, ad esempio un’etichetta o un ID che non cambia mai.
Ad esempio, questi parametri del body:
name: stringa, dalla conversazionephones: array, in cui ogni elemento è un oggetto con due campi:number: stringa, dalla conversazionelabel: stringa, valore fissomobile
source: oggetto con un campo,channel: stringa, valore fissophone
inviano un body della richiesta come questo:
Casi d’uso
Esempio
Un’azienda idraulica crea uno strumento webhook:
- Nome:
check_service_area - Descrizione: “Verifica se offriamo assistenza nel CAP del chiamante e qual è il prossimo appuntamento disponibile.”
- URL:
https://api.mybusiness.com/check-area - Metodo: POST
- Header della richiesta:
Authorizationimpostato sulla chiave API dell’azienda, come Segreto - Parametri del body:
zip_code(stringa, obbligatorio),service_type(stringa, obbligatorio)
Quando un chiamante chiede informazioni sul servizio nella propria zona, la receptionist raccoglie il suo CAP, chiama il webhook e gli comunica il risultato.
Gli strumenti webhook sono disponibili in tutti i piani.