Configuración de webhook

Para añadir los detalles de webhook, complete los pasos siguientes:

1. En el panel de navegación, haga clic en Entornos y abra el entorno en el que desea configurar el webhook.

2. Pulse el icono para abrir los valores de entorno.

3. Establezca el conmutador Webhook de posmensaje en Habilitado.

4. En el evento Sincrónico, seleccione una de las siguientes opciones:

   • Continuar procesando la entrada del usuario sin actualizar el webhook si hay un error.

   • Devuelve un error al cliente si falla la llamada al webhook.

   Para obtener más información, consulte Configuración de la gestión de errores de webhook para el postprocesamiento.

5. En el campo URL, añada el URL de la aplicación externa a la que desea enviar llamadas de solicitud POST de HTTP.

   Por ejemplo, tal vez almacene las respuestas del asistente en un sistema de gestión de contenidos independiente. Cuando el asistente entiende la entrada, la acción procesada devuelve un ID exclusivo que corresponde a una respuesta del CMS. Para llamar a un servicio que recupera una respuesta del CMS para un ID exclusivo determinado, especifique el URL de la instancia de servicio. Por ejemplo, https://example.com/get_answer.

   Debe especificar un URL que utilice el protocolo SSL, es decir, un URL que empiece por https.

6. Para configurar la autenticación de los webhooks post-mensaje, haga clic en Editar autenticación. Para obtener instrucciones detalladas, consulte Definición del método de autenticación para webhooks pre-mensaje y post-mensaje.

7. En el campo Tiempo de espera, especifique el tiempo (en segundos) que desea que el asistente espere una respuesta del webhook antes de devolver un error. La duración del tiempo de espera no puede de menos de 1 segundo ni de más de 30 segundos.

8. En la sección Cabeceras, haga clic en Añadir cabecera + para añadir las cabeceras que desee pasar al servicio, de una en una.

   Si la aplicación externa a la que llama devuelve una respuesta, es posible que pueda enviar una respuesta en diferentes formatos. El webhook requiere que la respuesta esté formateada en JSON. La siguiente tabla ilustra cómo añadir una cabecera para indicar que desea que el valor resultante que se devuelva esté en formato JSON.

   Ejemplo de cabecera

   Nombre de cabecera	Valor de cabecera
   Content-Type	application/json

9. Después de guardar el valor de la cabecera, la cadena se sustituye por asteriscos y no se puede volver a ver.

10. Los detalles de su webhook se guardan de forma automática.

Configuración de la gestión de errores de webhook para el postprocesamiento

Puedes decidir si se devuelve un error en el paso de postprocesamiento si falla la llamada al webhook. Tiene dos opciones:

• Continúa procesando la entrada del usuario sin actualizar el webhook si hay un error: El asistente ignora los errores y procesa el mensaje sin el resultado del webhook. Si el postprocesado es útil pero no esencial, considere esta opción.

• Devolver un error al cliente si falla la llamada al webhook: Si el postprocesamiento es crítico después de que el asistente envíe una respuesta, seleccione esta opción.

Cuando activas Devolver un error al cliente si la llamada webhook falla, todo se detiene hasta que el paso de postprocesamiento se completa con éxito.

Pruebe periódicamente el proceso externo para identificar posibles fallos. Si es necesario, ajuste esta configuración para evitar interrupciones en el procesamiento de la respuesta.

Prueba del webhook

Realice pruebas exhaustivas de su webhook antes de habilitarlo para un asistente que se utilice en un entorno de producción.

El webhook se activa sólo cuando su asistente procesa un mensaje y una respuesta está lista para ser devuelta al canal.

Resolución de problemas del webhook

Los códigos de error siguientes pueden ayudarle a localizar la causa de los problemas que se puede encontrar. Si tiene una integración de chat web, por ejemplo, sabrá que su webhook tiene un problema si cada mensaje de prueba que envía devuelve un mensaje como There is an error with the message you just sent, but feel free to ask me something else. Si aparece este mensaje, utilice una herramienta de API REST, como cURL, para enviar una solicitud de API /message de prueba, de modo que pueda ver el código de error y el mensaje completo que se devuelve.

Cuerpo de solicitud de ejemplo

Es útil conocer el formato del cuerpo del webhook post-mensaje de petición para que tu código externo pueda procesarlo.

La carga útil contiene el cuerpo de la respuesta que su asistente devuelve para la versión 2 de la llamada a la API /message, con y sin estado. El nombre del evento message_processed indica que el webhook post-mensaje genera la petición. Para obtener más información sobre el cuerpo de la solicitud de mensajes, consulte la referencia de la API.

El siguiente ejemplo muestra cómo se formatea el cuerpo de una solicitud sencilla:

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

Ejemplo 1

Este ejemplo muestra cómo añadir y'all al final de cada respuesta del asistente.

En la página de configuración del webhook post-mensaje, se especifican los siguientes valores:

• URL: https://your-webhook-url/
• Nombre de cabecera: Content-Type
• Valor de cabecera: application/json

El webhook post-mensaje llama a una acción web IBM Cloud Functions de nombre add_southern_charm.

El código node.js de la acción web add_southern_charm tiene el aspecto siguiente:

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

Ejemplo 2

Este ejemplo muestra cómo traducir la respuesta de un mensaje al idioma del cliente. Sólo funciona si realiza los pasos del Ejemplo 2 para definir un webhook previo al mensaje que traduzca el mensaje original al inglés.

Defina una secuencia de acciones web en IBM Cloud Functions. La primera acción de la secuencia comprueba el idioma del texto entrante original, que almacenaste en una variable de contexto llamada original_input en el código del webhook previo al mensaje. La segunda acción de la secuencia traduce el texto de respuesta del diálogo del inglés al idioma original utilizado por el cliente.

En la página de configuración del webhook post-mensaje, se especifican los siguientes valores:

• URL: https://your-webhook-url/
• Nombre de cabecera: Content-Type
• Valor de cabecera: application/json

El código node.js de la primera acción web de la secuencia tiene el aspecto siguiente:

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 segunda acción web de la secuencia tiene el aspecto siguiente:

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

Eliminación del webhook

Si no desea procesar respuestas de mensajes con un webhook, complete los siguientes pasos:

1. En su asistente, vaya a Entornos y abra el entorno en el que desea eliminar el webhook.

2. Pulse el icono para abrir los valores de entorno.

3. En la página Configuración del entorno, haga clic en Webhook post-mensaje.

4. Realice uno de los siguientes pasos:

• Para dejar de llamar a un webhook para procesar cada mensaje entrante, ponga el interruptor de webhook Post-mensaje en Desactivado.

• Para cambiar el webhook que desea llamar, haga clic en Eliminar webhook.