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:- File Upload
- Image URL
Image Parameters
Recipient phone number in international format.
Image file (JPG, JPEG, PNG). Mutually exclusive with
image_url.Image URL to download and send. Mutually exclusive with
image.Image caption text.
Compress image before sending (reduces file size).
Send as view-once image (disappears after viewing).
Disappearing message duration in seconds (0, 86400, 604800, 7776000).
Image Compression
Whencompress=true, the API uses FFmpeg to optimize images:
Compression typically reduces image size by 40-70% while maintaining visual quality.
Supported Formats
| Format | Extension | MIME Type | Compression |
|---|---|---|---|
| JPEG | .jpg, .jpeg | image/jpeg | ✅ |
| PNG | .png | image/png | ✅ |
| WebP | .webp | image/webp | ❌ |
Videos
Send Video
Video Parameters
Video file (MP4, MKV, AVI). Max size: 30MB (default).
Video URL to download and send.
Compress video using FFmpeg before sending.
Send as view-once video.
Video Compression
FFmpeg compression command used:Supported Video Formats
| Format | Extension | MIME Type |
|---|---|---|
| MP4 | .mp4 | video/mp4 |
| Matroska | .mkv | video/x-matroska |
| AVI | .avi | video/avi, video/x-msvideo |
Audio
Send Audio
Supported Audio Formats
View All Supported Formats
View All Supported 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:Sticker Conversion
Animated Stickers
Animated WebP stickers are supported but must meet WhatsApp requirements:Sticker Validation
The API automatically validates animated stickers:Supported Input Formats
| Format | Static | Animated | Auto-Resize |
|---|---|---|---|
| JPG/JPEG | ✅ | ❌ | ✅ |
| PNG | ✅ | ❌ | ✅ |
| WebP | ✅ | ✅* | ❌ |
| GIF | ✅ | ✅* | ✅ |
Documents/Files
Send File
Send any document type:File Size Limits
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:- Enabled (Default)
- Disabled
Media files are automatically downloaded to
statics/media/:Manual Media Download
Download media from a specific message:Media Storage Management
Cleanup Strategy
Configuration Reference
| Variable | Default | Description |
|---|---|---|
WHATSAPP_AUTO_DOWNLOAD_MEDIA | true | Auto-download incoming media |
WhatsappSettingMaxImageSize | 5MB | Max image download size |
WhatsappSettingMaxVideoSize | 30MB | Max video upload size |
WhatsappSettingMaxFileSize | 10MB | Max file upload size |
WhatsappSettingMaxDownloadSize | 100MB | Max media download size |
Error Handling
File Too Large
File Too Large
Invalid Sticker Dimensions
Invalid Sticker Dimensions
FFmpeg Not Found
FFmpeg Not Found
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
See Also
- Sending Messages — Send text messages with mentions and replies
- Receiving Messages — Handle incoming media via webhooks
- Configuration — Environment variables and settings
