Chamada a um serviço após o processamento de uma mensagem para IBM Cloud Pak for Data

Configuração do webhook

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

1. No painel de navegação, clique em Environments (Ambientes ) e abra o ambiente em que você deseja configurar o webhook.

2. Clique no ícone para abrir as configurações do ambiente.

3. Configure o comutador Webhook de postmessage para 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 pós-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, é possível armazenar as respostas do assistente em um sistema de gerenciamento de conteúdo separado. Quando o assistente compreende a entrada, a ação processada retorna um ID exclusivo que corresponde a uma resposta em seu CMS. Para chamar um serviço que recupere uma resposta do CMS para um determinado ID exclusivo, especifique a URL para a instância de serviço. Por exemplo, https://example.com/get_answer.

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

1. Para configurar a autenticação para webhooks pós-mensagem, clique em Edit authentication (Editar autenticação ). Para obter instruções detalhadas, consulte Definição do método de autenticação para webhooks de pré-mensagem e pós-mensagem.

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.

Configurando o tratamento de erros do webhook para pós-processamento

Você pode decidir se um erro será retornado na etapa de pós-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 pós-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 pós-processamento for essencial depois que o assistente enviar uma resposta, 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 resposta.

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 somente quando seu assistente processa uma mensagem e uma resposta está pronta para ser retornada ao canal.

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 do webhook da solicitação pós-mensagem para que seu código externo possa processá-lo.

O payload contém o corpo da resposta que seu assistente retorna para a versão 2 /message, chamada de API com e sem estado. O nome do evento message_processed indica que o webhook de pós-mensagem gera a solicitação. Para obter mais informações sobre o corpo da solicitação da mensagem, consulte a referência da API.

O exemplo a seguir mostra como um corpo de solicitação simples é formatado:

{
 "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"
                }
            }
        }
    }
}

Exemplo 1

Este exemplo mostra como adicionar y'all ao final de cada resposta do assistente.

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

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

• Header name: Content-Type

• Header value: application/json

O webhook pós-mensagem chama uma ação web IBM Cloud Functions de nome add_southern_charm.

O código node.js na ação da web add_southern_charm é semelhante ao seguinte:

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

Exemplo 2

Este exemplo mostra como traduzir uma resposta de mensagem de volta para o idioma do cliente. Isso só funciona se você executar as etapas do Exemplo 2 para definir um webhook de pré-mensagem que traduza a mensagem original para o inglês.

Defina uma sequência de ações da web no IBM Cloud Functions. A primeira ação da sequência verifica o idioma do texto original recebido, que você armazenou em uma variável de contexto chamada original_input no código do webhook de pré-mensagem. A segunda ação na sequência traduz o texto de resposta do diálogo do inglês para o idioma original que foi usado pelo cliente.

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

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

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

A segunda ação da web na sequência é semelhante à seguinte:

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

Removendo o webhook

Se você não quiser processar respostas de mensagens com um webhook, conclua as etapas a seguir:

1. Em seu assistente, vá para Environments (Ambientes ) e abra o ambiente em que deseja remover o webhook.

2. Clique no ícone para abrir as configurações do ambiente.

3. Na página de configurações do ambiente, clique em Webhook pós-mensagem.

4. Faça uma das etapas a seguir:

   • Para parar de chamar um webhook para processar cada mensagem recebida, defina a chave do webhook Post-message como Disabled (Desativado ).

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