Description

n8n-nodes-wafly


This is an n8n community node for the Wafly WhatsApp Bridge API. It lets you send WhatsApp messages, manage groups and configure webhooks directly from your n8n workflows.

Wafly is a managed WhatsApp API platform: cloud-hosted instances connected via QR Code, REST API, real-time webhooks and unlimited messages.

🧩 Ready-made workflow templates

Five workflows you can import and run, instead of starting from a blank canvas:

| Template | What it does |
|—|—|
| AI agent replies once | Buffers messages that arrive in a burst so your agent answers once instead of three times |
| Qualify inbound leads | Scores the conversation with AI and hands hot leads to a human |
| Moderate a group | Approves join requests, welcomes members and removes link spam |
| Send OTP with SMS fallback | Validates the number first, falls back to SMS when WhatsApp is unreachable |
| Alert on disconnect | Checks the connection on a schedule and alerts when the number drops |

Import the JSON, create the Wafly API credential and activate. All of them run on
self-hosted n8n, since community nodes are not available on n8n Cloud.

Portuguese versions of these flows are in examples/templates.

🚀 Features

📱 Instance

• Get the QR Code to connect
• Check the connection status
• Connect / disconnect the instance
• Restart the instance
• Get device information
• Check whether phone numbers exist on WhatsApp
• Message Buffer — group split messages so an AI agent answers once, not once per message
• Audio Transcription — received voice notes arrive transcribed in the webhook, using your own OpenAI key

📡 Newsletter / Channel, Community, Chat, Call

• Full coverage of the published API: newsletters and channels, communities,

chat management and the calls beta. See Operation under each resource.

💬 Messages

• Send text
• Send image
• Send video
• Send audio
• Send document
• Send location
• Send contact card
• Send polls
• Send links with preview
• Delete messages

👥 Groups

• Create groups
• List groups (with optional pagination)
• Get group metadata
• Add / remove participants
• Approve / reject pending participants
• Promote / demote admins
• Leave a group
• Update name, description and photo
• Get and reset the invite link
• Update group settings

🔔 Webhooks

• Set the webhook URL
• Get the webhook configuration
• Delete the webhook

📦 Installation

Install from the n8n UI

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-wafly
5. Click Install

Manual installation

If you run n8n locally, you can install the package via npm:

npm install n8n-nodes-wafly

If you run n8n via Docker, add it to your docker-compose.yml:

version: '3'
services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8NCOMMUNITYPACKAGES=n8n-nodes-wafly
    volumes:
      - ~/.n8n:/home/node/.n8n

🔑 Credentials

Before using the node, create a credential of type Wafly API with the following fields:

• Client Token: Client-Token provided by Wafly
• Instance: Name of your WhatsApp instance
• Token: Token of the instance
• Base URL: https://wafly.com.br/api-bridge-whats (default)

How to get your credentials

1. Open the Wafly dashboard at https://wafly.com.br
2. Log in to your account
3. Go to Instances and create or select an instance
4. Copy the Client-Token, Instance and Token

💡 Usage examples

Example 1: Send a text message

{
  "nodes": [
    {
      "parameters": {
        "resource": "message",
        "operation": "sendText",
        "phone": "5511999999999",
        "message": "Hello! This message was sent via n8n"
      },
      "name": "Wafly",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [250, 300],
      "credentials": {
        "waflyApi": "Wafly API"
      }
    }
  ]
}

Example 2: Create a group and add participants

{
  "nodes": [
    {
      "parameters": {
        "resource": "group",
        "operation": "createGroup",
        "groupName": "My Automated Group",
        "phones": "5511999999999,5511888888888"
      },
      "name": "Create Group",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [250, 300],
      "credentials": {
        "waflyApi": "Wafly API"
      }
    }
  ]
}

Example 3: Check the instance status

{
  "nodes": [
    {
      "parameters": {
        "resource": "instance",
        "operation": "getStatus"
      },
      "name": "Check Status",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [250, 300],
      "credentials": {
        "waflyApi": "Wafly API"
      }
    }
  ]
}

Example 4: Let your AI agent understand voice notes

Half of every WhatsApp conversation in Brazil is a voice note, and an LLM cannot
listen. Set Audio Transcription makes the transcript arrive in the webhook,
so you skip building download + speech-to-text.

The OpenAI key is yours — the cost lands on your own OpenAI account and Wafly
charges nothing for it. It is stored encrypted and never returned by the API.

{
  "nodes": [
    {
      "parameters": {
        "resource": "instance",
        "operation": "setTranscription",
        "transcriptionApiKey": "sk-proj-...",
        "transcriptionMaxAudioSeconds": 300,
        "transcriptionMonthlyCap": 500
      },
      "name": "Transcribe Voice Notes",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [250, 300],
      "credentials": { "waflyApi": "Wafly API" }
    }
  ]
}

Run it once per instance. After that, the audio webhook carries:

{
  "audio": { "audioUrl": "https://...", "seconds": 4 },
  "transcription": { "status": "ok", "text": "oi, queria saber o preço", "latency_ms": 1180 }
}

If the provider refuses (wrong key, quota) or the monthly cap is reached, **the
message still arrives** — only with transcription.status = "error" and the
reason. Nothing is lost.

Leave the key field empty on later calls to keep the stored key and change only
the limits.

Example 4: Stop your AI agent from answering three times

Nobody writes a paragraph on WhatsApp. People send hi, then you there?, then
how much is it? — three separate webhooks, so an AI agent replies three times,
and the first two replies were written without knowing what the person was still
about to type.

Set Message Buffer groups those into a single webhook call:

{
  "nodes": [
    {
      "parameters": {
        "resource": "instance",
        "operation": "setMessageBuffer",
        "bufferWindowSeconds": 8,
        "bufferMaxWaitSeconds": 30,
        "bufferMaxMessages": 10,
        "bufferMode": "concat",
        "bufferIncludeGroups": false
      },
      "name": "Group Split Messages",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [250, 300],
      "credentials": {
        "waflyApi": "Wafly API"
      }
    }
  ]
}

Run it once per instance — it is a setting, not a per-message step.

What your webhook receives after that. Before:

POST /your-webhook   { "text": { "message": "hi" } }
POST /your-webhook   { "text": { "message": "you there?" } }
POST /your-webhook   { "text": { "message": "how much is it?" } }

After:

{
  "phone": "5511999999999",
  "text": { "message": "hinyou there?nhow much is it?" },
  "buffered": { "count": 3, "messageIds": ["...", "...", "..."], "waitedMs": 8012 }
}

The payload keeps the exact same shape, so **an existing workflow keeps working
without edits** — your AI Agent node just receives the whole thought at once.
When a single message arrives, the payload is identical to before, without the
extra buffered field.

| Field | Default | What it does |
|—|—|—|
| Window (seconds) | 8 | Silence window. Restarts on every new message, so delivery happens when the person stops typing. Max 20. |
| Max Wait (seconds) | 30 | Hard ceiling from the first message, so someone typing non-stop cannot postpone delivery forever. Max 30. |
| Max Messages | 10 | Deliver immediately once this many pile up. Max 50. |
| Mode | concat | concat keeps the usual payload shape. batch adds a bufferedMessages array and changes it. |
| Include Groups | false | Grouping in group chats is per participant — different people never get merged. |

> Media, reactions and button replies are never grouped. If text is still waiting
> in the window when an audio arrives, the pending text is delivered first, so
> the conversation never reaches your agent out of order.

Use Get Message Buffer to read the current setting and **Disable Message
Buffer** to go back to one webhook call per message.

Example 4: Full workflow — daily message

This workflow sends an automatic message every day at 9am:

{
  "name": "Daily WhatsApp Message",
  "nodes": [
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "cronExpression",
              "expression": "0 9   *"
            }
          ]
        }
      },
      "name": "Cron - 9am Every Day",
      "type": "n8n-nodes-base.cron",
      "typeVersion": 1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "resource": "message",
        "operation": "sendText",
        "phone": "5511999999999",
        "message": "Good morning! Automatic 9am reminder."
      },
      "name": "Send Message",
      "type": "n8n-nodes-wafly.wafly",
      "typeVersion": 1,
      "position": [450, 300],
      "credentials": {
        "waflyApi": "Wafly API"
      }
    }
  ],
  "connections": {
    "Cron - 9am Every Day": {
      "main": [
        [
          {
            "node": "Send Message",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

📚 API documentation

For more information about the available endpoints and their parameters, see the full API documentation:

• Wafly API documentation
• Base URL: https://wafly.com.br/api-bridge-whats

🛠️ Development

Prerequisites

• Node.js v18 or later
• npm v9 or later
• A local n8n installation (for testing)

Local setup

Clone the repository
git clone https://github.com/iagovelasco3/n8n-nodes-wafly.git
cd n8n-nodes-wafly
Install dependencies
npm install
Compile the TypeScript code
npm run build
Link the package locally
npm link
In the n8n directory, link the package
cd ~/.n8n
npm link n8n-nodes-wafly

Build

npm run build

Lint

npm run lint
npm run lintfix  # auto-fix

🔐 Security

• Never share your credentials (Client-Token, Instance, Token)
• Use environment variables to store sensitive credentials
• Keep your n8n installation up to date
• Always use HTTPS

🐛 Reporting issues

Found a bug or have a suggestion? Open an issue on GitHub:

https://github.com/iagovelasco3/n8n-nodes-wafly/issues

📄 License

MIT License — see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/MyFeature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/MyFeature)
5. Open a Pull Request

💬 Support

• Email: contato@wafly.com.br
• Website: https://wafly.com.br
• WhatsApp community: Join the group
• Discord community: Join the Discord

🙏 Acknowledgements

• The n8n team for the amazing platform
• The developer community for their contributions

—

Made with ❤️ by the Wafly team