universal-media-downloader

Universal media downloader node for n8n. Detects and downloads non-text media from WhatsApp, Telegram, Messenger, Instagram, and direct URLs.

Package Information

Released: 4 mo ago
Downloads: 10 weekly / 143 monthly
Latest Version: 0.1.0
Author: Universal Media Downloader

Available Nodes

Universal Media Downloader icon
Universal Media Downloader
Detect and download non-text media from WhatsApp, Telegram, Messenger, Instagram, or direct URLs

Documentation

n8n-nodes-universal-media-downloader

Universal Media Downloader is an n8n community node that detects and downloads non-text media from incoming workflow items.

It is designed for mixed trigger payloads from WhatsApp, Telegram, Messenger, Instagram, webhooks, and direct media URLs. Each input item is processed independently, and downloaded media is stored as n8n binary data.

Features

  • Auto-detects supported media references.
  • Supports multiple input items.
  • Downloads media into a configurable binary property.
  • Preserves original JSON and adds normalized metadata.
  • Handles text-only messages without creating binary data.
  • Optional provider credentials.
  • Provider-specific error handling controls.

Supported sources

Source Supported media reference
WhatsApp Cloud API media_id values, including nested image.id, video.id, audio.id, document.id, and sticker.id
Telegram Bot API file_id values, including photo, document, video, audio, voice, video_note, and sticker
Messenger Attachment payload URLs such as message.attachments[].payload.url
Instagram Attachment payload URLs such as message.attachments[].payload.url
Direct URL HTTP or HTTPS media URLs in fields such as url, mediaUrl, fileUrl, downloadUrl, and attachmentUrl

Node parameters

Source Type

  • Auto Detect: Checks WhatsApp, Telegram, Messenger, Instagram, then direct URL shapes.
  • WhatsApp: Looks only for WhatsApp media IDs.
  • Telegram: Looks only for Telegram file IDs.
  • Messenger: Looks only for Messenger attachment URLs.
  • Instagram: Looks only for Instagram attachment URLs.
  • Direct URL: Looks only for direct HTTP or HTTPS URLs.

Binary Property Name

The binary property that receives the downloaded file.

Default: data

Continue If No Media

When enabled, text-only items return with hasMedia: false and no binary data.

Default: true

When disabled, the node fails if no supported media reference is found.

Continue On Download Error

When enabled, items with media references that fail to download return with downloadError details instead of failing the execution.

Default: false

Credentials

Credentials are optional.

Meta Access Token

Required for WhatsApp media_id downloads. Also used as a Bearer token for Messenger or Instagram attachment URLs when those URLs require Meta authentication.

Meta Graph API Version

Used when resolving WhatsApp media metadata.

Default: v23.0

Telegram Bot Token

Required for Telegram file_id downloads.

Direct URLs do not require credentials.

Output

When media is downloaded, the node adds metadata to the JSON and writes the binary file to the configured binary property:

{
  "hasMedia": true,
  "mediaType": "image",
  "mimeType": "image/jpeg",
  "fileName": "image.jpg",
  "fileSize": 128912
}

When the item has no supported media and Continue If No Media is enabled:

{
  "hasMedia": false
}

When Continue On Download Error is enabled:

{
  "hasMedia": true,
  "mediaType": "image",
  "sourceType": "whatsapp",
  "downloadError": "Meta Access Token credential is required to download WhatsApp media_id values"
}

Example payloads

WhatsApp

{
  "messages": [
    {
      "type": "image",
      "image": {
        "id": "1234567890",
        "mime_type": "image/jpeg"
      }
    }
  ]
}

Telegram

{
  "message": {
    "document": {
      "file_id": "BQACAgQAAxkBAAIB...",
      "file_name": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  }
}

Messenger or Instagram

{
  "message": {
    "attachments": [
      {
        "type": "image",
        "payload": {
          "url": "https://example.com/image.jpg"
        }
      }
    ]
  }
}

Direct URL

{
  "mediaUrl": "https://example.com/video.mp4"
}

Installation

From a local checkout:

npm install
npm run build
npm link

Then link it into your n8n custom nodes directory:

mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y
npm link n8n-nodes-universal-media-downloader

Restart n8n and search for Universal Media Downloader in the nodes panel.

Development

npm install
npm run build
npm run typecheck
npm run lint

Package contents

  • credentials/UniversalMediaDownloaderApi.credentials.ts
  • nodes/UniversalMediaDownloader/UniversalMediaDownloader.node.ts
  • nodes/UniversalMediaDownloader/universalMediaDownloader.svg
  • package.json
  • tsconfig.json
  • gulpfile.js

Notes

  • The node intentionally skips text MIME types such as text/*, application/json, and application/xml.
  • WhatsApp media downloads use the official two-step flow: resolve media metadata from Meta Graph API, then download the returned URL with the same Bearer token.
  • Telegram media downloads use the official two-step flow: call getFile, then download from the returned file path.

Discussion