Send Video

Send a video message to a WhatsApp number or group. Supports video upload, URL-based videos, captions, compression, and view-once mode.

Videos can be sent either by uploading a file or providing a URL. The API supports automatic compression and ephemeral view-once videos.

Endpoint

POST /send/video

Headers

X-Device-Id

string

Device identifier for multi-device support. Required when multiple devices are registered.

Content-Type

string

required

Must be multipart/form-data for file uploads.

Request Body (multipart/form-data)

phone

string

required

Phone number with country code and WhatsApp suffix.Format: {country_code}{phone_number}@s.whatsapp.netExample: [email protected]

caption

string

Optional caption text for the video. Supports up to 3000 characters.Example: "ini contoh caption video"

video

file

Video file to upload. Supports common video formats (MP4, AVI, MOV, MKV, WebM).

Either video (file upload) or video_url must be provided, but not both.

video_url

string

URL of the video to send. The API will download and send the video from this URL.Example: "https://example.com/sample.mp4"

Either video (file upload) or video_url must be provided, but not both.

view_once

boolean

default:false

Enable view-once mode. The video can only be viewed once by the recipient and will disappear after being opened.

View-once videos cannot be forwarded, saved, or recorded without notification (on supported devices).

compress

boolean

default:false

Compress the video before sending to reduce file size. Highly recommended for large videos.

Compression may reduce video quality but significantly improves delivery speed and reduces bandwidth usage.

duration

integer

Disappearing message duration in seconds.Common values:

86400 - 24 hours
604800 - 7 days
7776000 - 90 days

is_forwarded

boolean

default:false

Mark the message as forwarded.

Response

code

string

Response status code. Returns "SUCCESS" on successful send.

message

string

Human-readable response message.

results

object

message_id

string

Unique identifier for the sent message.Example: "3EB0B430B6F8F1D0E053AC120E0A9E5C"

status

string

Detailed status message.

Code Examples

curl -X POST http://localhost:3000/send/video \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "caption=Check out this amazing video!" \
  -F "video=@/path/to/video.mp4"

Response Example

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "message_id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
    "status": "Video sent successfully"
  }
}

Features

Video Compression

Enable compression to reduce file size while maintaining acceptable quality:

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

Benefits of compression:

Reduces file size by 50-80%
Faster upload and delivery
Better for recipients with limited bandwidth
Reduces server storage costs

Compression settings:

Resolution: Scaled to max 1280x720 (HD)
Bitrate: Optimized for mobile viewing
Format: Converted to H.264/MP4 if needed

View Once Videos

Send ephemeral videos that can only be viewed once:

curl -X POST http://localhost:3000/send/video \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "video=@/path/to/sensitive-content.mp4" \
  -F "view_once=true"

View-once behavior:

Recipient can watch video only once
Video disappears after being played
Sender is notified when video is opened
Cannot be forwarded or saved
Screenshot attempts may be detected on supported devices

URL-Based Video Sending

Send videos directly from URLs:

curl -X POST http://localhost:3000/send/video \
  -H "X-Device-Id: my-device" \
  -F "[email protected]" \
  -F "video_url=https://cdn.example.com/products/demo.mp4" \
  -F "caption=Product Demo Video"

Use cases:

CDN-hosted videos
Cloud storage integration
Dynamic video generation
Third-party video platforms

Video Requirements

Supported Formats

MP4 (.mp4) - Recommended, best compatibility
AVI (.avi) - Common format
MOV (.mov) - Apple format
MKV (.mkv) - High quality container
WebM (.webm) - Web format
3GP (.3gp) - Mobile format

Recommended Codec

Video: H.264 (AVC)
Audio: AAC
Container: MP4

File Size Limits

WhatsApp enforces strict video size limits.

Maximum file size: 16MB (compressed)
Maximum file size: 64MB (uncompressed, before API processing)
Recommended: Under 10MB for reliable delivery
With compression: Can handle larger source files

Video Specifications

Resolution:

Minimum: 144p (256x144)
Maximum: 1080p (1920x1080)
Recommended: 720p (1280x720)

Duration:

Maximum: ~90 seconds for best delivery
Longer videos: Use compression or split into parts
No technical limit on duration

Aspect Ratio:

Recommended: 16:9 (landscape) or 9:16 (portrait)
Square videos: 1:1
All aspect ratios supported

Frame Rate:

Recommended: 24-30 FPS
Maximum: 60 FPS
Lower frame rates acceptable for certain content

Best Practices

Always Use Compression for Large Files
```
# For files > 5MB
-F "compress=true"
```
Optimize Before Upload
- Pre-encode videos in H.264/MP4
- Use 720p resolution for balance of quality/size
- Trim unnecessary content
- Adjust bitrate to 1-2 Mbps
Caption Guidelines
- Keep captions concise and relevant
- Use captions to provide context
- Support emoji in captions
Choose the Right Method
- Local files: Use file upload
- Cloud-hosted: Use video_url
- Automated systems: Use video_url with CDN
Handle Long Processing Times
- Large videos take time to process
- Implement timeout handling (>60 seconds)
- Consider background job processing
- Notify users of upload progress
View Once for Sensitive Content
- Private or confidential videos
- Time-sensitive content
- One-time instructions or codes

Video Processing

The API automatically processes videos:

Without Compression

Format validation
Codec compatibility check
Thumbnail generation
Metadata extraction

With Compression

Resolution scaling (max 720p)
Bitrate optimization
Codec conversion to H.264
Audio normalization
File size reduction

Video processing is CPU-intensive. Processing time increases with video duration and resolution. Large videos may take 30-60+ seconds to process.

Use Cases

Marketing & Promotions

curl -X POST http://localhost:3000/send/video \
  -F "[email protected]" \
  -F "video_url=https://cdn.brand.com/promo-july.mp4" \
  -F "caption=🎉 Summer Sale! 50% OFF - Limited Time" \
  -F "compress=true"

Product Demonstrations

curl -X POST http://localhost:3000/send/video \
  -F "[email protected]" \
  -F "video=@products/demo-product-x.mp4" \
  -F "caption=Product X Demo - See it in action!"

Tutorial Content

curl -X POST http://localhost:3000/send/video \
  -F "[email protected]" \
  -F "video=@tutorials/setup-guide.mp4" \
  -F "caption=Setup Tutorial - Follow these steps" \
  -F "compress=true"

Personal Video Messages

curl -X POST http://localhost:3000/send/video \
  -F "[email protected]" \
  -F "video=@recordings/birthday-message.mp4" \
  -F "caption=Happy Birthday! 🎂"

Error Responses

400

Bad Request

Common causes:

Invalid phone number format
Missing both video and video_url
Providing both video and video_url
Unsupported video format
File too large (>64MB before compression)
Invalid video codec

500

Internal Server Error

Common causes:

Device not connected
Failed to download video from URL
Video processing/compression error
FFmpeg not installed or configured
Insufficient disk space
Network timeout during upload

Troubleshooting

Video Upload Fails

Check file size (must be under 64MB)
Verify video format is supported
Try enabling compression
Check device connection status
Verify FFmpeg is installed on server

Long Processing Time

Enable compression to speed up processing
Reduce video resolution before upload
Use shorter videos (under 60 seconds)
Check server CPU/memory resources

Quality Issues

Disable compression for high-quality needs
Pre-encode video in H.264 at desired quality
Use higher bitrate in source video
Avoid re-compressing already compressed videos

Send Image - Send image messages
Send Audio - Send audio messages
Send File - Send document files
Download Media - Download media from messages

Overview

Device Management

Connection

User

Messaging

Message Operations

Chats

Groups

Newsletters

Endpoint

Headers

Request Body (multipart/form-data)

Response

Code Examples

Response Example

Features

Video Compression

View Once Videos

URL-Based Video Sending

Video Requirements

Supported Formats

Recommended Codec

File Size Limits

Video Specifications

Best Practices

Video Processing

Without Compression

With Compression

Use Cases

Marketing & Promotions

Product Demonstrations

Tutorial Content

Personal Video Messages

Error Responses

Troubleshooting

Video Upload Fails

Long Processing Time

Quality Issues

Build docs developers (and LLMs) love

Overview

Device Management

Connection

User

Messaging

Message Operations

Chats

Groups

Newsletters

​Endpoint

​Headers

​Request Body (multipart/form-data)

​Response

​Code Examples

​Response Example

​Features

​Video Compression

​View Once Videos

​URL-Based Video Sending

​Video Requirements

​Supported Formats

​Recommended Codec

​File Size Limits

​Video Specifications

​Best Practices

​Video Processing

​Without Compression

​With Compression

​Use Cases

​Marketing & Promotions

​Product Demonstrations

​Tutorial Content

​Personal Video Messages

​Error Responses

​Troubleshooting

​Video Upload Fails

​Long Processing Time

​Quality Issues

​Related Endpoints

Build docs developers (and LLMs) love

Endpoint

Headers

Request Body (multipart/form-data)

Response

Code Examples

Response Example

Features

Video Compression

View Once Videos

URL-Based Video Sending

Video Requirements

Supported Formats

Recommended Codec

File Size Limits

Video Specifications

Best Practices

Video Processing

Without Compression

With Compression

Use Cases

Marketing & Promotions

Product Demonstrations

Tutorial Content

Personal Video Messages

Error Responses

Troubleshooting

Video Upload Fails

Long Processing Time

Quality Issues

Related Endpoints