Definizione del webhook

È possibile definire un URL webhook per una finestra di dialogo e quindi richiamare il webhook da uno o più nodi di dialogo.

La chiamata programmatica al servizio esterno deve soddisfare questi requisiti:

• La chiamata deve essere una richiesta POST HTTP.
• Il body della richiesta deve essere un oggetto JSON (Content-Type: application/json).
• La risposta deve essere un oggetto JSON (Accept: application/json).
• La chiamata deve ritornare in 8 secondi o meno. Se è stato avviato più di una volta in una singola chiamata del messaggio tramite i nodi di dialogo, tutte queste chiamate devono essere restituite in 8 secondi o meno.

Se il servizio esterno supporta solo le richieste GET o se è necessario specificare dinamicamente i parametri URL in fase di esecuzione, si può pensare di creare un servizio intermedio che accetti una richiesta POST con un payload JSON che contenga i valori in fase di esecuzione. Il servizio intermedio può quindi fare una richiesta al servizio di destinazione, passando questi valori come parametri URL, e restituire la risposta alla finestra di dialogo.

Se hai bisogno di richiamare un servizio che potrebbe non restituire entro 8 secondi, puoi gestire la chiamata tramite un'applicazione client personalizzata e passare le informazioni al dialogo come passo separato. Per ulteriori informazioni, vedi Richiesta di azioni client.

Per aggiungere i dettagli webhook, completa i seguenti passi:

1. Nella finestra di dialogo in cui vuoi aggiungere il webhook, fai clic su Webhooks.

2. Nel campo URL, aggiungi l'URL per l'applicazione esterna a cui vuoi inviare i callout della richiesta POST HTTP.

   Ad esempio, per chiamare il servizio Language Translator, specificare l' URL dell'istanza del servizio.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   Se l'applicazione esterna che richiami restituisce una risposta, deve essere in grado di reinviare una risposta in formato JSON. Per il servizio Language Translator, ad esempio, è necessario specificare il formato in cui si desidera che venga restituito il risultato. Puoi eseguire questa operazione passando un'intestazione al servizio.

3. Nella sezione Headers, aggiungi le intestazioni che vuoi passare al servizio una alla volta facendo clic su Add header.

   Ad esempio, questa intestazione indica che la richiesta è in formato JSON.

   Esempio di intestazione

   Nome intestazione	Valore intestazione
   Content-Type	application/json

4. Se il servizio esterno richiede che passi le credenziali di autenticazione di base con la richiesta, forniscile. Fai clic su Add authorization, aggiungi le tue credenziali ai campi User name e Password e poi fai clic su Save.

   Il prodotto crea una stringa ASCII con codifica base-64 dalle credenziali e genera un'intestazione che la aggiunge alla pagina per te.

   Esempio di intestazione

   Nome intestazione	Valore intestazione
   Autorizzazione	Base <encoded-credentials>

   Se si utilizza l'integrazione della chat web e si abilita la sicurezza, è possibile utilizzare lo stesso token utilizzato per proteggere la chat web nell'intestazione Authorization. Per ulteriori informazioni, vedi Chat web: riutilizzo del JWT per l'autenticazione webhook.

I dettagli del tuo webhook vengono salvati automaticamente.

Aggiunta di un callout webhook a un nodo di dialogo

Per utilizzare un webhook da un nodo di dialogo, devi abilitare i webhook sul nodo e poi aggiungere i dettagli per il callout.

1. Trova un nodo di dialogo in cui vuoi aggiungere un callout. La chiamata al webhook avviene ogni volta che questo nodo viene attivato durante una conversazione con un utente.

   Ad esempio, potresti voler inviare un callout al webhook dal nodo #General_Greetings.

2. Fai clic per aprire il nodo di dialogo e poi fai clic su Customize.

3. Scorrere fino alla sezione webhook. Imposta l'opzione Call out to webhooks / actions su On.

4. Seleziona Call a webhook e fai clic su Apply.

   Se non è già stato attivato, l'interruttore delle risposte condizionate multiple è impostato automaticamente su On e non è possibile disattivarlo. Questa impostazione viene abilitata per supportare l'aggiunta di diverse risposte a seconda della riuscita o meno della chiamata Webhook. Se esiste già una risposta specificata per il nodo, questa diventa la prima risposta condizionale.

5. Aggiungi i dati che vuoi passare all'applicazione esterna come coppie chiave e valore nella sezione Parameters.

   I parametri vengono passati come proprietà del corpo della richiesta. Non è possibile specificare parametri di query o parametri URL in un nodo di dialogo. Questi parametri possono essere configurati con valori statici solo come parte della definizione webhook. Per ulteriori informazioni, vedi Definizione del webhook.

   Ad esempio, se richiami il servizio Language Translator, devi fornire i valori per i seguenti parametri:

   Esempio di parametro

   Chiave	Valore	Descrizione
   model_id	en-es	Identifica le lingue di input e di output. In questo esempio, la richiesta è per il testo in inglese (en) da tradurre in spagnolo (es).
   text	How are you?	Questo parametro contiene la stringa di testo che vuoi che venga tradotta dal servizio. È possibile codificare questo valore, passare una variabile di contesto, come $saved_text, o passare direttamente l'input dell'utente al servizio, specificando <? input.text ?> come valore.

   In casi di utilizzo più complessi, potresti raccogliere le informazioni durante una conversazione con un utente sui suoi piani di viaggio, ad esempio. Puoi raccogliere le informazioni sulle date e sulla destinazione e salvarle in variabili di contesto che puoi passare a un'applicazione esterna come parametri.

   Esempio di parametri di viaggio

   Chiave	Valore
   depart_date	$departure
   arrive_date	$arrival
   origine	$origin
   destinazione	$destination

6. Qualsiasi risposta fornita dal callout viene salvata nella variabile return. Puoi ridenominare la variabile che viene aggiunta automaticamente al campo Return variable per te. Se il callout genera un errore, questa variabile viene impostata su null.

   Il nome della variabile generata ha la sintassi webhook_result_n, dove il suffisso _n viene incrementato ogni volta che si aggiunge un callout webhook a un nodo di dialogo. Questa convenzione di denominazione assicura che i nomi delle variabili di contesto siano unici in tutta la finestra di dialogo. Se modifichi il nome, assicurati di utilizzare un nome univoco.

7. Nella sezione delle risposte condizionali, vengono salvate automaticamente due risposte, una risposta da mostrare quando il callout webhook ha esito positivo e viene reinviata una variabile di ritorno. E una risposta da mostrare quando il callout ha esito negativo. Puoi modificare queste risposte e aggiungere altre risposte condizionali al nodo.

   • Se il callout restituisce una risposta e conosci il formato della risposta JSON, puoi modificare la risposta del nodo di dialogo per includere solo la sezione della risposta che vuoi condividere con gli utenti.

     Ad esempio, il servizio Language Translator restituisce un oggetto come questo:

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     Utilizza un'espressione SpEL che estrae solo il valore di testo tradotto.

     Esempio di risposte condizionali

     Condizione	Risposta
     $webhook_result_1	Le tue parole in spagnolo: .
     anything_else	The call to the external application failed. Riprovare successivamente.

     Se si utilizza il formato consigliato per la risposta e viene restituita la risposta di traduzione mostrata in precedenza, la risposta dell'assistente all'utente sarà: Your words in Spanish: ¿Cómo estás?

   • Se si vuole fornire una risposta specifica se il callout restituisce una stringa vuota, cioè se la chiamata ha successo, ma il valore restituito è una stringa vuota, si può aggiungere una risposta condizionale che ha una condizione con una sintassi come questa:

     $webhook_result_1.size() == 0
     

8. Una volta terminato, fai clic sulla X per chiudere il nodo. Le tue modifiche vengono salvate automaticamente.

Verifica dei webhook

Quando si aggiunge per la prima volta un callout webhook, può essere utile vedere esattamente cosa viene restituito nella risposta dall'applicazione esterna, i dati e il loro formato. Aggiungere questa espressione come testo di risposta per la risposta condizionale di callout riuscito: $webhook_result_n dove n è il numero appropriato per il webhook che si sta testando.

Questa risposta restituisce il corpo completo della variabile di ritorno, quindi puoi vedere cosa sta reinviando il callout e decidere cosa condividere con gli utenti. Si possono quindi usare i metodi documentati nel linguaggio Expression per estrarre dalla risposta solo le informazioni che interessano.

Verifica se determinati input utente possono generare errori nel callout e crea modi per gestire tali situazioni. Gli errori generati dall'applicazione esterna sono memorizzati in output.webhook_error.<result_variable>. Puoi utilizzare una risposta condizionale come questa mentre stai verificando l'acquisizione di questo tipo di errori:

Ad esempio, è possibile che tu non stia autenticando correttamente la richiesta (401) oppure che tu stia tentando di passare un parametro con un nome già utilizzato dall'applicazione esterna. Verifica il webhook per rilevare e correggere questi tipi di errori prima di distribuire il webhook.

Rimozione di un webhook

Se decidi di non voler effettuare una chiamata webhook da un nodo di dialogo, apri la pagina Customize del nodo e poi imposta i Webhook su Off.

La sezione Parameters e il campo Return variable vengono rimossi dall'editor del nodo di dialogo. Tuttavia, le risposte condizionali aggiunte per te o che hai aggiunto da solo rimangono.

La sezione Multiple conditioned responses è di nuovo modificabile. È possibile scegliere di disattivare la funzione. Se lo fai, solo la prima risposta condizionale viene salvata come unica risposta di testo del nodo.

Per modificare il servizio esterno che hai richiamato dai nodi di dialogo, modifica i dettagli webhook definiti nella pagina Webhooks della scheda Options. Se il nuovo servizio prevede che gli vengano passati parametri diversi, assicurati di aggiornare i nodi di dialogo che lo richiamano.

Aggiornamento di output.generic con un webhook

Puoi utilizzare un webhook per aggiornare output.generic e fornire risposte dinamiche. Per ulteriori informazioni, consultare l'articolo del blog How to Dynamically Add Response Options to Dialog Nodes.