Definición del webhook

Puede definir una URL webhook para un diálogo, y luego llamar al webhook desde uno o más nodos de diálogo.

La llamada mediante programa al servicio externo debe cumplir estos requisitos:

• La llamada debe ser una solicitud POST HTTP.
• El cuerpo de la solicitud debe ser un objeto JSON (Content-Type: application/json).
• La respuesta debe ser un objeto JSON (Accept: application/json).
• La llamada debe regresar en 8 segundos o menos. Si se inicia más de una vez en una sola llamada de mensaje a través de nodos de diálogo, todas estas invocaciones deben devolverse en 8 segundos o menos.

Si su servicio externo sólo admite solicitudes GET, o si necesita especificar parámetros de URL dinámicamente en tiempo de ejecución, considere la posibilidad de crear un servicio intermedio que acepte una solicitud POST con una carga útil JSON que contenga cualquier valor en tiempo de ejecución. A continuación, el servicio intermedio puede efectuar una solicitud al servicio de destino, en la que pasará estos valores como parámetros de URL, y, a continuación, devolver la respuesta al diálogo.

Si necesita llamar a un servicio cuyo retorno podría ser superior a 8 segundos, puede gestionar la llamada a través de una aplicación cliente personalizada y pasar la información al diálogo como un paso independiente. Para obtener más información, consulte Solicitud de acciones de cliente.

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

1. En el diálogo donde desea añadir el webhook, pulse Webhooks.

2. 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, para llamar al servicio Language Translator, especifique la URL de su instancia de servicio.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   Si la aplicación externa a la que llama devuelve una respuesta, debe ser capaz de devolver una respuesta en formato JSON. Para el servicio Language Translator, por ejemplo, debe especificar el formato en el que desea que se devuelva el resultado. Puede hacerlo pasando una cabecera al servicio.

3. En la sección Headers, añada las cabeceras que quiera pasar al servicio de una en una, pulsando Añadir cabecera.

   Por ejemplo, esta cabecera indica que la solicitud está en formato JSON.

   Ejemplo de cabecera

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

4. Si el servicio externo requiere que pase las credenciales de autenticación básica con la solicitud, proporciónelas. Pulse Añadir autorización, añada sus credenciales a los campos Nombre de usuario y Contraseña y, a continuación, pulse Guardar.

   El producto crea una serie ASCII codificada en base 64 a partir de las credenciales y genera una cabecera que se añade a la página.

   Ejemplo de cabecera

   Nombre de cabecera	Valor de cabecera
   Autorización	Básico <encoded-credentials>

   Si utiliza la integración del chat web y activa la seguridad, puede utilizar el mismo token que utiliza para proteger el chat web en el encabezado Autorización. Para obtener más información, consulte Conversación web: Reutilización de una JWT para la autenticación de webhooks.

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

Agregar una llamada de webhook a un nodo de diálogo

Para utilizar un webhook desde un nodo de diálogo, debe habilitar los webhooks en el nodo y, a continuación, añadir detalles a la llamada.

1. Busque el nodo de diálogo en el que desea añadir una llamada. La llamada al webhook se produce siempre que este nodo se activa durante una conversación con un usuario.

   Por ejemplo, es posible que desee enviar una llamada a un webhook desde el nodo #General_Greetings.

2. Pulse para abrir el nodo de diálogo y, a continuación, pulse Personalizar.

3. Desplácese hasta la sección de webhook. Activa el interruptor Call out to webhooks / actions.

4. Seleccione Llamar a un webhook y, a continuación, pulse Aplicar.

   Si aún no lo ha habilitado, el conmutador Varias respuestas condicionadas se establece automáticamente en Activado. Este valor se habilita para permitir añadir distintas respuestas, según el éxito o fracaso de la llamada al webhook. Si ya se ha especificado una respuesta para el nodo, ésta se convierte en la primera respuesta condicional.

5. Añada los datos que quiera pasar a la aplicación externa como pares de clave y valor, en la sección Parámetros.

   Los parámetros se pasan como propiedades del cuerpo de la solicitud. No puede especificar parámetros de consulta ni parámetros de URL en un nodo de diálogo. Estos parámetros sólo pueden configurarse con valores estáticos como parte de la definición del webhook. Para obtener más información, consulte Definición del webhook.

   Por ejemplo, si llama al servicio Traductor de idiomas, debe proporcionar valores para los parámetros siguientes:

   Ejemplo de parámetro

   Clave	Valor	Descripción
   model_id	en-es	Identifica los idiomas de entrada y salida. En este ejemplo, se solicita que el texto en inglés (en) se traduzca a español (es).
   Texto	How are you?	Este parámetro contiene la serie de texto que desea que el servicio traduzca. Puede codificar este valor, pasar una variable de contexto, como $saved_text, o pasar la entrada del usuario al servicio directamente, especificando <? input.text ?> como este valor.

   En casos de uso más complejos, podría recopilar información durante una conversación con un usuario acerca de sus planes de viaje, por ejemplo. Puede recopilar información de fechas y destinos, y guardarla en las variables de contexto que puede pasar a una aplicación externa como parámetros.

   Ejemplo de parámetros de viaje

   Clave	Valor
   depart_date	$departure
   arrive_date	$arrival
   origen	$origin
   destino	$destination

6. Cualquier respuesta realizada por la llamada se guarda en la variable de retorno. Puede cambiar el nombre de la variable que se añade automáticamente al campo Variable de retorno. Si la llamada da como resultado un error, esta variable se establece en null.

   El nombre de la variable generada tiene la sintaxis webhook_result_n, donde el sufijo _n se incrementa cada vez que añades una llamada de webhook a un nodo de diálogo. Esta convención de nomenclatura garantiza que los nombres de las variables de contexto sean únicos en todo el diálogo. Si cambia el nombre, asegúrese de utilizar un nombre exclusivo.

7. En la sección de respuestas condicionales, se añaden automáticamente dos condiciones de respuesta, una respuesta que se muestran al llamar correctamente al webhook y se devuelve una variable de retorno. Y una respuesta que se muestra cuando la llamada falla. Puede editar estas respuestas y añadir más respuestas condicionales al nodo.

   • Si la llamada devuelve una respuesta y conoce el formato de la respuesta JSON, puede editar la respuesta del nodo de diálogo para que incluya sólo la sección de la respuesta que desea compartir con los usuarios.

     Por ejemplo, el servicio Traductor de idiomas devuelve un objeto como este:

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     Utilice una expresión SpEL que extraiga sólo el valor de texto traducido.

     Ejemplo de respuestas condicionales

     Condición	Respuesta
     $webhook_result_1	Sus palabras en español: .
     anything_else	La llamada a la aplicación externa ha fallado. Inténtelo de nuevo más adelante.

     Si se utiliza el formato recomendado para la respuesta y se devuelve la respuesta de traducción mostrada anteriormente, la respuesta del asistente al usuario sería: Your words in Spanish: ¿Cómo estás?

   • Si desea proporcionar una respuesta específica si la llamada devuelve una cadena vacía, lo que significa que la llamada tiene éxito, pero el valor que se devuelve es una cadena vacía, puede añadir una respuesta condicional que tenga una condición con una sintaxis como esta

     $webhook_result_1.size() == 0
     

8. Cuando haya terminado, pulse en la X para cerrar el nodo. Los cambios se guardan automáticamente.

Prueba de los webhooks

Cuando se añade por primera vez una llamada webhook, puede ser útil ver exactamente lo que se devuelve en la respuesta de la aplicación externa, los datos y su formato. Añada esta expresión como respuesta de texto para la respuesta condicional de llamada exitosa: $webhook_result_n donde n es el número apropiado para el webhook que está probando.

Esta respuesta devuelve el cuerpo completo de la variable de retorno, de modo que puede ver lo que devuelve la llamada y decidir qué compartir con el usuario. A continuación, puede utilizar los métodos que se documentan en los métodos del lenguaje de expresión para extraer sólo la información que le interesa de la respuesta.

Probar si determinadas entradas de usuario pueden generar errores en la llamada e incorporar maneras de manejar tales situaciones. Los errores generados por la aplicación externa se almacenan en output.webhook_error.<result_variable>. Puede utilizar una respuesta condicional como esta mientras prueba la captura de dichos errores:

Por ejemplo, podría no autenticar la solicitud adecuadamente (401), o bien podría intentar pasar un parámetro con un nombre que ya se esté utilizando por parte de una aplicación externa. Pruebe el webhook para descubrir y arreglar estos tipos de errores antes de desplegar el webhook.

Eliminar un webhook

Si decide que no desea realizar una llamada de webhook desde un nodo de diálogo, abra la página Personalizar del nodo y, a continuación, cambie Webhooks a Desactivado.

La sección Parámetros y el campo Variable de retorno se eliminan del editor del nodo de diálogo. Sin embargo, las respuestas condicionales que se han añadido automáticamente o que usted mismo haya añadido, se conservan.

La sección Varias respuestas condicionadas vuelve a ser editable. Puedes desactivar esta función. Si lo hace, sólo se guardará la primera respuesta condicional como la única respuesta de texto del nodo.

Para cambiar el servicio externo que llama desde los nodos de diálogo, edite los detalles de webhook definidos en la página de Webhooks del separador Opciones. Si el nuevo servicio espera que se le pasen parámetros distintos, asegúrese de actualizar los nodos de diálogo que lo llaman.

Actualización de output.generic con un webhook

Puede utilizar un webhook para actualizar output.generic y proporcionar respuestas dinámicas. Para obtener más información, consulte el artículo del blog Cómo añadir dinámicamente opciones de respuesta a nodos de diálogo.