Vai alla navigazione

Webhook

Fornisci alla tua receptionist strumenti personalizzati che chiamano i tuoi endpoint HTTP.

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:

  1. Un endpoint HTTP da chiamare.
  2. Una descrizione di cosa fa, così l’IA sa quando usarlo.
  3. 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.

CampoDescrizione
NomeNome dello strumento visualizzato dall’IA, ad esempio check_order_status
DescrizioneQuando e perché usare questo strumento
MetodoGET, POST, PUT, PATCH o DELETE
URLIl tuo endpoint HTTP
Timeout della risposta (secondi)Tempo di attesa del server: 5–120 secondi, valore predefinito 20
Assegna agli agentiReceptionist, Agente assistente o entrambi
Disabilita le interruzioniImpedisce al chiamante di interrompere mentre lo strumento è in esecuzione
Header della richiestaHeader facoltativi inviati con ogni richiesta. Il Tipo può essere Valore o Segreto. Un Segreto viene archiviato in forma crittografata e non viene mai più mostrato. Un header proveniente da ElevenAgents può mostrare Variabile d’ambiente o Variabile, con una nota che indica che è impostato nella piattaforma degli agenti.
Parametri del pathVengono mostrati quando l’URL contiene segnaposto tra parentesi graffe, ad esempio /orders/{order_id}. Modifica l’URL per aggiungerne o rimuoverne uno.
Parametri del bodyParametri inviati come body della richiesta JSON, mostrati per POST, PUT e PATCH. Possono essere oggetti ed elenchi.
Parametri della queryParametri inviati come stringhe di query nell’URL. Ognuno è un singolo valore.

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 come filter[name].
  • Tipo: string, number, integer o boolean. I parametri del body possono essere anche object o array.
  • 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 object raggruppa 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 conversazione
  • phones: array, in cui ogni elemento è un oggetto con due campi:
    • number: stringa, dalla conversazione
    • label: stringa, valore fisso mobile
  • source: oggetto con un campo, channel: stringa, valore fisso phone

inviano un body della richiesta come questo:

{
"name": "Jane Doe",
"phones": [{ "number": "+15551234567", "label": "mobile" }],
"source": { "channel": "phone" }
}

Casi d’uso

ScenarioDescrizioneMetodo
Ricerca CRMCerca le informazioni sul cliente nel tuo sistemaGET
Controllo inventarioVerifica la disponibilità dei prodotti in tempo realeGET
Acquisizione leadInvia i dettagli del chiamante al tuo sistema di marketingPOST
Creazione ticketCrea un ticket di assistenza durante la chiamataPOST
PreventivoCalcola un preventivo personalizzato in base alle esigenze del chiamantePOST

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: Authorization impostato 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.