n8n Evolution API Media Downloader

0.1.0 verified Sat Apr 25 auth: no javascript

A community node package for n8n (v0.1.0) that adds a node to download media from Evolution API data messages. This package allows users to process incoming WhatsApp messages containing media (images, audio, video, documents) and download the files directly within n8n workflows. The node integrates with the Evolution API webhook format. It is intended for n8n instances running version 0.218.0 or later. The package is minimal and focused on a single use case, with no additional dependencies beyond n8n-workflow.

Common errors

error ERROR: The import ''n8n-nodes-evolution-api-media-downloader'' could not be resolved ↓

cause Package not installed in the n8n custom nodes directory or missing from package.json

fix

Run npm install n8n-nodes-evolution-api-media-downloader inside the directory where n8n loads custom nodes (usually ~/.n8n/nodes/).

error Error: Cannot find module 'n8n-workflow' ↓

cause Missing peer dependency n8n-workflow

fix

Install n8n-workflow globally: npm install -g n8n-workflow

error TypeError: Cannot read properties of undefined (reading 'mediaUrl') ↓

cause Input data does not contain the expected path `data.message.mediaUrl`

fix

Check the structure of your incoming data. Use a Function node to log the payload and adjust field mappings.

Warnings

gotcha The input data structure must match Evolution API's webhook format exactly. Custom API calls may require transformation before using this node. ↓

fix Ensure the incoming JSON contains a `data.message.mediaUrl` property. Use n8n's Set node or Function node to restructure data if needed.

gotcha The node may fail if the media URL is not accessible from the n8n server (e.g., due to network restrictions or authentication). ↓

fix Verify network connectivity and ensure the Evolution API server allows downloads from the n8n host. Consider using a proxy or VPN.

gotcha Large media files may cause memory issues or timeouts in n8n. The node does not stream to disk. ↓

fix Increase n8n's `N8N_PAYLOAD_SIZE_MAX` environment variable or pre-filter small files using a Function node.

Install

npm install n8n-nodes-evolution-api-media-downloader

yarn add n8n-nodes-evolution-api-media-downloader

pnpm add n8n-nodes-evolution-api-media-downloader

Imports

EvolutionApiMediaDownloader

wrong

const EvolutionApiMediaDownloader = require('n8n-nodes-evolution-api-media-downloader')

correct

import { EvolutionApiMediaDownloader } from 'n8n-nodes-evolution-api-media-downloader'

This package is ESM-only as per n8n node convention. CommonJS require() will fail at runtime.

nodeMetadata
```
import { nodeMetadata } from 'n8n-nodes-evolution-api-media-downloader'
```
Optional export for advanced node configuration. Not required for basic usage.

default

wrong

import { default as EvolutionApiMediaDownloader } from 'n8n-nodes-evolution-api-media-downloader'

correct

import EvolutionApiMediaDownloader from 'n8n-nodes-evolution-api-media-downloader'

Default import is also supported and is the recommended pattern for a single node.

Quickstart

Shows how to install and configure the node in an n8n workflow for downloading media from Evolution API

// Install the package in your n8n custom nodes directory
// npm install n8n-nodes-evolution-api-media-downloader

// Example usage: Create an n8n workflow that uses the node
// 1. Add a Webhook node (trigger) to receive Evolution API messages
// 2. Connect it to an Evolution API Media Downloader node
// 3. Configure the node to extract the media URL from the webhook payload

// The node expects input with JSON like:
// {
//   "data": {
//     "message": {
//       "mediaUrl": "https://evolution-api.example.com/media/123",
//       "fileName": "document.pdf",
//       "mimeType": "application/pdf"
//     }
//   }
// }

// Node output will contain the downloaded file as binary data
// Use n8n's Set node to map the binary data for further processing