@astervia/n8n-nodes-wacraft

n8n community node for wacraft — a WhatsApp Cloud API backend server. This node lets you manage contacts, send messages, handle media, and retrieve templates directly from your n8n workflows.

Installation

Community node (recommended)

1. Open your n8n instance.
2. Go to Settings > Community Nodes.
3. Search for @astervia/n8n-nodes-wacraft and click Install.

Manual installation

cd ~/.n8n/custom
npm install @astervia/n8n-nodes-wacraft

Then restart n8n.

Development (npm link)

git clone https://github.com/Astervia/n8n-nodes-wacraft.git
cd n8n-nodes-wacraft
npm install
npm run build
npm link

cd ~/.n8n
npm link @astervia/n8n-nodes-wacraft

Restart n8n. The Wacraft node will appear in the node picker.

Credentials

Create a Wacraft API credential with the following fields:

Authentication flow

The node authenticates via POST /user/oauth/token using the password grant type. Tokens are cached in memory and automatically refreshed using the refresh_token grant before expiry. If a refresh fails, the node falls back to a fresh password grant.

Resources and operations

Contact

Message

Messaging Product

Messaging Product Contact

Media

Template

Workspace ID override

Every operation includes an optional Workspace ID Override field. When set, it replaces the default workspace ID from the credentials for that specific execution. This is useful when a single n8n instance interacts with multiple wacraft workspaces.

Sending a WhatsApp message

The Send WhatsApp Message operation requires:

• To ID: The messaging product contact ID (not a phone number).
• Sender Data (JSON): The WhatsApp Cloud API message payload.

Example sender data for a text message:

{
    "messaging_product": "whatsapp",
    "type": "text",
    "text": {
        "body": "Hello from n8n!"
    }
}

Example sender data for a template message:

{
    "messaging_product": "whatsapp",
    "type": "template",
    "template": {
        "name": "hello_world",
        "language": {
            "code": "en_US"
        }
    }
}

Testing with Docker

Build and run a custom n8n image with the node pre-installed using Docker Compose:

docker compose -f docker-compose.test.yml up --build

Open http://localhost:5678 and the Wacraft node will appear in the node picker.

If your wacraft server is running on the host machine, use http://host.docker.internal:6900 as the base URL. The compose file already includes the extra_hosts mapping so host.docker.internal resolves correctly on all platforms including Linux.

Development

npm install       # Install dependencies
npm run build     # Compile TypeScript and copy icons
npm run dev       # Watch mode for TypeScript
npm run lint      # Lint with ESLint
npm run lint:fix  # Lint and auto-fix
npm run format    # Format code with Prettier

Project structure

n8n-nodes-wacraft/
├── .github/workflows/
│   ├── codeql-analysis.yml          # CodeQL SAST scanning
│   ├── quality-and-security.yml     # Lint, format, audit, build on push/PR
│   └── release.yml                  # Publish to npm on GitHub Release
├── credentials/
│   └── WacraftApi.credentials.ts    # Credential definition
├── nodes/Wacraft/
│   ├── GenericFunctions.ts          # Auth helpers and API request functions
│   ├── Wacraft.node.ts              # Node definition with all resources
│   └── wacraft.svg                  # Node icon
├── Dockerfile.test
├── docker-compose.test.yml
├── eslint.config.mjs
├── gulpfile.js
├── package.json
└── tsconfig.json

License

MIT