Configurazione webhook

Per aggiungere i dettagli webhook, completa i seguenti passi:

1. Dal pannello di navigazione, fare clic su Ambienti e aprire l'ambiente in cui si desidera configurare il webhook.

2. Fare clic sull' per aprire le impostazioni dell'ambiente.

3. Impostare l'interruttore webhook Pre-messaggio su Abilitato.

4. Nell'evento Sincrono, selezionare una delle seguenti opzioni:

   • Continuare a elaborare l'input dell'utente senza aggiornare il webhook se si verifica un errore.

   • Restituire un errore al client se la chiamata webhook fallisce.

   Per ulteriori informazioni, vedere Configurazione della gestione degli errori dei webhook per la preelaborazione.

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

   Ad esempio, si potrebbe scrivere un'azione web Cloud Functions che controlla se un messaggio è in una lingua diversa dall'inglese e lo invia al servizio Language Translator per convertirlo in inglese. Specificare il sito URL per l'azione web, come in questo esempio:

   https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
   

   È necessario specificare un URL che utilizzi il protocollo SSL, quindi specificare un URL che inizi con https.

6. Per configurare l'autenticazione per i webhook pre-messaggio, fare clic su Modifica autenticazione. Per istruzioni dettagliate, vedere Definizione del metodo di autenticazione per i webhook pre-messaggio e post-messaggio.

7. Nel campo Timeout, specificare l'intervallo di tempo, in secondi, in cui si desidera che l'assistente attenda una risposta dal webhook prima di restituire un errore. La durata del timeout non può essere inferiore a 1 secondo o superiore a 30 secondi.

8. Nella sezione Intestazioni, fare clic su Aggiungi intestazione + per aggiungere le intestazioni che si desidera passare al servizio, una alla volta.

   Se l'applicazione esterna che si chiama restituisce una risposta, potrebbe essere in grado di inviare una risposta in diversi formati. Il webhook richiede che la risposta sia formattata in JSON. La tabella seguente illustra come aggiungere un'intestazione per indicare che si desidera che il valore risultante sia restituito in formato JSON.

   Esempio di intestazione

   Nome intestazione	Valore intestazione
   Content-Type	application/json

9. Dopo aver salvato il valore dell'intestazione, la stringa viene sostituita da asterischi e non può più essere visualizzata.

10. I dettagli del tuo webhook vengono salvati automaticamente.

Configurazione della gestione degli errori dei webhook per la preelaborazione

Si può decidere se restituire un errore nella fase di preelaborazione se la chiamata webhook fallisce. Hai due opzioni:

• Continuare a elaborare l'input dell'utente senza aggiornare il webhook in caso di errore: L'assistente ignora gli errori ed elabora il messaggio senza il risultato del webhook. Se la preelaborazione è utile ma non essenziale, considerare questa opzione.

• Restituire un errore al client se la chiamata webhook non riesce: Se la pre-elaborazione è fondamentale prima che l'assistente elabori un messaggio, selezionare questa opzione.

Quando si attiva la funzione Restituisci un errore al client se la chiamata webhook fallisce, tutto si ferma finché la fase di preelaborazione non viene completata correttamente.

Testare regolarmente il processo esterno per identificare potenziali errori. Se necessario, regolare questa impostazione per evitare interruzioni nell'elaborazione dei messaggi.

Testare il webhook

Eseguire test approfonditi del webhook prima di abilitarlo per un assistente utilizzato in un ambiente di produzione.

Il webhook viene attivato quando un messaggio viene inviato all'assistente per essere elaborato.

Risoluzione dei problemi del webhook

I seguenti codici di errore possono aiutare a individuare la causa dei problemi riscontrati. Se si dispone di un'integrazione di chat web, ad esempio, si sa che il webhook ha un problema se ogni messaggio di prova inviato restituisce un messaggio come There is an error with the message you just sent, but feel free to ask me something else. Se viene visualizzato questo messaggio, utilizzare uno strumento API REST, come cURL,, per inviare una richiesta API /message di prova, in modo da poter vedere il codice di errore e il messaggio completo che viene restituito.

Esempio di corpo della richiesta

È utile conoscere il formato del corpo della richiesta del webhook pre-messaggio, in modo che il codice esterno possa elaborarlo.

Il payload contiene il corpo della richiesta /message, stateful o stateless, versione 2 della richiesta API. Il nome dell'evento message_received indica che la richiesta è generata dal webhook pre-messaggio. Per ulteriori informazioni sul corpo della richiesta di messaggio, consultare il riferimento API.

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

Saltare l'elaborazione dell'assistente

I miglioramenti ai webhook pre-messaggio consentono a Cloud Pak for Data di saltare l'elaborazione dei messaggi e di restituire direttamente la risposta del webhook. Questa funzionalità si attiva impostando l'intestazione x-watson-assistant-webhook-return nella risposta HTTP del webhook.

Corpo della risposta

Il servizio che riceve la richiesta POST dal webhook deve restituire un oggetto JSON (Accept: application/json).

Il corpo della risposta deve avere la seguente struttura:

{
  "payload": {
    ...
  }
}

La risposta payload deve includere la payload del corpo della richiesta. Il codice può modificare i valori delle proprietà o le variabili di contesto, ma il payload del messaggio restituito deve seguire lo schema del metodo message. Per ulteriori informazioni, vedi Riferimento API.

Esempio 1

Questo esempio mostra come controllare la lingua del testo in ingresso e aggiungere le informazioni sulla lingua alla stringa di testo in ingresso.

Nella pagina di configurazione del webhook pre-messaggio, vengono specificati i seguenti valori:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• Nome dell'intestazione: Content-Type
• Valore dell'intestazione: application/json

Il webhook pre-messaggio richiama un'azione web IBM Cloud Functions denominata check_language.

Il codice di node.js nell'azione web check_language si presenta come segue.

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input text.
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return {
    body : params
}
};

Per testare il webhook, fare clic su Anteprima. Inviare il testo Buenos días. L'assistente probabilmente non riesce a capire l'input e restituisce la risposta del nodo Anything else. Tuttavia, se si va alla pagina Analisi dell'assistente e si aprono le Conversazioni, si può vedere cosa è stato inviato. Controllare la conversazione più recente dell'utente. Il log mostra che l'input dell'utente è Buenos días (in es). L'indirizzo es tra parentesi rappresenta il codice della lingua spagnola, quindi il webhook ha funzionato e ha riconosciuto che il testo inviato era una frase spagnola.

Esempio 2

Questo esempio mostra come controllare la lingua del messaggio in arrivo e, se non è inglese, tradurlo in inglese prima di inviarlo all'assistente.

Definire una sequenza di azioni web in IBM Cloud Functions. La prima azione della sequenza controlla la lingua del testo in arrivo. La seconda azione della sequenza traduce il testo dalla lingua originale all'inglese.

Nella pagina di configurazione del webhook pre-messaggio, vengono specificati i seguenti valori:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• Nome dell'intestazione: Content-Type
• Valore dell'intestazione: application/json

Il codice node.js per la prima azione web della sequenza si presenta come segue:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills["actions skill"].user_defined["language"] = 'none'
    return params
}
};

La seconda azione web della sequenza invia il testo al servizio Watson Language Translator per tradurre il testo in ingresso dalla lingua identificata nell'azione web precedente all'inglese. La stringa tradotta viene quindi inviata all'assistente al posto del testo originale.

Il codice node.js per la seconda azione della sequenza si presenta come segue:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: {
      text: [
          params.payload.input.text
          ],
          target: 'en'
  },
  json: true
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return {
    body : params
    }
};

Quando si testa il webhook nel pannello di anteprima, è possibile inviare Buenos días e l'assistente risponde come se si dicesse Good morning in inglese. Infatti, quando si controlla la pagina Analizza dell'assistente e si apre Conversazioni, il registro mostra che l'input dell'utente è stato Good morning.

È possibile aggiungere un webhook post-messaggio per tradurre la risposta del messaggio nella lingua del cliente prima che venga visualizzata. Per ulteriori informazioni, vedere l'Esempio 2.

Esempio 3

Questo esempio mostra come comporre una risposta webhook per consentire a Cloud Pak for Data di saltare l'elaborazione del messaggio e restituire direttamente la risposta del webhook.

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

Rimozione del webhook

Se non si desidera preelaborare l'input del cliente con un webhook, completare i passaggi seguenti:

1. Nell'assistente, andare in Ambienti e aprire l'ambiente in cui si desidera rimuovere il webhook.

2. Fare clic sull' per aprire le impostazioni dell'ambiente.

3. Nella pagina Impostazioni ambiente, fare clic su Webhook pre-messaggio.

4. Effettuare una delle seguenti operazioni:

• Per non chiamare più un webhook per elaborare ogni messaggio in arrivo, impostare l'interruttore Pre-message webhook su Disabled.

• Per cambiare il webhook che si desidera chiamare, fare clic su Elimina webhook.