n8n-nodes-plantillawhatsapp

Nodo personalizado de n8n para enviar plantillas (templates) de WhatsApp usando la API de WhatsApp Business.

📋 Descripción

Este nodo permite enviar mensajes de plantilla de WhatsApp que han sido previamente aprobadas por Meta. Es ideal para campañas de marketing, notificaciones automáticas y mensajes transaccionales.

🚀 Características

• ✅ Envío de plantillas con headers dinámicos (texto, imagen, video, documento)
• ✅ Soporte para parámetros variables en el cuerpo del mensaje
• ✅ Integración con WhatsApp Business API (Graph API v22.0)
• ✅ Credenciales seguras para Access Token y Phone Number ID
• ✅ Manejo de errores con opción de continuar en caso de fallo

📦 Instalación

Opción 1: Instalación en n8n (Docker)

# Copiar el directorio al volumen de n8n
docker cp n8n-nodes-plantillawhatsapp n8n:/home/node/.n8n/nodes/

# Entrar al contenedor
docker exec -it n8n sh

# Instalar el nodo
cd /home/node/.n8n/nodes
npm install ./n8n-nodes-plantillawhatsapp

# Reiniciar n8n
exit
docker restart n8n

Opción 2: Instalación local (desarrollo)

cd ~/.n8n/custom
npm install /path/to/n8n-nodes-plantillawhatsapp
n8n restart

🔧 Configuración

1. Crear credenciales de WhatsApp API

En n8n, ve a Credentials y crea una nueva credencial de tipo "WhatsApp API":

• Access Token: Token permanente de WhatsApp Business API
• Phone Number ID: ID del número de teléfono en WhatsApp Business

Dónde obtenerlos:

1. Ve a Meta for Developers
2. Crea una app de WhatsApp Business
3. En la sección de WhatsApp > API Setup:
   • Phone Number ID: Se muestra en la sección "From"
   • Access Token: Genera un token permanente en "System User"

2. Aprobar plantillas en Meta

Antes de usar el nodo, debes crear y aprobar plantillas en Meta Business Manager:

1. Ve a Meta Business Suite
2. Selecciona tu cuenta de WhatsApp Business
3. Ve a Message templates
4. Crea una nueva plantilla con los componentes necesarios
5. Espera la aprobación (puede tardar hasta 24 horas)

📝 Uso

Parámetros del Nodo

Obligatorios:

• Phone Number: Número de teléfono del destinatario (formato: 5215512345678)
• Template Name: Nombre de la plantilla aprobada

Opcionales:

• Language Code: Código de idioma (default: es_MX)
• Header Type: Tipo de header (none, text, image, video, document)
• Header Text: Texto del header (si Header Type = text)
• Header Media Link: URL del media (si Header Type = image/video/document)
• Body Parameters: Parámetros variables para el cuerpo del mensaje

Ejemplo Básico

// Enviar plantilla simple sin parámetros
{
  "phoneNumber": "5215512345678",
  "templateName": "hello_world",
  "languageCode": "es_MX"
}

Ejemplo con Header de Video

{
  "phoneNumber": "5215512345678",
  "templateName": "capicombo_video",
  "languageCode": "es_MX",
  "headerType": "video",
  "headerMediaLink": "https://i.imgur.com/YPFKM5b.mp4"
}

Ejemplo con Parámetros en el Body

{
  "phoneNumber": "5215512345678",
  "templateName": "order_confirmation",
  "languageCode": "es_MX",
  "bodyParameters": [
    {
      "parameter": [
        {
          "type": "text",
          "value": "Juan Pérez"
        }
      ]
    },
    {
      "parameter": [
        {
          "type": "text",
          "value": "12345"
        }
      ]
    }
  ]
}

🔄 Integración con Workflows

Workflow de Campaña de Marketing

[Manual Trigger]
    ↓
[Google Sheets] → Lee lista de clientes
    ↓
[Split in Batches] → Procesa uno por uno
    ↓
[WhatsApp Template Sender] → Envía plantilla
    ↓
[Extract Message ID] → Extrae ID del mensaje
    ↓
[HTTP Request] → Registra en sistema de tracking
    ↓
[Wait 1s] → Evita rate limiting
    ↓
[Loop back]

Ver workflow completo en: marketing/Plantilla de marketing WA envio.json

🛠️ Desarrollo

Compilar el nodo

npm install
npm run build

Desarrollo con watch mode

npm run dev

Estructura del proyecto

n8n-nodes-plantillawhatsapp/
├── credentials/
│   └── WhatsAppApi.credentials.ts    # Definición de credenciales
├── nodes/
│   └── PlantillaWhatsApp/
│       ├── PlantillaWhatsApp.node.ts # Lógica principal del nodo
│       └── plantillawhatsapp.png     # Icono del nodo
├── dist/                             # Build output (generado)
├── package.json
├── tsconfig.json
└── README.md

📊 Respuesta del API

El nodo devuelve la respuesta completa del API de WhatsApp:

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "5215512345678",
      "wa_id": "5215512345678"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgNNTE1NTEyMzQ1Njc4OBUCABIYFjNFQjA2MTUyNEQ0MTJFOEY2NjkzOUEA"
    }
  ]
}

Este message.id puede ser usado para tracking de estados (delivered, read, failed).

🔗 API de WhatsApp Business

Endpoint utilizado: https://graph.facebook.com/v22.0/{phoneNumberId}/messages

Documentación oficial: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates

📚 Recursos Adicionales

• Documentación de uso
• Sistema de tracking de campañas
• Workflows de análisis

🐛 Troubleshooting

Error: "Invalid phone number"

Solución: Asegúrate de usar el formato internacional completo sin espacios ni guiones: 5215512345678

Error: "Template not found"

Solución: Verifica que:

1. La plantilla esté aprobada en Meta Business Manager
2. El nombre de la plantilla sea exactamente igual (case-sensitive)
3. El idioma coincida con el configurado en la plantilla

Error: "Invalid parameter count"

Solución: El número de parámetros en bodyParameters debe coincidir exactamente con las variables definidas en la plantilla ({{1}}, {{2}}, etc.)

El icono no aparece en n8n

Solución: Asegúrate de ejecutar npm run build que copia automáticamente el icono a dist/

📝 Changelog

v0.2.3

• Fix: Agregado script copy:assets para copiar automáticamente el icono PNG durante el build

v0.2.2

• Fix: Corregido error tipográfico en el nombre del archivo del icono

v0.2.1

• Fix: Cambio del nombre de credencial para evitar conflictos con credenciales nativas de n8n

📄 Licencia

MIT

👥 Autor

CapiBobbaBot Team

Nota: Este es un nodo personalizado desarrollado específicamente para CapiBobbaBot. Para uso general, considera usar el nodo oficial de WhatsApp de n8n o adaptarlo a tus necesidades.