Skip to main content

Overview

GOWA WhatsApp API supports sending and receiving various media types with automatic format conversion, compression, and optimization. All media operations require FFmpeg for video/audio processing and libwebp for sticker conversion.

Requirements

FFmpeg

Required for video compression and audio processing.Install:
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt install ffmpeg
  • Windows: Download FFmpeg

libwebp

Required for sticker conversion (WebP format).Install:
  • macOS: brew install webp
  • Ubuntu: sudo apt install webp
  • Windows: Download libwebp

Images

Send Image

Send images from file upload or URL:
curl -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "caption=Check this out!" \
  -F "image=@/path/to/photo.jpg" \
  -F "compress=true"

Image Parameters

phone
string
required
Recipient phone number in international format.
image
file
Image file (JPG, JPEG, PNG). Mutually exclusive with image_url.
image_url
string
Image URL to download and send. Mutually exclusive with image.
caption
string
Image caption text.
compress
boolean
default:"false"
Compress image before sending (reduces file size).
view_once
boolean
default:"false"
Send as view-once image (disappears after viewing).
duration
integer
Disappearing message duration in seconds (0, 86400, 604800, 7776000).

Image Compression

When compress=true, the API uses FFmpeg to optimize images:
ffmpeg -i input.jpg -q:v 3 -preset ultrafast output.jpg
Compression typically reduces image size by 40-70% while maintaining visual quality.

Supported Formats

FormatExtensionMIME TypeCompression
JPEG.jpg, .jpegimage/jpeg
PNG.pngimage/png
WebP.webpimage/webp

Videos

Send Video

curl -X POST http://localhost:3000/send/video \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "caption=Watch this" \
  -F "video=@/path/to/video.mp4" \
  -F "compress=true"

Video Parameters

video
file
Video file (MP4, MKV, AVI). Max size: 30MB (default).
video_url
string
Video URL to download and send.
compress
boolean
default:"false"
Compress video using FFmpeg before sending.
view_once
boolean
default:"false"
Send as view-once video.

Video Compression

FFmpeg compression command used:
ffmpeg -i input.mp4 -c:v libx264 -preset ultrafast -crf 28 \
  -c:a aac -b:a 128k output.mp4
Video compression is CPU-intensive. Consider disabling for large files or use a dedicated media processing server.

Supported Video Formats

FormatExtensionMIME Type
MP4.mp4video/mp4
Matroska.mkvvideo/x-matroska
AVI.avivideo/avi, video/x-msvideo

Audio

Send Audio

curl -X POST http://localhost:3000/send/audio \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "audio=@/path/to/audio.mp3"

Supported Audio Formats

  • AAC (.aac, audio/aac)
  • AMR (.amr, audio/amr)
  • FLAC (.flac, audio/flac)
  • M4A (.m4a, audio/m4a)
  • M4R (.m4r, audio/m4r)
  • MP3 (.mp3, audio/mp3, audio/mpeg)
  • OGG (.ogg, audio/ogg)
  • WAV (.wav, audio/wav, audio/wave, audio/x-wav)
  • WMA (.wma, audio/wma, audio/x-ms-wma)

Voice Messages (PTT)

PTT (Push-to-Talk) voice messages are not yet implemented in the current API version. Regular audio files are sent as audio attachments.

Stickers

Send Sticker

Stickers are automatically converted to WebP format with 512x512 pixel dimensions:
curl -X POST http://localhost:3000/send/sticker \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "sticker=@/path/to/image.png"

Sticker Conversion

1

Format Detection

API accepts JPG, JPEG, PNG, WebP, and GIF formats.
2

Automatic Resize

Static images are resized to 512x512 pixels using imaging library.
3

WebP Conversion

Images are converted to WebP format for WhatsApp compatibility.
4

Transparency Preservation

PNG transparency is preserved in the WebP output.

Animated Stickers

Animated WebP stickers are supported but must meet WhatsApp requirements:
Animated Sticker Requirements:
  • Dimensions: Exactly 512x512 pixels
  • File size: Under 500KB
  • Duration: Maximum 10 seconds
If your animated sticker doesn’t meet these requirements, resize it before uploading using tools like ezgif.com.

Sticker Validation

The API automatically validates animated stickers:
// Pseudo-code validation
if isAnimatedWebP {
  if width != 512 || height != 512 {
    return error("animated stickers must be 512x512")
  }
  if fileSize > 500KB {
    return error("animated stickers must be under 500KB")
  }
}

Supported Input Formats

FormatStaticAnimatedAuto-Resize
JPG/JPEG
PNG
WebP✅*
GIF✅*
*Animated formats must meet size/dimension requirements.

Documents/Files

Send File

Send any document type:
curl -X POST http://localhost:3000/send/file \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "caption=Monthly report" \
  -F "file=@/path/to/document.pdf"

File Size Limits

WhatsappSettingMaxFileSize
integer
default:"10485760"
Maximum file upload size: 10MB (10,485,760 bytes).
For files larger than 10MB, upload to cloud storage and send the link as a text message.

All File Types Supported

WhatsApp accepts any file type including:
  • Documents (PDF, DOCX, XLSX, PPTX)
  • Archives (ZIP, RAR, 7Z)
  • Code files (JS, PY, GO)
  • Data files (JSON, CSV, XML)

Receiving Media

Auto-Download Media

Control automatic media downloads:
export WHATSAPP_AUTO_DOWNLOAD_MEDIA=true  # Default
Media files are automatically downloaded to statics/media/:
{
  "event": "message",
  "payload": {
    "id": "3EB0C127D7BACC83D6A3",
    "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
  }
}

Manual Media Download

Download media from a specific message:
curl -X GET "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download" \
  -H "X-Device-Id: [email protected]" \
  -o downloaded_media.jpg

Media Storage Management

Disk Space: Downloaded media files accumulate in statics/media/. Implement cleanup jobs to manage disk space.

Cleanup Strategy

# Delete media files older than 7 days
find statics/media -type f -mtime +7 -delete
Or use a cron job:
# Clean up media daily at 2 AM
0 2 * * * find /app/statics/media -type f -mtime +7 -delete

Configuration Reference

VariableDefaultDescription
WHATSAPP_AUTO_DOWNLOAD_MEDIAtrueAuto-download incoming media
WhatsappSettingMaxImageSize5MBMax image download size
WhatsappSettingMaxVideoSize30MBMax video upload size
WhatsappSettingMaxFileSize10MBMax file upload size
WhatsappSettingMaxDownloadSize100MBMax media download size

Error Handling

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "max file upload is 10 MB, please upload in cloud and send via text"
}
Solution: Upload large files to cloud storage (S3, Google Drive) and send the link.
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "animated WebP stickers must be exactly 512x512 pixels (got 480x480)"
}
Solution: Resize animated stickers to 512x512 before uploading using ezgif.com.
{
  "status": 500,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "ffmpeg not found in system PATH"
}
Solution: Install FFmpeg and ensure it’s in system PATH.

Best Practices

Compress Large Media

Always enable compression for images/videos over 2MB to reduce bandwidth.

Validate Before Upload

Pre-validate file sizes and formats client-side before API calls.

Use Cloud Storage

For files >10MB, upload to S3/GCS and send links instead.

Clean Up Media

Implement automated cleanup of downloaded media files.

Complete Example

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function sendMediaMessage(type, filePath, recipient) {
  const form = new FormData();
  form.append('phone', recipient);
  form.append('caption', 'Sent via API');
  form.append(type, fs.createReadStream(filePath));
  
  if (type === 'image' || type === 'video') {
    form.append('compress', 'true');
  }

  const response = await axios.post(
    `http://localhost:3000/send/${type}`,
    form,
    {
      headers: {
        ...form.getHeaders(),
        'X-Device-Id': '[email protected]'
      }
    }
  );
  
  return response.data;
}

// Usage
await sendMediaMessage('image', 'photo.jpg', '[email protected]');
await sendMediaMessage('video', 'clip.mp4', '[email protected]');
await sendMediaMessage('sticker', 'sticker.png', '[email protected]');

See Also

Build docs developers (and LLMs) love