Esta guía te enseñará sobre nuestras herramientas API y lo que puedes hacer con bloques dinámicos y solicitudes externas. Lo ideal es que, después de leerla, tengas un nuevo nivel de comprensión de estas herramientas y seas capaz de resolver cualquier problema que puedas encontrar.
También es importante entender que las herramientas de desarrollo no son similares a otras herramientas en Manychat. Mientras que los disparadores y el creador de flujos fueron creados por nosotros, las herramientas de desarrollo son más parecidas a las herramientas de API que se utilizan en todo Internet.
Para usarlas, es necesario comprender los conceptos básicos de programación, la conexión entre cliente y servidor, el uso de API y la estructura de solicitud de API. Cubriremos todos estos temas a continuación.
Para solucionar problemas con ellas, necesitas entender lo mismo y recordar que los problemas no están relacionados con los sistemas de Manychat en sí mismos, sino que son problemas que encontrarías en cualquier herramienta similar de otros servicios.
Este artículo responderá las siguientes preguntas:
- ¿Qué es una API?
- ¿Qué son los nodos?
- ¿Qué es un nodo dinámico?
- Estructura de la solicitud
- ¿Qué es una ruta JSON?
- ¿Cómo se utiliza nuestra API pública?
- ¿Qué son los métodos POST y GET?
- ¿Qué hace un bloque dinámico?
- ¿Qué hace una solicitud externa?
- ¿Qué es una clave de API?
- Resolución de problemas
- Consejos y limitaciones
- Cosas que debes saber
¿Qué es una API?
API es el acrónimo de Application Programming Interface (Interfaz de Programación de Aplicaciones), un método de interacción entre diferentes aplicaciones o dentro de una sola aplicación. API es la base de nuestra interacción (de Manychat) con Meta. Meta cuenta con una excelente documentación sobre API que puedes consultar para obtener más información.
API se utiliza para conectarse con una aplicación desde el exterior y cambiar, modificar o enviar algo dentro de ella. La base de API es un conjunto de métodos, y la interfaz se caracteriza por estos métodos.
¿Qué son los nodos?
Las automatizaciones están formadas por nodos. Hay un nodo de contenido, el nodo “Send Message” (Enviar mensaje), que consta de bloques. Utilizamos este nodo para enviar mensajes a los contactos de Manychat. Desmontamos los nodos en partes, los cambiamos a un formato comprensible para Meta y los enviamos a Meta a través de API.
¿Qué es un nodo dinámico?
Es un proceso en el que Manychat interrumpe el procesamiento de la automatización, pasa a otras acciones (como una solicitud de servidor externo, alguna acción, etc.) y luego regresa a la automatización.
Estructura de la solicitud
Una solicitud consta de:
- Método o tipo de solicitud (GET, POST, etc.)
- Vínculo
- Opcionalmente: encabezados (incluidas claves de API y autorización)
- Opcionalmente: cuerpo (con el contenido dentro) si es del tipo de solicitud POST
Dos cosas completan el formato de los datos en la solicitud:
- La versión del protocolo que utilizamos (actualmente es la v2)
- El contenido: mensajes, acciones, respuestas rápidas, etc. Así es exactamente como se ven los nodos de contenido de Manychat. Manychat solo admite las acciones disponibles en Manychat. Aquí hay algunos ejemplos.
La opción de fallback se activa en caso de una respuesta incorrecta del servidor en un bloque dinámico, generalmente cuando el servidor devuelve una falla. Si un miembro del equipo especifica algún contenido en el fallback, este contenido se enviará a aquellos contactos para quienes la solicitud falló.
Si no hay fallback y la solicitud falla, el resto de la automatización no se procesará y todo se detendrá. Recomendamos utilizar fallback para notificar a los usuarios que algo salió mal en el servidor, pero no para crear la lógica de automatización en él. Fallback se utiliza en situaciones excepcionales.
¿Qué es una ruta JSON?
La ruta JSON es un protocolo cuyo formato se utiliza para extraer una respuesta de un sistema externo y guardarla en un campo de usuario personalizado; el servidor devuelve una respuesta que consta de propiedades y sus valores.
El mapeo de respuestas te permite guardar algunos de los valores en campos de usuario personalizados ingresando la ruta JSON a esos valores.
Nuestras integraciones (Hubspot, ConvertKit, etc.) y Meta lo utilizan.
¿Cómo se utiliza nuestra API pública?
Nuestra API pública se puede utilizar para cambiar el estado de los contactos en cualquier momento y enviarles mensajes; básicamente, te permite realizar ciertas acciones desde fuera de Manychat. Sirve para eventos externos que Manychat no conoce y sobre los que debe notificar a los contactos.
Por ejemplo, tienes un servicio de entregas. La información de seguimiento del producto se actualizó y sabes de quién es el pedido. Llamas a un método para ese contacto específico para notificarlo, y la persona recibe un mensaje.
¿Qué son los métodos POST y GET?
El método POST cambia los datos de la cuenta o del contacto, por ejemplo, con Set Custom Field (Establecer campo personalizado), Send Content (Enviar contenido) o Set Bot Field (Establecer campo de bot). También se utiliza para pasar parámetros al servidor para realizar determinadas acciones.
Tomemos la API setCustomField como ejemplo. Si quieres establecer un campo de usuario personalizado con un valor específico para un contacto específico, debes informar al servidor el ID del contacto, el nombre del campo y el valor que quieres establecer.
El método GET obtiene información de cuenta o contacto a través de Get Info (Obtener información), Get Bot Fields (Obtener campos de bot), etc. En solicitudes como esa, esperamos una respuesta del servidor externo de inmediato. Una solicitud GET no tiene cuerpo.
Un ejemplo más simple: GET encontrará y devolverá el valor de un campo de usuario personalizado, y POST cambiará o enviará el valor del campo de usuario personalizado a algún lugar.
La solicitud del método SendContent acepta mensajes en el mismo formato JSON utilizado para el Bloque dinámico.
Los métodos POST y GET se pueden usar para acciones y solicitudes similares, pero se entiende que GET obtiene los datos de algún lugar y POST modifica o envía los datos.
¿Qué hace un bloque dinámico?
El propósito más básico del bloque dinámico es ir al servidor externo, obtener el código JSON, transformarlo en un mensaje y enviar este mensaje a un contacto.
El bloque dinámico se puede utilizar para disparar nuestra API, pero ese no es su propósito principal. No garantizamos que funcione correctamente y es posible que nuestra API no devuelva nada al bloque dinámico. Casi todas las solicitudes configuradas de esta manera se pueden crear en la interfaz interna nativa.
Una nota importante sobre el uso de botones de nodo: si un bloque dinámico intenta acceder a nuestra API pública con el código que incluye un botón de Go To Node (Ir a nodo) o una respuesta rápida, no funcionará. El bloque dinámico funciona dentro del contexto de la automatización, pero cuando dispara la API pública, sale de ese contexto y no se encontrará la automatización.
💡 Puedes ver los registros de fallas y advertencias relacionados con las solicitudes de bloqueo dinámico en Settings (Configuración) → Logs (Registros).
¿Qué hace una solicitud externa?
El objetivo más básico de la solicitud externa es ir al servidor externo y:
- Guardar algunos datos allí
- Cambiar datos allí
- Obtener algunos datos allí y devolverlos a Manychat con el mapeo de la solicitud
- Algunos o todos los anteriores
También se pueden utilizar solicitudes externas para disparar nuestra API pública con algunos valores predefinidos en su interior. Por ejemplo, para enviar el valor de un campo de usuario personalizado de un contacto a otro dentro de un bot.
¿Qué es una clave de API?
Una clave de API es un código que identifica al usuario, desarrollador o programa que envía solicitudes para acceder a un sitio web. Manychat proporciona una clave de API (función PRO) para utilizar con la API pública de la cuenta. La clave de API pública se puede encontrar en Settings (Configuración) → API.
Además, existe una API pública de perfiles que se utiliza para conectar con elementos no relacionados con bots específicos, como las plantillas. Se requiere una clave diferente que se puede encontrar aquí.
Resolución de problemas
A continuación se abordarán fallas específicas y consejos de configuración. Aquí, desarrollaremos la introducción y profundizaremos en la solución de problemas.
Si no sabes qué pasa, busca la falla en línea. A menudo encontrarás la solución en los foros de Stack Overflow o en cualquier sitio web de programación, incluidos los foros de Meta Support. Recuerda que las fallas de las herramientas de desarrollo no son exclusivas de Manychat: son comunes para todas las herramientas como esta. Aquí está la lista de códigos de estado de fallas comunes del protocolo HTTP.
Recomendamos enfáticamente que te familiarices con nuestras solicitudes de API disponibles y ejemplos de código JSON.
Estos dos vínculos responden a todas las preguntas sobre las posibilidades de nuestra API pública. Si no puedes ver el método que estás buscando, entonces no existe. Sin embargo, puedes publicar una solicitud de función aquí.
Es posible que necesites usar JSON Lint o una herramienta similar para verificar que el código JSON sea correcto, ya que nuestro verificador podría haber pasado por alto algún error, aunque eso ocurre rara vez. Recuerda que es posible que necesites desactivar la casilla Encode to JSON (Codificar a JSON), y que no es necesario encerrar entre comillas (“”) los campos personalizados de usuario que se inserten.
¿Qué es la casilla de verificación Encode to JSON?
Todos los sitios web tienen un protocolo determinado para aceptar solicitudes. La mayoría de ellos tienen toneladas de indicadores, filtros y decodificadores que transfieren el código JSON enviado desde nuestro lado a algo que el sitio web pueda entender. Algunos solo aceptan código JSON estricto. Encode to JSON (Codificar a JSON) te permite transformar el valor de los campos en JSON, lo que también es necesario cuando solo tienes variables en el cuerpo de la solicitud, como con {{Full Contact Data}}.
Postman te permitirá verificar y probar rápidamente cualquier solicitud de API.
Vínculos que te ayudarán a resolver cualquier pregunta sobre la ruta JSON o Request mapping (Mapeo de solicitudes):
- JSON formatter te ayudará a formatear la cadena JSON como un código que sea fácil de leer y comprender
- Esta documentación de ruta JSON explicará los comandos de ruta JSON y su formato correcto y proporcionará algunos ejemplos
- Este probador de expresiones de JSONPath te ayudará a probar rápidamente una ruta JSON específica con un código JSON
Consejos y limitaciones
Si quieres ver cómo funciona un bloque dinámico con un mensaje de un servidor externo, puedes crear el tuyo en cuestión de minutos: sigue los pasos de este artículo.
Si un servidor al que estás llamando no requiere autorización y quieres ver qué respuesta devuelve en una nueva pestaña, puedes instalar una extensión de Google Chrome como JSON Formatter para verla estructurada en líneas:
También puedes copiar la respuesta desde la pestaña o las herramientas de desarrollo después de probar la solicitud y usar un formateador JSON en línea como este para estructurarla en líneas:
También te permitirá ver a qué pertenecen ciertos corchetes en el código.
Cosas que debes saber
- La longitud de la URL de solicitud está limitada a 2000 símbolos.
- Si completas un campo de usuario personalizado dentro de la tarjeta del contacto, el límite es de 4000 caracteres. Pero si guardas el valor del mensaje de un contacto en Messenger con un Data Collection block (Bloque de recopilación de datos), el límite es de aproximadamente 20 000 (es el límite de caracteres para un mensaje en Messenger). No existe un límite real para los campos de API y bot.
- El tiempo de espera está limitado a 10 segundos. Y no se puede modificar.
- “https://” en la dirección de solicitud es necesario en el cuadro Request URL (URL de solicitud), incluso si un campo ya lo contiene.
- La URL de solicitud solo admite vínculos https.
- No es posible mapear un mensaje de falla si el código devuelto no es 200 OK y, de alguna manera, reaccionar a cada falla específica.
- No es posible mapear los valores de respuesta al probar la solicitud. Solo es posible hacerlo cuando se activa la herramienta de desarrollo como contacto o se obtiene una vista previa de la automatización.
- Solo es posible mapear un código JSON. No se admiten otros formatos.