📱 WhatsApp API - Complete Documentation

🚀 Overview

WhatsApp API adalah REST API lengkap untuk mengirim berbagai jenis pesan WhatsApp termasuk text, gambar, dokumen, audio, video, dan sticker. API ini dibangun menggunakan Flask dan library Neonize untuk integrasi dengan WhatsApp Web.

⚡ Quick Info

• Base URL: http://your-server:5000
• Version: 2.0.0
• Protocol: HTTP/HTTPS
• Format: JSON
• Authentication: None (dapat ditambahkan)

---

📋 Table of Contents

1. API Endpoints
2. Request/Response Format
3. Supported Media Types
4. Error Handling
5. Examples
6. Rate Limits
7. Troubleshooting

---

🔗 API Endpoints

1. Health Check

Get API status and supported features.

GET /

Response:

{
  "service": "WhatsApp API - Complete Media Support",
  "status": "running",
  "bot_connected": true,
  "version": "2.0.0",
  "features": {
    "text_messages": "✅ Working",
    "image_messages": "✅ Working", 
    "document_messages": "✅ Working",
    "audio_messages": "✅ Available",
    "video_messages": "✅ Available",
    "sticker_messages": "✅ Available"
  },
  "supported_formats": {
    "images": ["jpg", "jpeg", "png", "gif", "webp"],
    "documents": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "zip", "rar", "7z"],
    "audio": ["mp3", "wav", "ogg", "m4a", "aac", "flac"],
    "video": ["mp4", "avi", "mov", "mkv", "webm", "3gp", "flv"],
    "stickers": ["webp"]
  },
  "file_size_limits": {
    "images": "16MB",
    "documents": "32MB",
    "audio": "16MB",
    "video": "64MB",
    "stickers": "1MB"
  },
  "endpoints": [
    "POST /api/send-message - Send text message",
    "POST /api/send-image - Send image with caption",
    "POST /api/send-document - Send document with caption",
    "POST /api/send-audio - Send audio file",
    "POST /api/send-video - Send video with caption",
    "POST /api/send-sticker - Send WebP sticker",
    "GET /api/status - Bot status"
  ]
}

2. Bot Status

Check WhatsApp bot connection status.

GET /api/status

Response:

{
  "bot_connected": true,
  "thread_alive": true,
  "upload_folder": "uploads",
  "supported_formats": {
    "images": ["jpg", "jpeg", "png", "gif", "webp"],
    "documents": ["pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "txt", "zip", "rar", "7z"],
    "audio": ["mp3", "wav", "ogg", "m4a", "aac", "flac"],
    "video": ["mp4", "avi", "mov", "mkv", "webm", "3gp", "flv"],
    "stickers": ["webp"]
  },
  "file_size_limits": {
    "images": "16MB",
    "documents": "32MB",
    "audio": "16MB",
    "video": "64MB",
    "stickers": "1MB"
  },
  "message": "Bot status retrieved"
}

3. Send Text Message

Send a text message to WhatsApp number.

POST /api/send-message

Headers:

Content-Type: application/json

Request Body:

{
  "phone": "6281234567890",
  "message": "Hello from WhatsApp API!"
}

Success Response (200):

{
  "status": "success",
  "message": "Text message sent successfully",
  "data": {
    "phone": "6281234567890",
    "message": "Hello from WhatsApp API!",
    "type": "text",
    "timestamp": "2025-08-15 17:38:34.475734"
  }
}

4. Send Image

Send an image with optional caption.

POST /api/send-image

Content-Type: multipart/form-data

Form Parameters:

• phone (required): WhatsApp number
• file (required): Image file
• caption (optional): Image caption

Example:

curl -X POST http://localhost:5000/api/send-image \
  -F "phone=6281234567890" \
  -F "caption=📸 Beautiful sunset!" \
  -F "file=@image.jpg"

Success Response (200):

{
  "status": "success",
  "message": "Image sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "sunset.jpg",
    "caption": "📸 Beautiful sunset!",
    "type": "image",
    "file_size_kb": 245.67,
    "timestamp": "2025-08-15 17:38:34.475734"
  }
}

5. Send Document

Send a document with optional caption.

POST /api/send-document

Content-Type: multipart/form-data

Form Parameters:

• phone (required): WhatsApp number
• file (required): Document file
• caption (optional): Document caption

Example:

curl -X POST http://localhost:5000/api/send-document \
  -F "phone=6281234567890" \
  -F "caption=📄 Important document" \
  -F "file=@report.pdf"

Success Response (200):

{
  "status": "success",
  "message": "Document sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "report.pdf",
    "caption": "📄 Important document",
    "type": "document",
    "file_size_kb": 1024.00,
    "timestamp": "2025-08-15 17:38:34.475734"
  }
}

6. Send Audio

Send an audio file.

POST /api/send-audio

Content-Type: multipart/form-data

Form Parameters:

• phone (required): WhatsApp number
• file (required): Audio file

Example:

curl -X POST http://localhost:5000/api/send-audio \
  -F "phone=6281234567890" \
  -F "file=@voice_message.mp3"

Success Response (200):

{
  "status": "success",
  "message": "Audio sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "voice_message.mp3",
    "type": "audio",
    "file_size_kb": 2869.42,
    "timestamp": "2025-08-15 17:38:54.824421"
  }
}

7. Send Video

Send a video with optional caption.

POST /api/send-video

Content-Type: multipart/form-data

Form Parameters:

• phone (required): WhatsApp number
• file (required): Video file
• caption (optional): Video caption

Example:

curl -X POST http://localhost:5000/api/send-video \
  -F "phone=6281234567890" \
  -F "caption=🎬 Amazing video!" \
  -F "file=@demo.mp4"

Success Response (200):

{
  "status": "success",
  "message": "Video sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "demo.mp4",
    "caption": "🎬 Amazing video!",
    "type": "video",
    "file_size_kb": 34.06,
    "timestamp": "2025-08-15 17:38:34.475734"
  }
}

8. Send Sticker

Send a WebP sticker.

POST /api/send-sticker

Content-Type: multipart/form-data

Form Parameters:

• phone (required): WhatsApp number
• file (required): WebP sticker file

Example:

curl -X POST http://localhost:5000/api/send-sticker \
  -F "phone=6281234567890" \
  -F "file=@funny_sticker.webp"

Success Response (200):

{
  "status": "success",
  "message": "Sticker sent successfully",
  "data": {
    "phone": "6281234567890",
    "filename": "funny_sticker.webp",
    "type": "sticker",
    "file_size_kb": 23.45,
    "timestamp": "2025-08-15 17:38:34.475734"
  }
}

---

📝 Request/Response Format

Phone Number Format

Phone numbers can be sent in various formats:

• 081234567890 (local format)
• +6281234567890 (international format)
• 6281234567890 (without +)

The API automatically converts to WhatsApp format: 6281234567890@s.whatsapp.net

File Upload Requirements

• Max file sizes vary by type (see supported media types)
• Files are automatically deleted after sending
• Secure filename processing to prevent path traversal
• MIME type detection for proper file handling

---

🎯 Supported Media Types

Media Type	Extensions	Max Size	Caption Support	Notes
Images	jpg, jpeg, png, gif, webp	16MB	✅ Yes	Most common image formats
Documents	pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip, rar, 7z	32MB	✅ Yes	Office documents and archives
Audio	mp3, wav, ogg, m4a, aac, flac	16MB	❌ No	Voice messages and music
Video	mp4, avi, mov, mkv, webm, 3gp, flv	64MB	✅ Yes	Video files with various codecs
Stickers	webp	1MB	❌ No	WebP format only, small size

---

❌ Error Handling

Error Response Format

All errors return JSON with consistent format:

{
  "status": "error",
  "message": "Error description here"
}

Common Error Codes

400 - Bad Request

{
  "status": "error",
  "message": "Phone number required"
}

{
  "status": "error",
  "message": "Invalid file type. Allowed: ['jpg', 'jpeg', 'png', 'gif', 'webp']"
}

{
  "status": "error",
  "message": "File too large. Max size for images: 16MB"
}

503 - Service Unavailable

{
  "status": "error",
  "message": "Bot not connected"
}

500 - Internal Server Error

{
  "status": "error",
  "message": "Failed to send message"
}

Validation Rules

1. Phone Number:

   • Must be 10-15 digits
   • Automatically formatted to Indonesian format (+62)
   • Invalid formats return 400 error

2. File Validation:

   • File type checked by extension
   • File size validated per media type
   • Missing files return 400 error

3. Bot Status:

   • Must be connected to WhatsApp
   • Returns 503 if not connected

---

📖 Examples

Text Message Example

JavaScript (fetch):

const response = await fetch('http://localhost:5000/api/send-message', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '6281234567890',
    message: 'Hello from JavaScript!'
  })
});

const result = await response.json();
console.log(result);

Python (requests):

import requests

data = {
    "phone": "6281234567890",
    "message": "Hello from Python!"
}

response = requests.post(
    'http://localhost:5000/api/send-message',
    json=data
)

print(response.json())

PHP:

<?php
$data = array(
    'phone' => '6281234567890',
    'message' => 'Hello from PHP!'
);

$response = file_get_contents(
    'http://localhost:5000/api/send-message',
    false,
    stream_context_create(array(
        'http' => array(
            'method' => 'POST',
            'header' => 'Content-Type: application/json',
            'content' => json_encode($data)
        )
    ))
);

echo $response;
?>

Image Upload Example

JavaScript (FormData):

const formData = new FormData();
formData.append('phone', '6281234567890');
formData.append('caption', '📸 Image from JavaScript');
formData.append('file', fileInput.files[0]);

const response = await fetch('http://localhost:5000/api/send-image', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log(result);

Python (requests with files):

import requests

files = {'file': open('image.jpg', 'rb')}
data = {
    'phone': '6281234567890',
    'caption': '📸 Image from Python'
}

response = requests.post(
    'http://localhost:5000/api/send-image',
    files=files,
    data=data
)

print(response.json())

Complete Test Script

Python test script:

import requests
import json

API_BASE = "http://localhost:5000"
TEST_PHONE = "6281234567890"

def test_all_endpoints():
    # Test text message
    print("Testing text message...")
    response = requests.post(f"{API_BASE}/api/send-message", json={
        "phone": TEST_PHONE,
        "message": "🧪 API Test - All endpoints working!"
    })
    print(f"Text: {response.status_code} - {response.json()}")
    
    # Test image (if you have test.jpg)
    try:
        with open('test.jpg', 'rb') as f:
            response = requests.post(f"{API_BASE}/api/send-image", 
                files={'file': f},
                data={'phone': TEST_PHONE, 'caption': '📸 Test image'}
            )
        print(f"Image: {response.status_code} - {response.json()}")
    except FileNotFoundError:
        print("Image: Skipped (no test.jpg file)")
    
    # Test document (if you have test.pdf)
    try:
        with open('test.pdf', 'rb') as f:
            response = requests.post(f"{API_BASE}/api/send-document",
                files={'file': f}, 
                data={'phone': TEST_PHONE, 'caption': '📄 Test document'}
            )
        print(f"Document: {response.status_code} - {response.json()}")
    except FileNotFoundError:
        print("Document: Skipped (no test.pdf file)")

if __name__ == "__main__":
    test_all_endpoints()

---

⚡ Rate Limits

Current Status: No rate limiting implemented

Recommendations for Production:

• Implement rate limiting per IP/user
• Suggested limits: 100 requests per hour
• Use Redis or in-memory storage for rate limiting
• Return 429 status code when exceeded

Example Implementation:

from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

limiter = Limiter(
    app,
    key_func=get_remote_address,
    default_limits=["100 per hour"]
)

@app.route('/api/send-message', methods=['POST'])
@limiter.limit("10 per minute")
def send_message():
    # endpoint implementation

---

🔧 Troubleshooting

Common Issues

1. Bot Not Connected

Error: "Bot not connected"

Solution:

• Check if WhatsApp bot is connected
• Restart the application
• Scan QR code with WhatsApp
• Check API status endpoint

2. Invalid Phone Number

Error: "Invalid phone number format"

Solution:

• Use proper phone number format
• Include country code for international numbers
• Remove special characters except +

3. File Too Large

Error: "File too large. Max size for images: 16MB"

Solution:

• Compress the file
• Check file size limits per media type
• Use appropriate compression tools

4. Unsupported File Type

Error: "Invalid file type. Allowed: ['mp3', 'wav', 'ogg']"

Solution:

• Convert file to supported format
• Check supported extensions for each media type
• Use online converters if needed

5. Connection Timeout

Error: "Message sending timeout"

Solution:

• Check internet connection
• Try smaller file sizes
• Wait and retry
• Check server resources

Debug Mode

To enable debug mode, set environment variable:

export FLASK_DEBUG=1
python3 app.py

Health Check

Always check bot status before sending messages:

curl http://localhost:5000/api/status

Ensure bot_connected: true before sending messages.

---

🔒 Security Considerations

Production Deployment

1. Authentication:

   • Add API key authentication
   • Implement JWT tokens
   • Use HTTPS in production

2. Rate Limiting:

   • Implement per-user limits
   • Use Redis for distributed limiting
   • Monitor abuse patterns

3. File Validation:

   • Scan files for malware
   • Validate file content, not just extension
   • Implement file quarantine

4. Logging:

   • Log all API requests
   • Monitor error patterns
   • Implement audit trails

Example Security Headers

@app.after_request
def after_request(response):
    response.headers['X-Content-Type-Options'] = 'nosniff'
    response.headers['X-Frame-Options'] = 'DENY'
    response.headers['X-XSS-Protection'] = '1; mode=block'
    return response

---

📞 Support

For issues and questions:

• Check this documentation first
• Review error messages carefully
• Test with minimal examples
• Check bot connection status

API Version: 2.0.0
Last Updated: August 15, 2025
Status: Production Ready ✅