n8n-nodes-ycloud

Community node para integrar YCloud WhatsApp API en n8n. Cobertura completa del API v2 de WhatsApp Business.

Compatibilidad

• n8n: >= 1.0.0
• Node.js: >= 18.17

Recursos y operaciones

Message

• sendDirectly — envío sincrónico
• enqueue — envío asíncrono con filtros filterUnsubscribed / filterBlocked
• retrieve — recuperar mensaje por ID
• list — listar mensajes paginados con filtros (WABA, from, to, status, externalId)

Tipos soportados: text, template, image, document, video, audio, sticker, location, reaction, contacts, interactive (button/list/cta_url/flow/product).

Template

• list — con filtros WABA/name/language y includeTotal
• retrieve — por WABA + name + language
• create — con categoría UTILITY / MARKETING / AUTHENTICATION, componentes JSON, TTL, sub-categoría
• delete — por name+language o por name (todas las lenguas)

Dropdown dinámico desde la credencial: muestra el body text de cada plantilla como preview para saber cuántas variables necesitas.

Contact

• CRUD completo: list, create, retrieve, update, delete
• Campos: nickName, realName, email, countryCode, tags (CSV), customAttributes (JSON)

Inbound Message

• markAsRead
• typingIndicator

Media

• upload — sube un binario desde el input de n8n y devuelve el mediaId para usar en mensajes posteriores

Phone Number

• list, retrieve, getProfile, updateProfile, register

Business Account

• list, retrieve

Webhook Endpoint

• CRUD completo: create, list, retrieve, update, delete

Flow

• list, retrieve, create, publish, updateStructure

Balance

• retrieve

Credenciales

Credencial YCloud API:

• baseUrl (por defecto: https://api.ycloud.com)
• apiKey (header X-API-Key)

Test de credencial: GET /v2/balance.

Template Messages — Variables del body

1. Elige Message Type: Template y Template Source: From YCloud.
2. Selecciona la WABA (dropdown dinámico).
3. Selecciona la plantilla del dropdown — la descripción muestra el body text con {{1}}, {{2}}...
4. Añade los valores en Template Body Variables en el orden de los placeholders.
5. Activa Validate Placeholder Count para que el nodo compare contra la plantilla remota antes de enviar.

Para header/buttons/carousel usa Template Components JSON (Advanced) con el schema de Meta.

Desarrollo local

npm install
npm run build
npm run lint

Cargarlo en n8n local

npm run build
npm link
cd /ruta/a/n8n
npm link n8n-nodes-ycloud

Reinicia n8n y busca el nodo YCloud.

Release

Ver DEPLOY.md.

Notas de implementación

• Validación E.164 para from/to.
• Manejo explícito de errores 401/403/404/429/5xx con requestId.
• Retries automáticos en 429 respetando Retry-After (o backoff exponencial con jitter).
• Transporte interno soporta GET, POST, PATCH, PUT, DELETE + multipart para media upload.
• En continueOnFail, devuelve error estructurado por item.

Changelog

0.4.0

• Cobertura completa del WhatsApp API v2: media, phone numbers, business accounts, webhooks, flows, balance.
• Mensaje: document, video, audio, sticker, location, reaction, contacts, interactive.
• Templates: create + delete.
• Contacts: CRUD completo.
• Dropdown de plantillas mejorado con body preview.
• Transport con soporte para PATCH/PUT/DELETE y multipart uploads.

0.3.0

• Plantillas dinámicas desde YCloud.
• Validación de placeholders.

0.1.0

• MVP (text/template/image).