Upload Media

Uploads a local media file to WhatsApp servers and returns a Media ID that can be used to send media messages via the WhatsApp Business Cloud API.

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) - 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

• Phone Number ID - WhatsApp Business Phone Number ID from Meta Developer Portal.
• File Path - Local file path to the media file to upload (absolute path).
• MIME Type - MIME type of the file (e.g., image/jpeg, video/mp4, application/pdf).

Options

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

Outputs

• Media ID - The uploaded media ID that can be used with Send Image/Video/Audio/Document nodes.
• Full Response - The complete API response object from WhatsApp.

How It Works

The Upload Media node uploads files to WhatsApp's servers. When executed, the node:

1. Validates all required inputs
2. Opens and reads the file from the specified path
3. Creates a multipart form upload request
4. Includes the file, MIME type, and messaging product
5. Uploads to WhatsApp API
6. Returns the Media ID for use in sending messages

Requirements

• A WhatsApp Business Account in Meta Developer Portal
• Access Token with appropriate permissions
• Valid local file path
• File must be in supported format and within size limits
• Sufficient permissions to read the file

Supported Media Types and Size Limits

Images:

• JPEG, PNG
• Maximum: 5 MB

Videos:

• MP4, 3GPP
• Maximum: 16 MB

Audio:

• AAC, AMR, MP3, OGG
• Maximum: 16 MB

Documents:

• PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT
• Maximum: 100 MB

Error Handling

The node will return specific errors in the following cases:

• Empty or invalid Phone Number ID
• Empty or invalid File Path
• Empty or invalid MIME Type
• File not found at specified path
• File exceeds size limit
• Unsupported file format
• Invalid access token
• Network connectivity issues
• Insufficient file permissions

Example: Upload and Send Image

Flow:

1. Upload Media node uploads local image
2. Get Media ID from output
3. Send Image Message node uses Media ID

Upload Media Inputs:

• Phone Number ID: 123456789012345
• File Path: /path/to/product-image.jpg
• MIME Type: image/jpeg

Output:

• Media ID: 1234567890123456

Send Image Message:

• Image URL: 1234567890123456 (the Media ID)
• Use Media ID: true

Example: Upload Document

Inputs:

• Phone Number ID: 123456789012345
• File Path: /home/user/reports/monthly-report.pdf
• MIME Type: application/pdf

Output:

• Media ID: 9876543210987654

Then use this Media ID with Send Document Message node.

Example: Batch Upload

Use Case: Upload multiple files and send them

const files = [
  {path: '/images/product1.jpg', mimeType: 'image/jpeg'},
  {path: '/images/product2.jpg', mimeType: 'image/jpeg'},
  {path: '/docs/catalog.pdf', mimeType: 'application/pdf'}
];

const mediaIds = [];

for (const file of files) {
  const result = await uploadMedia({
    phoneNumberId: '123456789012345',
    filePath: file.path,
    mimeType: file.mimeType
  });
  mediaIds.push(result.mediaId);
}

// Send all uploaded media
for (const mediaId of mediaIds) {
  await sendMediaMessage({
    mediaId: mediaId,
    toPhoneNumber: customer.phone
  });
}

Media ID Lifecycle

• Upload: Media is uploaded and Media ID is returned
• Validity: Media IDs are valid for 30 days
• Usage: Can be used multiple times to send to different recipients
• Expiration: After 30 days, media must be re-uploaded
• Storage: WhatsApp stores the media for 30 days

Usage Notes

• Use absolute file paths, not relative paths
• Verify file exists before uploading
• MIME type must match the actual file type
• Media IDs can be reused for 30 days
• Same file can be uploaded multiple times (creates new Media ID each time)
• Files are automatically validated by WhatsApp
• Upload is synchronous (waits for completion)

Tips for RPA Developers

• Cache Media IDs to avoid re-uploading within 30 days
• Validate file size before uploading
• Store Media IDs in database with expiration tracking
• Implement retry logic for failed uploads
• Use Upload Media for local files, URLs for remote files
• Monitor upload success rate
• Log uploads for audit purposes
• Clean up local files after upload if no longer needed
• Implement parallel uploads for multiple files
• Track upload costs (bandwidth usage)

Common MIME Types

const mimeTypes = {
  // Images
  'jpg': 'image/jpeg',
  'jpeg': 'image/jpeg',
  'png': 'image/png',

  // Videos
  'mp4': 'video/mp4',
  '3gp': 'video/3gpp',

  // Audio
  'aac': 'audio/aac',
  'm4a': 'audio/aac',
  'amr': 'audio/amr',
  'mp3': 'audio/mpeg',
  'ogg': 'audio/ogg',

  // Documents
  'pdf': 'application/pdf',
  'doc': 'application/msword',
  'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  'xls': 'application/vnd.ms-excel',
  'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  'ppt': 'application/vnd.ms-powerpoint',
  'pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
  'txt': 'text/plain'
};

File Path Examples

Linux/Mac:

/home/user/documents/report.pdf
/var/data/images/product.jpg
/tmp/audio/message.mp3

Windows:

C:/Users/username/Documents/report.pdf
D:/Data/Images/product.jpg
C:/Temp/audio/message.mp3

Important: Use forward slashes (/) or escaped backslashes (\\) in paths.

Common Use Cases

Product Catalog:

// Upload product images
const productImages = await Promise.all(
  products.map(async (product) => {
    const result = await uploadMedia({
      phoneNumberId: phoneNumberId,
      filePath: product.imagePath,
      mimeType: 'image/jpeg'
    });
    return {
      productId: product.id,
      mediaId: result.mediaId
    };
  })
);

// Store Media IDs
await db.saveMediaIds(productImages);

Invoice Generation and Sending:

// Generate PDF invoice
const pdfPath = await generateInvoice(orderId);

// Upload invoice
const result = await uploadMedia({
  phoneNumberId: phoneNumberId,
  filePath: pdfPath,
  mimeType: 'application/pdf'
});

// Send to customer
await sendDocument({
  toPhoneNumber: customer.phone,
  mediaId: result.mediaId,
  filename: `Invoice-${orderId}.pdf`,
  caption: `Your invoice for order #${orderId}`
});

Media Library Management:

// Upload media and store in database
const result = await uploadMedia({
  phoneNumberId: phoneNumberId,
  filePath: filePath,
  mimeType: mimeType
});

await db.mediaLibrary.insert({
  mediaId: result.mediaId,
  filePath: filePath,
  mimeType: mimeType,
  uploadedAt: new Date(),
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 days
});

Validation Before Upload

const fs = require('fs');
const path = require('path');

function validateMedia(filePath, maxSize) {
  // Check if file exists
  if (!fs.existsSync(filePath)) {
    throw new Error('File not found');
  }

  // Check file size
  const stats = fs.statSync(filePath);
  if (stats.size > maxSize) {
    throw new Error(`File too large: ${stats.size} bytes (max: ${maxSize})`);
  }

  // Get MIME type from extension
  const ext = path.extname(filePath).toLowerCase().substring(1);
  const mimeType = mimeTypes[ext];

  if (!mimeType) {
    throw new Error(`Unsupported file type: ${ext}`);
  }

  return {
    filePath: filePath,
    mimeType: mimeType,
    size: stats.size
  };
}

// Usage
const media = validateMedia('/path/to/file.jpg', 5 * 1024 * 1024); // 5 MB
await uploadMedia({
  phoneNumberId: phoneNumberId,
  filePath: media.filePath,
  mimeType: media.mimeType
});

Common Errors and Solutions

Error: File not found

• Verify file path is correct
• Use absolute paths
• Check file permissions
• Ensure file exists at specified location

Error: File too large

• Check file size against limits:
  • Images: 5 MB
  • Videos: 16 MB
  • Audio: 16 MB
  • Documents: 100 MB
• Compress file before uploading

Error: Unsupported file type

• Verify MIME type is correct
• Check file format is supported
• Don't use wrong MIME type for file

Error: Invalid file path

• Use absolute paths
• Check path separators (/ vs \)
• Verify path encoding
• Ensure no special characters

Best Practices

• Validate file before uploading
• Use absolute file paths
• Specify correct MIME type
• Cache Media IDs to avoid re-uploads
• Track Media ID expiration (30 days)
• Clean up temporary files after upload
• Implement error handling and retry logic
• Monitor upload bandwidth usage
• Log all uploads for audit
• Store Media IDs in database
• Test with various file types and sizes
• Implement file size limits
• Use parallel uploads for better performance
• Consider upload costs in high-volume scenarios

Performance Optimization

• Upload files in parallel when possible
• Cache Media IDs for reuse
• Pre-upload frequently used media
• Use CDN for frequently accessed files
• Compress files before upload when appropriate
• Monitor and optimize upload times
• Implement upload queue for high volumes

Security Considerations

• Validate file types before upload
• Scan files for malware
• Implement file size limits
• Control access to uploaded media
• Use secure file storage
• Log all upload operations
• Follow data protection regulations
• Don't upload sensitive data without encryption
• Implement proper access controls