Saltearse al contenido
Nappai Documentation

Message

Guía del Componente de WhatsApp: Envío de Mensajes

El componente Message en Nappai es tu herramienta principal para comunicar con tus clientes o usuarios a través de WhatsApp. Está diseñado para interactuar directamente con la API oficial de WhatsApp Business, permitiéndote automatizar la entrega de notificaciones, respuestas automáticas o campañas de marketing de manera sencilla.

Imagina este componente como un “correo digital” que, una vez configurado, puede enviar mensajes a la velocidad y escala que necesites, ya sea que estés respondiendo a una consulta automática o enviando una actualización importante a una lista de contactos.

¿Cómo funciona?

Internamente, este componente actúa como un puente seguro entre tu flujo de trabajo en Nappai y los servidores de Meta (Facebook).

  1. Preparación: Tú le dices a Nappai a quién enviar el mensaje (el número de teléfono) y qué decirle (el contenido).
  2. Validación: El sistema verifica que el formato del número sea correcto (incluyendo el código de país) y que el mensaje cumpla con las políticas de WhatsApp.
  3. Envío Seguro: Utilizando las credenciales de seguridad que has configurado previamente, el componente se conecta a la API de WhatsApp Cloud.
  4. Confirmación: Una vez enviado, recibe una confirmación indicando si el mensaje fue entregado exitosamente o si hubo algún error.

Conexión y Credenciales

Importante: Para que este componente funcione, es indispensable que primero configures una credencial de WhatsApp Business en Nappai. Sin esto, no habrá conexión con WhatsApp.

Sigue estos pasos antes de usar el componente:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo WhatsApp Business.
    • Deberás ingresar tu API Key, el Identificador del Número de WhatsApp y tu Token de Verificación. Puedes obtener estos datos siguiendo la guía oficial de Facebook Developer.
  3. Una vez guardada la credencial, vuelve a tu flujo de trabajo y en el campo Credential de este componente, selecciona la que acabas de crear.

Operaciones

Este componente ofrece flexibilidad en cómo decides los destinatarios y el contenido. Al seleccionar la operación en el campo Operation, podrás elegir entre:

  • Basic: Utiliza el número de teléfono capturado automáticamente desde un Webhook previo (ideal para respuestas rápidas a mensajes entrantes).
  • Advanced: Te permite ingresar manualmente el número de destino (ideal para enviar mensajes a clientes específicos o listas).

Para usar el componente, primero debes seleccionar la operación que mejor se adapte a tu necesidad en el campo Operation.

Entradas

A continuación, se detallan los campos disponibles para configurar el envío. Recuerda que los nombres de los campos deben leerse exactamente como se muestran en inglés en tu interfaz.

  • Type Operation: Permite elegir entre el modo Básico (usando número del webhook) o Avanzado (usando número manual).

    • Visible en: Basic, Advanced

  • Number Destination: Es el número de teléfono al que enviarás el mensaje. Debe incluir el código de país (ej. +52 para México) pero sin el símbolo ’+’. Solo puedes usar números vinculados a la configuración de tu API.

    • Visible en: Advanced

  • Message Body: Es el texto principal del mensaje que quieres enviar.

    • Visible en: Basic, Advanced

  • Media Content: Si deseas enviar archivos adjuntos (imágenes, documentos, videos), sube el contenido del archivo aquí para que se cargue en WhatsApp.

    • Visible en: Advanced

  • WhatsApp Template: Permite seleccionar plantillas pre-aprobadas por Meta. Las plantillas son útiles para mensajes estructurados o notificaciones oficiales. Ten en cuenta que las plantillas deben ser aprobadas en el Meta Business Suite y pueden tardar hasta 24 horas. Si no ves la plantilla que necesitas, espera a su aprobación.

    • Visible en: Advanced

  • Template Preview: Muestra una vista previa del texto de la plantilla seleccionada, ayudándote a verificar cómo se verá el mensaje antes de enviarlo.

    • Visible en: Advanced

Salidas

Una vez que el componente ha procesado el envío, te proporciona información clave para saber si la acción fue exitosa.

Ejemplo de Respuesta JSON

Al finalizar la operación, recibirás un resultado en formato JSON que puedes usar en siguientes pasos de tu flujo. Este es un ejemplo de lo que podrías recibir al enviar un mensaje con éxito: json { “messaging_product”: “whatsapp”, “contacts”: [ { “inputs”: [ { “id”: “WID-XXXXXXXXXXXXXXX”, “phone”: “+5215512345678” } ], “message_id”: “wamid.HBgNNTUxNTUxMjM0NTY3OAUCABIYFkE5QTRDMkY2RTdCQzhGMEUxNkQ4QkU5QkM3RjE2NjkA”, “statuses”: [ { “id”: “wamid.HBgNNTUxNTUxMjM0NTY3OAUCABIYFkE5QTRDMkY2RTdCQzhGMEUxNkQ4QkU5QkM3RjE2NjkA”, “status”: “sent”, “timestamp”: “1234567890”, “conversation”: { “id”: “WAIDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX”, “expiration_window”: “86400” }, “pricing”: { “billable”: true, “pricing_partner”: “meta” } } ] } ] }

Nota: El campo más útil para los siguientes nodos suele ser el message_id (identificador del mensaje) o el estado dentro del campo Status, que te dirá si fue “sent” (enviado), “delivered” (entregado) o “failed” (fallido).

Conectividad

Este componente es el punto de salida hacia el mundo exterior. Lógicamente, suele conectarse inmediatamente después de:

  1. Webhooks de WhatsApp: Para responder a mensajes entrantes de clientes.
  2. Llamadas a APIs (HTTP Requests): Para obtener datos de clientes (como nombres o estados de pedido) y personalizar el mensaje.
  3. Condicionales (Switch/IF): Para decidir si se debe enviar un mensaje basado en algún criterio (ej. “si el pago fue aprobado, enviar WhatsApp”).

Después de este componente, puedes conectar nodos de Registro (Log) para guardar un historial de los mensajes enviados, o nodos de Tiempo de Espera (Delay) si necesitas pausar el flujo para cumplir límites de la API.

Ejemplo de Uso

Escenario: Eres un sistema de ventas y un cliente ha completado su compra. Quieres enviarle un recibo por WhatsApp.

  1. Entrada: Configuras el componente para usar la operación Advanced.
  2. Número: Insertas manualmente o mapeas el número del cliente desde una base de datos previa.
  3. Mensaje: En el campo Message Body, escribes: “Hola [Nombre], tu pedido ha sido confirmado. Gracias por tu compra.”
  4. Salida: El sistema envía el mensaje. Si la salida indica “sent”, puedes continuar el flujo para actualizar la base de datos como “entregado”. Si dice “failed”, puedes activar una alerta de error.

Consejos y Mejores Prácticas

  • Formato del Número: Asegúrate de que el Number Destination tenga el código de país. Un error común es omitir el código, lo que provocará que el mensaje falle.
  • Plantillas: Si necesitas usar una plantilla, asegúrate de que esté aprobada en el Panel de Meta Business. Los mensajes con plantillas requieren aprobación previa y tienen un costo diferente a los mensajes de texto libre.
  • Manejo de Errores: Si tu flujo es crítico, siempre es recomendable conectar el resultado del componente a un nodo de manejo de errores en caso de que el estado sea “failed”.

Consideraciones de Seguridad

  • Tokens Seguros: Nunca compartas tu API Key o Token de Verificación en foros públicos o commits de código.
  • Cumplimiento de Meta: Asegúrate de que los mensajes que envías cumplan con las políticas de contenido de WhatsApp para evitar que tu número sea bloqueado por spam.