Chamada a um serviço antes do processamento de uma mensagem no " IBM Cloud Pak for Data " – experiência clássica

Configuração do webhook

Para incluir detalhes do webhook, conclua as etapas a seguir:

1. Para o assistente que você deseja configurar, clique no ícone e selecione Configurações.

2. Clique em Webhooks > Webhook de pré-mensagem.

3. Configure o comutador Webhook de pre-message como Ativado.

4. No evento Synchronous (Síncrono ), selecione uma das seguintes opções:

   • Continue processando a entrada do usuário sem atualização do webhook se houver um erro.

   • Retorna um erro ao cliente se a chamada do webhook falhar.

Para obter mais informações, consulte Configuração do tratamento de erros do webhook para pré-processamento.

1. No campo URL, inclua a URL para o aplicativo externo para o qual você deseja enviar callouts de solicitação de POST HTTP.

Por exemplo, você pode escrever uma ação da Web Cloud Functions que verifica se uma mensagem está em um idioma diferente do inglês e a envia para o serviço Language Translator para convertê-la em inglês. Especifique a URL para a ação da Web, como neste exemplo:

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

Deve-se especificar uma URL que use o protocolo SSL, portanto, especifique uma URL que comece com https.

1. Preencha o campo Secret (Segredo ). Para obter mais informações, consulte Adição de um segredo.

2. No campo Tempo limite, especifique o tempo de duração, em segundos, que você deseja que o assistente aguarde por uma resposta do webhook antes de retornar um erro. A duração do tempo limite não pode ser menor que um segundo ou maior que 30 segundos.

3. Na seção Headers (Cabeçalhos ), clique em Add header + (Adicionar cabeçalho +) para adicionar os cabeçalhos que deseja passar para o serviço, um de cada vez.

Se o aplicativo externo que você chamar retornar uma resposta, ele poderá enviar uma resposta em diferentes formatos. O webhook requer que a resposta seja formatada em JSON. A tabela a seguir ilustra como adicionar um cabeçalho para indicar que você deseja que o valor resultante seja retornado no formato JSON.

1. Depois que você salva o valor do cabeçalho, a cadeia de caracteres é substituída por asteriscos e não pode ser visualizada novamente.

2. Os detalhes de seu webhook são salvos automaticamente.

Adicionar um segredo

Adicione um segredo de cliente no campo Secret para passar com a solicitação de autenticação com o serviço externo:

• Digite a chave como uma cadeia de texto, como purple unicorn.

• Use um máximo de 1.024 caracteres.

• Não use variáveis de contexto.

O serviço externo é responsável por checar e verificar o segredo. Se nenhum token for necessário, especifique qualquer cadeia de caracteres. Esse campo não pode ser deixado em branco.

Para obter mais informações sobre como esse campo é usado, consulte Segurança do Webhook.

Segurança do webhook

Autentique a solicitação do webhook verificando o JSON Web Token (JWT) que é enviado com a solicitação. O microsserviço de webhook gera automaticamente um JWT e o envia no cabeçalho Authorization com cada chamada de webhook:

• Para novos webhooks ou webhooks atualizados por meio do Edit authentication, o cabeçalho de autorização é ignorado.

• Para webhooks existentes com um cabeçalho de autenticação salvo, a opção Editar autenticação está desativada.

• A atualização de um webhook existente para usar a nova configuração de autenticação altera seu comportamento.

Se você precisar testar a verificação do JWT, poderá adicionar código ao serviço externo. Por exemplo, se você especificar purple unicorn no campo Secret (Segredo ), poderá usar o seguinte código:

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
}

Configurando o tratamento de erros de webhook para o pré-processamento

Você pode decidir se um erro será retornado na etapa de pré-processamento se a chamada do webhook falhar. Há duas opções:

• Continue processando a entrada do usuário sem atualização do webhook se houver um erro : O assistente ignora os erros e processa a mensagem sem o resultado do webhook. Se o pré-processamento for útil, mas não essencial, considere essa opção.

• Retornar um erro para o cliente se a chamada do webhook falhar : Se o pré-processamento for essencial antes de o assistente processar uma mensagem, selecione essa opção.

Importante: Ao ativar a opção “Retornar um erro ao cliente se a chamada do webhook falhar”, tudo fica suspenso até que a etapa de pós-processamento seja concluída com sucesso.

Teste regularmente o processo externo para identificar possíveis falhas. Se necessário, ajuste essa configuração para evitar interrupções no processamento da mensagem.

Testando o webhook

Importante: Realize testes exaustivos do seu webhook antes de ativá-lo para um assistente utilizado em um ambiente de produção.

O webhook é acionado quando uma mensagem é enviada para o assistente para ser processada.

Resolução de problemas do webhook

Os códigos de erro a seguir podem ajudá-lo a rastrear a causa de problemas encontrados. Se você tiver uma integração de bate-papo na Web, por exemplo, saberá que seu webhook tem um problema se cada mensagem de teste que você enviar retornar uma mensagem como There is an error with the message you just sent, but feel free to ask me something else. Se essa mensagem for exibida, use uma ferramenta de API REST, como cURL,, para enviar uma solicitação de API /message de teste, para que você possa ver o código de erro e a mensagem completa que é retornada.

Corpo da solicitação de exemplo

É útil conhecer o formato do corpo da solicitação do webhook de pré-mensagem para que seu código externo possa processá-lo.

O payload contém o corpo da solicitação da versão 2 da solicitação de API /message, com ou sem estado. O nome do evento message_received indica que a solicitação é gerada pelo webhook de pré-mensagem. Para obter mais informações sobre o corpo da solicitação da mensagem, consulte a referência da API.

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

Ignorando o processamento do assistente

As melhorias nos webhooks pré-mensagem permitem que o IBM Cloud Pak for Data - experiência clássica ignore o processamento da mensagem e retorne diretamente a resposta do webhook. Essa funcionalidade é ativada definindo o x-watson-assistant-webhook-return cabeçalho na resposta do webhook ` HTTP `.

Corpo de resposta

O serviço que recebe a solicitação POST do webhook deve retornar um objeto JSON (Accept: application/json).

O corpo da resposta deve ter a estrutura a seguir:

{
  "payload": {
    ...
  }
}

A resposta payload deve incluir o payload do corpo da solicitação. Seu código pode modificar os valores de propriedade ou as variáveis de contexto, mas a carga útil da mensagem retornada deve seguir o esquema do método message . Para obter mais informações, consulte a referência da API.

Exemplo 1

Este exemplo mostra como verificar o idioma do texto de entrada e anexar as informações de idioma à cadeia de texto de entrada.

Na página de configuração do webhook de pré-mensagem, os seguintes valores são especificados:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language

• Secret: none

• Header name: Content-Type

• Header value: application/json

O webhook de pré-mensagem chama uma ação da Web IBM Cloud Functions com o nome check_language.

O código node.js na ação da web check_language tem a aparência a seguir.

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
}
};

Para testar o webhook, clique em Visualizar. Envie o texto Buenos días. O assistente provavelmente não consegue entender a entrada e retorna a resposta de seu nó Anything else. No entanto, se você acessar a página Analisar do seu assistente e abrir Conversas, poderá ver o que foi enviado. Confira a conversa mais recente do usuário. O registro mostra que a entrada do usuário é Buenos días (in es). O es entre parênteses representa o código de idioma do espanhol, portanto, o webhook funcionou e reconheceu que o texto enviado era uma frase em espanhol.

Exemplo 2

Este exemplo mostra como verificar o idioma da mensagem recebida e, se não for inglês, traduzi-la para o inglês antes de enviá-la ao assistente.

Defina uma sequência de ações da web no IBM Cloud Functions. A primeira ação na sequência verifica o idioma do texto recebido. A segunda ação na sequência traduz o texto do idioma original para o inglês.

Na página de configuração do webhook de pré-mensagem, os seguintes valores são especificados:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence

• Secret: none

• Header name: Content-Type

• Header value: application/json

O código node.js para a primeira ação da web em sua sequência é semelhante ao seguinte:

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
}
};

A segunda ação da web na sequência envia o texto para o serviço Watson Language Translator para traduzir o texto de entrada do idioma identificado na ação da web anterior para o inglês. A sequência traduzida é então enviada para o assistente no lugar do texto original.

O código node.js para a segunda ação em sua sequência é semelhante ao seguinte:

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
    }
};

Ao testar o webhook no painel de visualização, é possível enviar Buenos días e o assistente responde como se você dissesse Good morning em inglês. Na verdade, quando você verifica a página Analyze do seu assistente e abre Conversations (Conversas ), o registro mostra que a entrada do usuário foi Good morning.

Você pode adicionar um webhook pós-mensagem para traduzir a resposta da mensagem de volta para o idioma do cliente antes de ser exibida. Para obter mais informações, consulte o Exemplo 2.

Exemplo 3

Este exemplo mostra como elaborar uma resposta de webhook para que IBM Cloud Pak for Data - classic experience ignore o processamento da mensagem e retorne diretamente a resposta do 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;
}

Removendo o webhook

1. Para o assistente que você deseja configurar, clique no ícone e selecione Configurações.

2. Clique em Webhooks > Webhook de pré-mensagem.

3. Faça uma das etapas a seguir:

   • Para parar de chamar um webhook para processar cada mensagem recebida, defina o interruptor Pre-message webhook como Disabled (Desativado ).

   • Para alterar o webhook que você deseja chamar, clique em Excluir webhook.