Solicitudes Externas

Modificado el jueves, 16 de noviembre de 2023 a las 3:29 p.m.

Entendiendo las Solicitudes Externas 

Las solicitudes externas son el medio por el cual tu chatbot se comunica con otros programas o servicios en internet. Permiten que tu chatbot recupere información de estos servicios o comparta información con ellos de manera fluida. Esencialmente, es la forma en que tu chatbot hace preguntas o intercambia información con el mundo digital más amplio.

La función de Solicitud Externa permite la interacción con servicios externos, APIs (Interfaces de Programación de Aplicaciones) o sitios web para recuperar datos o realizar acciones. Te permite obtener datos de cualquier otro sistema y presentarlos al usuario dentro de tu chatbot.

Tipos de Solicitudes Externas 

Existen dos tipos principales de solicitudes externas: HTTP GET y HTTP POST, cada una con propósitos distintos. Vamos a profundizar en estos tipos y entender cuándo emplear cada uno:

HTTP GET:

Propósito:

• La solicitud HTTP GET se utiliza para recuperar datos de un recurso especificado sin alterarlo ni modificarlo. Se usa principalmente para obtener información.

Características:

• Los parámetros se envían en la URL como parámetros de consulta.
• Las solicitudes GET suelen ser almacenadas en caché por los navegadores, lo que las hace adecuadas para operaciones importantes y de sólo lectura.
• Las solicitudes GET son visibles en la URL, por lo que no se deben incluir datos sensibles (como contraseñas) en ellas.

Casos de Uso:

• Recuperar datos de una API pública, como información meteorológica o titulares de noticias.
• Obtener el perfil de un usuario pasando su nombre de usuario en la URL.
• Acceder a páginas web o recursos en un navegador web haciendo clic en enlaces.

Cuándo Usar GET:

• Cuando necesitas recuperar datos de un servidor o fuente externa.
• Para operaciones de sólo lectura que no modifican el estado del servidor.
• Cuando los parámetros de la solicitud o datos pueden ser incluidos en la URL (por ejemplo, en parámetros de consulta).

HTTP POST:

Propósito: 

• La solicitud HTTP POST se utiliza para enviar datos a un recurso especificado para ser procesados. Se usa principalmente para enviar datos y crear o actualizar recursos en el servidor.

Características:

• Los parámetros y datos se envían en el cuerpo de la solicitud, lo que la hace adecuada para enviar grandes cantidades de datos.
• Las solicitudes POST no se almacenan en caché por defecto y no exponen datos sensibles en la URL.
• Se utilizan para acciones que pueden modificar el estado del servidor y no son independientes (lo que significa que múltiples solicitudes idénticas pueden tener diferentes resultados).

Casos de Uso:

• Enviar un formulario en un sitio web para crear una nueva cuenta de usuario.
• Subir un archivo a un servidor.
• Enviar datos a una API para actualizar las preferencias de un usuario.

Cuándo Usar POST:

• Cuando necesitas enviar datos a un servidor o servicio externo.
• Para operaciones que crean, actualizan o eliminan recursos en el servidor.
• Cuando los datos son sensibles y no deben exponerse en la URL.

Cuándo Elegir Entre GET y POST:

• Usa GET cuando quieras recuperar datos de una fuente externa, especialmente si la operación es idempotente (solicitudes repetidas tienen el mismo resultado).
• Usa POST cuando necesites enviar datos a una fuente externa para crear, actualizar o eliminar recursos, o cuando los datos sean sensibles y no deban exponerse en la URL.

Configurando la Solicitud Externa 

En el Flow Builder, añade Acciones > Solicitud de API Externa.

Cómo guardar datos en un campo personalizado

Puedes usar el mapeo de respuestas para guardar datos de una API en un campo personalizado si la API devuelve datos en formato JSON. Muchas veces, es posible que desees obtener datos de una API y mostrarlos al usuario.

Por ejemplo, utilizaremos una API de intercambio de divisas para mostrar cómo podrías guardar los datos devueltos por una API en un campo personalizado. A continuación se muestra la respuesta de la API:

Si deseas mostrar el valor en dólares estadounidenses (USD), necesitarás usar las tasas de cambio para convertir desde otra moneda a USD.

Para hacerlo, puedes probar tu solicitud, copiar la respuesta que recibas y usar un servicio que te ayude a extraer los datos correctos usando JSONPath (una manera de navegar y extraer datos de formato JSON).

Este servicio también puede verificar si tu JSONPath es correcto. No necesitas comenzar tu expresión JSONPath con "x" cuando uses este servicio. Es una herramienta para asegurarte de que estás obteniendo la información correcta de los datos que recibes.

Hay dos formas de mostrar los datos que obtienes de una API al usuario en tu chatbot

1. Campo Personalizado y Mapeo de Respuestas: Puedes almacenar los datos de la respuesta de la API en un campo personalizado, actuando como un espacio de almacenamiento. Una vez almacenados, puedes usar este campo personalizado en el flujo de conversación de tu chatbot para mostrar la información al usuario.
2. Contenido Dinámico: Alternativamente, la API puede configurarse para proporcionar mensajes o contenido directamente adecuado para mostrarse dentro de tu chatbot. Esto implica que la respuesta de la API incluya texto o información lista para presentarse al usuario sin necesidad de procesamiento adicional.

Puedes seleccionar el método que mejor se alinee con los requisitos de tu chatbot y la estructura de la API.

Cómo obtener el código de estado HTTP o todo el cuerpo de la respuesta:

En el mapeo de respuestas, puedes usar los siguientes elementos para trabajar con la respuesta de la API:

1. http_status_code: Este elemento te permite capturar el código de estado HTTP de la respuesta de la API. Te indica si la solicitud a la API fue exitosa o encontró un error. Puedes guardar este código de estado en un campo personalizado para su procesamiento posterior.
2. http_response_body: Este elemento te permite capturar todo el cuerpo de la respuesta de la API. Contiene los datos o el contenido devuelto por la API, que también puedes guardar en un campo personalizado si deseas usarlo más adelante en la conversación de tu chatbot.
3. http_download_EXTENSION: Si necesitas descargar un tipo específico de archivo, puedes usar este elemento. Por ejemplo, si deseas descargar un archivo de audio en formato MP3, usarías http_download_mp3.

1. Contenido Dinámico: El contenido dinámico en tu chatbot te permite generar y mostrar contenido directamente desde tu servidor, asegurando compatibilidad en todos los canales de comunicación. El sistema adapta automáticamente el contenido al formato adecuado para el canal del usuario en tiempo real.

Limitación Importante: Sólo puedes utilizar la función de Contenido Dinámico si posees y gestionas la API que proporciona los datos. Si no tienes control sobre la API, aún puedes trabajar con sus datos guardándolos en un Campo Personalizado usando el Mapeo de Respuestas. Posteriormente, puedes mostrar esos datos al usuario en el flujo de tu chatbot usando el Campo Personalizado.

El formato de respuesta para contenido dinámico típicamente se ve así:

Los mensajes contienen las comunicaciones enviadas a los contactos. Puedes enviar cualquier mensaje compatible con los bots de Messenger.

Para capacidades adicionales, consulta la documentación de Facebook. El constructor de chatbots incluye el encabezado 'X-USER-ID' en cada solicitud, y el uso de respuestas rápidas (quick_replies) es opcional.

Puedes enviar un mensaje de texto de la siguiente manera:

Enviar más de un solo mensaje.

Puedes enviar un mensaje de texto con botones, donde puedes tener hasta 3 botones. Cada nombre de botón puede tener hasta 20 letras. Si deseas que algo ocurra cuando alguien hace clic en un botón, utilizas un código especial llamado "Flow ID" como disparador del botón.

Payload:

Puedes usar cualquier ID de flujo o paso como payload. Por ejemplo, si deseas llevar a alguien a una conversación específica cuando hacen clic en un botón, puedes usar el ID de esa conversación como payload. Este artículo también explica cómo usar acciones como payloads.

Al enviar un mensaje, puedes agregar respuestas rápidas a él. Las respuestas rápidas funcionan con diferentes tipos de mensajes como texto, archivos y galerías. Facebook te permite incluir hasta 11 respuestas rápidas en un mensaje. El payload que utilizas para respuestas rápidas es similar al que usas para botones.

En caso de que tengas más de 11 opciones, por favor utiliza la opción de "Opción Múltiple" del bloque de acción Obtener Entrada de Usuario en un bloque de mensaje.

La estructura para los payloads en respuestas rápidas y botones es la misma.

Para enviar una imagen, vídeo, audio o archivo, puedes utilizar la siguiente estructura. Simplemente cambia el "media_type" para especificar si es una imagen, vídeo, audio o archivo. La "URL" debe ser el enlace específico a la imagen, audio, video o archivo que deseas enviar.

Puedes enviar una sola tarjeta, y en esa tarjeta, tanto el título como el subtítulo pueden tener hasta 80 caracteres cada uno.

Puedes enviar una sola tarjeta, y esa tarjeta puede tener hasta 3 botones

Enviar una galería

Enviar una galería es como enviar una colección de tarjetas. Puedes incluir hasta 10 tarjetas en una galería. Para cada tarjeta en la galería, también puedes añadir un botón.

Enviar mensajes soportados solo por WhatsApp

WhatsApp admite varios tipos de mensajes que no son compatibles con los bots de Messenger, incluyendo Listas, Contactos, Ubicaciones o Catálogos. Sin embargo, con Topchat.bot, puedes enviar cualquier tipo de mensaje soportado por WhatsApp. Solo necesitas utilizar la estructura de mensaje detallada en la documentación de WhatsApp, y Topchat.bot manejará automáticamente el parámetro "To" por ti.

Acciones

El campo "Actions" es opcional, lo que significa que no es necesario incluirlo. Las acciones te permiten hacer cosas como añadir o eliminar etiquetas, establecer o quitar campos personalizados, y enviar un flujo.

Añadir Etiquetas

Remover Etiquetas

Establecer Campo Personalizado

Esta acción no solo te permite utilizar cualquier nombre de campo personalizado, sino que también te permite modificar campos del sistema como el número de teléfono, correo electrónico, nombre completo, nombre y apellido.

Enviar Flujo

Para encontrar el ID del flujo, ve a la lista de flujos, haz clic en los tres puntos y selecciona "Obtener enlace". El ID del flujo es el valor numérico en el enlace. Siempre es un número. Puedes combinar tantas acciones como necesites.

Combinar Múltiples Acciones

Tienes la flexibilidad de combinar múltiples acciones en una sola solicitud, lo cual te permite ejecutar varias acciones simultáneamente. Por ejemplo, puedes establecer un campo personalizado y activar un flujo con una sola solicitud.

Utilizar acciones como payload en botones y quick_replies:

Para utilizar una acción como payload en botones, puedes seguir este formato. Sin embargo, ten en cuenta que un payload es típicamente una cadena de texto. Por lo tanto, necesitarás convertir tu objeto de acciones a una cadena JSON. Si estás usando PHP, puedes utilizar la función “Json_encode”para transformar tu objeto de acciones en una representación de cadena.

A continuación, se utiliza la acción anterior como payload del botón: