Saltearse al contenido
Nappai Documentation

Instagram Webhook

El componente Instagram Webhook es la puerta de entrada para conectar tu cuenta de Instagram con el sistema de automatización Nappai. Imagina que funciona como un “receptor” inteligente que está atento a todo lo que sucede en tu cuenta. Cada vez que alguien te envía un mensaje en Instagram Direct (DM) o comenta en una publicación, este componente captura esa información instantáneamente y la organiza para que otros automatismos puedan procesarla.

Su principal ventaja es que separa automáticamente lo que recibe en dos categorías claras: texto (mensajes escritos) y multimedia (imágenes o videos), permitiéndote tratar cada tipo de interacción de la manera más adecuada.

¿Cómo funciona?

Internamente, este componente actúa como un puente seguro entre la infraestructura de Meta (la empresa matriz de Instagram) y tu flujo de trabajo en Nappai.

  1. Escucha Activa: El componente mantiene un “oído atento” en el sistema. Cuando un usuario interactúa con tu cuenta de Instagram (por ejemplo, te envía un mensaje), Instagram notifica automáticamente a Nappai.
  2. Clasificación Inteligente: En lugar de enviarte toda la información mezclada, el componente analiza la recepción y la divide en dos caminos claros:
    • Mensaje: Si el usuario envió texto, este camino se activa. Es ideal si quieres que tu asistente de IA lea el texto y responda con palabras.
    • Medio: Si el usuario adjuntó una foto o un video, este camino se activa. Es útil si quieres que tu asistente analice el contenido visual de esa imagen.
  3. Procesamiento: Una vez clasificado, el dato se transforma en una estructura lista para ser usada por otros componentes (como un modelo de lenguaje o una IA de visión), permitiéndote crear chatbots inteligentes que entiendan tanto lo que escribes como las fotos que envías.

Conexión y Credenciales

Para que este componente pueda “escuchar” lo que sucede en tu cuenta de Instagram, es obligatorio establecer una conexión segura con la cuenta de desarrollo de Meta. Esto se hace a través de una Credencial.

Sigue estos pasos para configurarlo correctamente:

  1. Obtén tus credenciales: Antes de abrir Nappai, asegúrate de haber generado tu API Access Token y tu Verification Token siguiendo la guía oficial de Instagram Basic Display API Guide. Asegúrate de activar los permisos instagram_basic y instagram_manage_comments.
  2. Crea la credencial en Nappai:
    • Dirígete a la sección de Credenciales en tu panel de Nappai.
    • Crea una nueva credencial del tipo Instagram.
    • Ingresa los datos necesarios (Identificador de API, Token de Acceso, Token de Verificación).
  3. Vincula el componente:
    • Vuelve a tu flujo de trabajo y selecciona el componente Instagram Webhook.
    • En el campo Credential, selecciona la credencial que acabas de guardar.

Sin este paso previo, el componente no tendrá permiso para recibir datos de Instagram.

Entradas

Los detalles técnicos avanzados, como los tokens de acceso y las claves de seguridad, ya han sido manejados en el paso de configuración de la Credencial mencionada arriba. Por lo tanto, este componente no requiere que ingreses datos manualmente en sus campos de entrada después de conectar la credencial; su función es puramente receptiva y procesadora.

Salidas

Cuando se recibe una notificación de Instagram, el componente genera dos tipos de resultados distintos que puedes conectar a otros pasos de tu automatización:

  • Message: Contiene los datos del mensaje de texto recibido. Úsalo si quieres que tu IA responda por texto.
  • Media: Contiene la información sobre las imágenes o videos recibidos. Úsalo si quieres que tu IA analice fotos o videos.

Ejemplo de Respuesta JSON

A continuación, puedes ver cómo se ve la información que sale del componente cuando llega un mensaje de texto (salida Message): json { “object”: “instagram”, “entry”: [ { “id”: “17841405722753896”, “time”: 1572356826790, “messaging”: [ { “sender”: { “id”: “1234567890” }, “recipient”: { “id”: “9876543210” }, “timestamp”: 1572356824069, “message”: { “is_echo”: false, “app_id”: 123456789, “mid”: “wIGAAAAkFV65QKj4bYx0kZbqHfXyM_”, “text”: “Hola, necesito ayuda con mi pedido” } } ] } ] }

Nota: La salida Media tendría una estructura similar pero en lugar del campo text, contendría datos binarios o URLs de imágenes/videos.

Conectividad

Este componente es la fuente de información en tu flujo. Por lo general, sus salidas se conectan a:

  • Modelos de Lenguaje (LLMs): Conectando la salida Message a un modelo de IA para generar respuestas automáticas.
  • Modelos de Visión: Conectando la salida Media a una IA capaz de “ver” imágenes para describir objetos o analizar contenido.

Es el punto de partida ideal para crear botones de respuesta automática en Instagram Direct.

Ejemplo de Uso

Escenario: Quieres responder automáticamente a los clientes que te escriben en Instagram Direct para pedir precios.

  1. Usas el componente Instagram Webhook con tu credencial de Instagram conectada.
  2. Tomas la salida Message.
  3. La conectas a un componente Assistant Agent (Agente de Asistente) que ha sido entrenado con tu lista de precios.
  4. El agente lee el mensaje del cliente (“¿Cuánto cuesta el servicio X?”), calcula el precio y, mediante otro componente de salida, envía la respuesta de vuelta al usuario en Instagram.

Consejos y Mejores Prácticas

  • Verifica tu Credencial: Asegúrate de que tu cuenta de Instagram en Meta Developers tenga los permisos correctos (instagram_basic y instagram_manage_comments) o el webhook fallará al intentar leer mensajes.
  • Separa Textos de Fotos: Si tu flujo solo debe responder textos, usa únicamente la salida Message. Si intentas enviar una foto por la rama Message, es posible que el sistema marque un error.
  • Entorno de Desarrollo: Este componente está optimizado para entornos de prueba. Si estás configurando el webhook localmente en tu computadora, asegúrate de usar una herramienta como “ngrok” para generar una URL pública accesible desde Internet, ya que Instagram necesita enviar los datos a una dirección web válida.

Consideraciones de Seguridad

  • Acceso Restringido: Asegúrate de no compartir las credenciales de Instagram (tokens de acceso) públicamente.
  • Validación de Datos: El sistema espera datos estructurados de Meta. Si envías datos desde otras fuentes fuera de Instagram, el proceso de validación podría rechazarlos.