Chiamata di un servizio dopo l'elaborazione di un messaggio per IBM Cloud Pak for Data - esperienza classica

Configurazione webhook

Per aggiungere i dettagli webhook, completa i seguenti passi:

1. Per l'assistente che desideri configurare, fai clic sull'icona, quindi seleziona Impostazioni.

2. Fare clic su Webhooks > Webhook post-messaggio.

3. Impostare l'interruttore webhook Post-message su Enabled.

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 post-elaborazione.

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

Ad esempio, è possibile memorizzare le risposte del vostro assistente in un sistema di gestione dei contenuti separato. Quando l'assistente comprende l'input, l'azione elaborata restituisce un ID univoco che corrisponde a una risposta nel sito CMS. Per richiamare un servizio che recuperi una risposta da CMS per un determinato ID univoco, specificare URL per l'istanza del servizio. Ad esempio, https://example.com/get_answer.

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

1. Compilare il campo Segreto. Per ulteriori informazioni, vedere Aggiunta di un segreto.

2. 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.

3. 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.

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

2. I dettagli del tuo webhook vengono salvati automaticamente.

Aggiungere un segreto

Aggiungere un segreto del client nel campo Secret da passare con la richiesta di autenticazione con il servizio esterno:

• Immettere la chiave come stringa di testo, ad esempio purple unicorn.

• Utilizzare un massimo di 1.024 caratteri.

• Non utilizzare variabili di contesto.

Il servizio esterno è responsabile del controllo e della verifica del segreto. Se non è richiesto alcun token, specificare una stringa qualsiasi. Questo campo non può essere lasciato vuoto.

Per ulteriori informazioni sull'utilizzo di questo campo, vedere Sicurezza dei webhook.

Sicurezza dei webhook

Autenticare la richiesta di webhook verificando il JSON Web Token (JWT) inviato con la richiesta. Il microservizio webhook genera automaticamente un JWT e lo invia nell'intestazione Authorization con ogni chiamata webhook:

• Per i nuovi webhook o per i webhook aggiornati tramite l' autenticazione Edit, l'intestazione di autorizzazione viene ignorata.

• Per i webhook esistenti con un'intestazione di autenticazione salvata, il pulsante Modifica autenticazione è disattivato.

• L'aggiornamento di un webhook esistente per utilizzare la nuova configurazione di autenticazione ne modifica il comportamento.

Se è necessario testare la verifica JWT, è possibile aggiungere del codice al servizio esterno. Ad esempio, se si specifica purple unicorn nel campo Secret, si può utilizzare il seguente codice:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Configurazione della gestione degli errori dei webhook per la post-elaborazione

Si può decidere se restituire un errore nella fase di post-elaborazione 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 postelaborazione è utile ma non essenziale, considerare questa opzione.

• Restituire un errore al client se la chiamata webhook non riesce : Se la post-elaborazione è fondamentale dopo l'invio della risposta da parte dell'assistente, selezionare questa opzione.

Importante: quando si attiva l'opzione "Restituisci un errore al client se la chiamata al webhook fallisce", tutte le operazioni vengono sospese fino al completamento con esito positivo della fase di post-elaborazione.

Testare regolarmente il processo esterno per identificare potenziali fallimenti. Se necessario, regolare questa impostazione per evitare interruzioni nell'elaborazione della risposta.

Verifica del webhook

Importante: esegui test approfonditi sul tuo webhook prima di abilitarlo per un assistente utilizzato in un ambiente di produzione.

Il webhook viene attivato solo quando l'assistente elabora un messaggio e una risposta è pronta per essere restituita al canale.

Risoluzione dei problemi relativi al 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 del webhook post-messaggio della richiesta, in modo che il codice esterno possa elaborarlo.

Il payload contiene il corpo della risposta che l'assistente restituisce per la chiamata API versione 2 /message, stateful e stateless. Il nome dell'evento message_processed indica che il webhook post-messaggio genera la richiesta. Per ulteriori informazioni sul corpo della richiesta, consultare la documentazione di riferimento dell'API.

Il seguente esempio mostra come viene formattato un semplice corpo della richiesta:

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

Esempio 1

Questo esempio mostra come aggiungere y'all alla fine di ogni risposta dell'assistente.

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

• URL: https://your-webhook-url/

• Segreto : nessuno

• Nome dell'intestazione : Content-Type

• Valore dell'intestazione : application/json

Il webhook post-messaggio richiama un'azione web IBM Cloud Functions denominata add_southern_charm.

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

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return { 
        body : params
    }
  }
}

Esempio 2

Questo esempio mostra come tradurre la risposta a un messaggio nella lingua del cliente. Funziona solo se si eseguono i passaggi dell' Esempio 2 per definire un webhook pre-messaggio che traduce il messaggio originale in inglese.

Definire una sequenza di azioni web in IBM Cloud Functions. La prima azione della sequenza controlla la lingua del testo originale in arrivo, memorizzata in una variabile di contesto denominata original_input nel codice del webhook pre-messaggio. La seconda azione della sequenza traduce il testo di risposta del dialogo dall'inglese alla lingua originale utilizzata dal cliente.

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

• URL: https://your-webhook-url/

• Segreto : nessuno

• 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.output.generic[0].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': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  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 param
}
};

La seconda azione web della sequenza si presenta come segue:

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

function main(params) {
  console.log(JSON.stringify(params))
    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'
        },
    body: { 
        text: [ 
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true 
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return { 
    body : params
  }
};

Rimozione del webhook

Se non si desidera elaborare le risposte ai messaggi con un webhook, completare i passaggi seguenti:

1. Per l'assistente che desideri configurare, fai clic sull'icona, quindi seleziona Impostazioni.

2. Fare clic su Webhooks > Webhook post-messaggio.

3. Effettuare una delle seguenti operazioni:

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

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