Skip to main content

Get Media URL

Retrieves the download URL for a WhatsApp media file via the WhatsApp Business Cloud API. Use this to download media files received in messages.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Media ID - The Media ID from a received message webhook (obtained from Receive Events node).

Options​

  • API Version - Meta Graph API version. Default is 21.0.
  • Access Token - WhatsApp Cloud API Access Token credential (required).

Outputs​

  • Download URL - The temporary download URL for the media file (valid for 5 minutes).
  • MIME Type - The MIME type of the media file (e.g., image/jpeg, video/mp4).
  • File Size - The file size in bytes.
  • Full Response - The complete API response object with all media information.

How It Works​

The Get Media URL node retrieves download information for media files. When executed, the node:

  1. Validates the Media ID input
  2. Retrieves the access token from the credential
  3. Calls the WhatsApp API to get media information
  4. Extracts the download URL, MIME type, and file size
  5. Returns all media information in outputs

Requirements​

  • A WhatsApp Business Account in Meta Developer Portal
  • Access Token with appropriate permissions
  • Valid Media ID from a received message
  • Media must be available (not expired or deleted)

Error Handling​

The node will return specific errors in the following cases:

  • Empty or invalid Media ID
  • Media ID not found or expired
  • Invalid access token
  • Media no longer available
  • Network connectivity issues

Getting Media IDs​

Media IDs are obtained from the Receive Events node when media messages are received:

From Receive Events Output:

{
  "messageType": "image",
  "mediaId": "1234567890123456",
  "from": "14155551234",
  ...
}

Download URL Expiration​

Important: Download URLs are temporary and expire after 5 minutes. You must:

  1. Get the media URL
  2. Download the file immediately
  3. Store the file if needed for later use

Example: Download Received Image​

Flow:

  1. Receive Events captures image message with Media ID
  2. Get Media URL node retrieves download URL
  3. Download file using HTTP request
  4. Process or store the image

Inputs:

  • Media ID: 1234567890123456 (from Receive Events)

Outputs:

  • Download URL: https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=xxx&ext=xxx
  • MIME Type: image/jpeg
  • File Size: 245678 (bytes)

Example: Complete Media Handling Flow​

// 1. Get media from webhook
const mediaId = event.mediaId;
const messageType = event.messageType;

// 2. Get download URL
const mediaInfo = await getMediaURL({
  mediaId: mediaId
});

// 3. Download the file
const response = await fetch(mediaInfo.downloadUrl, {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const fileBuffer = await response.buffer();

// 4. Save to file system
const filename = `${mediaId}.${getExtension(mediaInfo.mimeType)}`;
await fs.writeFile(filename, fileBuffer);

// 5. Process the file
if (messageType === 'image') {
  await processImage(filename);
} else if (messageType === 'document') {
  await processDocument(filename);
}

Example: Save Media to Cloud Storage​

// Get media URL
const mediaInfo = await getMediaURL({mediaId});

// Download file
const response = await fetch(mediaInfo.downloadUrl, {
  headers: {'Authorization': `Bearer ${accessToken}`}
});

// Upload to AWS S3
await s3.upload({
  Bucket: 'my-whatsapp-media',
  Key: `media/${mediaId}`,
  Body: response.body,
  ContentType: mediaInfo.mimeType
});

Supported Media Types​

The node works with all media types received via WhatsApp:

  • Images: JPEG, PNG
  • Videos: MP4, 3GPP
  • Audio: AAC, AMR, MP3, OGG
  • Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT
  • Stickers: WebP

Usage Notes​

  • Download URLs expire after 5 minutes
  • You must include the access token in download request headers
  • Downloaded files should be processed or stored immediately
  • Media IDs are unique per file
  • Original filename is not included (use MIME type to determine extension)
  • File size is in bytes
  • MIME type helps determine how to process the file

Tips for RPA Developers​

  • Download media immediately after getting URL
  • Store media in permanent storage (S3, Azure Blob, etc.)
  • Use MIME type to determine file extension
  • Implement error handling for expired URLs
  • Log media downloads for audit purposes
  • Clean up temporary files after processing
  • Validate file size before downloading
  • Use streaming for large files
  • Implement virus scanning for received files
  • Track storage costs for media files

MIME Type to Extension Mapping​

const mimeTypeToExtension = {
  'image/jpeg': 'jpg',
  'image/png': 'png',
  'video/mp4': 'mp4',
  'video/3gpp': '3gp',
  'audio/aac': 'aac',
  'audio/amr': 'amr',
  'audio/mpeg': 'mp3',
  'audio/ogg': 'ogg',
  'application/pdf': 'pdf',
  'application/msword': 'doc',
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
  'application/vnd.ms-excel': 'xls',
  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
  'application/vnd.ms-powerpoint': 'ppt',
  'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
  'text/plain': 'txt'
};

Downloading Media Files​

To download the media file, make an authenticated HTTP request:

// Using fetch
const response = await fetch(downloadUrl, {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const buffer = await response.buffer();
// Using axios
const response = await axios.get(downloadUrl, {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  },
  responseType: 'arraybuffer'
});

const buffer = Buffer.from(response.data);

Common Use Cases​

Image Processing:

// Get and process received images
const mediaInfo = await getMediaURL({mediaId});
const image = await downloadImage(mediaInfo.downloadUrl);
const processed = await resizeImage(image, 800, 600);
await saveImage(processed, `processed-${mediaId}.jpg`);

Document Archiving:

// Archive received documents
const mediaInfo = await getMediaURL({mediaId});
const document = await downloadFile(mediaInfo.downloadUrl);
await archiveSystem.store({
  file: document,
  metadata: {
    from: sender,
    receivedAt: timestamp,
    mimeType: mediaInfo.mimeType,
    size: mediaInfo.fileSize
  }
});

Media Backup:

// Backup all received media
if (event.mediaId) {
  const mediaInfo = await getMediaURL({mediaId: event.mediaId});
  const file = await downloadFile(mediaInfo.downloadUrl);
  await cloudStorage.upload({
    path: `backups/${event.from}/${mediaId}`,
    file: file,
    metadata: {
      mimeType: mediaInfo.mimeType,
      originalSize: mediaInfo.fileSize
    }
  });
}

Common Errors and Solutions​

Error: Invalid Media ID

  • Verify Media ID is correct
  • Media may have expired (typically after 30 days)
  • Check if Media ID was properly received from webhook

Error: URL expired

  • Download URLs are only valid for 5 minutes
  • Get a fresh URL by calling this node again
  • Download immediately after getting URL

Error: Download failed (401)

  • Include access token in download request headers
  • Verify access token is valid
  • Format: Authorization: Bearer YOUR_ACCESS_TOKEN

Error: Media not found

  • Media may have been deleted
  • Media ID may be incorrect
  • Media may have expired

Best Practices​

  • Download media immediately after getting URL
  • Store media in permanent storage
  • Clean up temporary files
  • Implement retry logic for failed downloads
  • Validate file size before downloading
  • Use streaming for large files
  • Scan files for viruses/malware
  • Respect storage limits and costs
  • Log all media operations
  • Implement access controls for stored media
  • Compress large files if appropriate
  • Follow data retention policies

Security Considerations​

  • Validate MIME types before processing
  • Scan downloaded files for malware
  • Implement file size limits
  • Use secure storage with encryption
  • Control access to stored media
  • Log all downloads for audit
  • Don't expose media URLs publicly
  • Implement proper authentication
  • Follow data protection regulations
  • Delete media after retention period

Performance Optimization​

  • Use CDN for frequently accessed media
  • Cache media URLs (but remember 5-minute expiration)
  • Implement parallel downloads for multiple files
  • Use streaming for large files
  • Compress media when possible
  • Monitor storage costs
  • Implement cleanup routines for old media