WhatsAppBlitz is a powerful and user-friendly automation tool designed to send WhatsApp messages to multiple contacts from Excel files. It features advanced capabilities including image support, custom placeholders, phone number validation, and a modern GUI interface built with CustomTkinter.
- Excel Integration: Import contacts from Excel files with multi-sheet support
- Sheet Sequence Selector: Define exact processing order for multiple sheets
- Data Preview: Enhanced table view with processing statistics
- Phone Number Processing: Automatic normalization and validation
- Number Comparison: Before/after processing preview
- Smart Placeholders: Personalize messages with dynamic content
- Template System: Create and manage message templates
- Image Support: Attach images with automatic optimization
- Audio Support: Attach audio files with format validation (.mp3, .wav, .m4a, .ogg, .aac)
- Video Support: Attach video files with multiple format support (.mp4, .avi, .mov, .mkv, .webm)
- Message Preview: Real-time preview of personalized messages
- Modern GUI: Built with CustomTkinter for a sleek experience
- Intuitive Design: User-friendly interface with clear navigation
- Progress Tracking: Real-time sending progress and statistics
- Configuration Editor: Easy-to-use settings management
- Error Handling: Robust error management and logging system
- Pause Management: Smart pause system to avoid rate limiting
- Resource Monitoring: CPU and memory usage optimization
- Comprehensive Logging: Detailed logs for troubleshooting
- Python 3.8 or higher
- Windows OS (recommended)
- WhatsApp Web access
# Clone the repository
git clone https://github.com/Javi-CD/whatsappblitz.git
# Navigate to the directory
cd whatsappblitz
# Install dependencies
pip install -r requirements.txt-
Launch the application:
python main.py
For core version (CLI):
python main.py --core -
Load your Excel file with contact data
-
Select the sheet containing your data
-
Review the preview of processed phone numbers
-
Upload media files to attach:
- Images: Automatically optimized (JPEG, PNG, WebP)
- Audio: Multiple formats supported (MP3, WAV, M4A, OGG, AAC)
- Videos: Multiple formats supported (MP4, AVI, MOV, MKV, WebM)
-
Configure placeholders according to your needs
-
Click "Start Sending" and you're ready to go!
Using setup.py:
python setup.py installBuild executable:
# Run the build script (Windows)
scripts\build.batYour Excel file must contain at least:
- "Whatsapp" column with phone numbers
- "Mensaje" (Message) column with text to send
- Additional columns for use as placeholders
| Name | Company | Mensaje | |
|---|---|---|---|
| 573001234567 | Juan | Acme Inc. | Hello, {name}! |
| 573007654321 | María | XYZ Corp. | Good morning {Name} from {company} |
- Use international format for phone numbers (e.g., 573001234567)
- Ensure consistent column naming across sheets
- Avoid empty rows between data
- Use UTF-8 encoding for special characters
The config.json file allows detailed customization of the application behavior:
Below are examples of some basic program configurations.
Click to open
{
"excel_file": "data.xlsx",
"imagen_predeterminada": "image.jpg",
"header_row": 4,
"wait_time": 20,
"pause_between_messages": 8,
"default_region": "57"
}{****
"number_processing": {
"auto_fix_decimals": true,
"strip_leading_zeros": true,
"add_country_code": true,
"country_code": "57",
"min_length": 10,
"max_length": 15
}
}{
"preview": {
"show_processing_preview": true,
"max_preview_rows": 20,
"highlight_changes": true
}
}{
"image_optimization": {
"enabled": true,
"max_width": 1280,
"quality": 85,
"format": "webp"
}
}{
"messages_before_long_pause": 1000,
"long_pause_duration": 300,
"memory_threshold_mb": 1000,
"cpu_threshold_percent": 80
}- Python 3.8+ - Main programming language
- CustomTkinter - Modern GUI framework
- Pandas - Data manipulation and analysis
- Pillow (PIL) - Image processing and optimization
- PyWhatKit - WhatsApp Web integration
- phonenumbers - Phone number validation and formatting
- openpyxl/xlrd - Excel file processing
- psutil - System resource monitoring
- cryptography - License verification
- pytest - Testing framework
- rich - Enhanced console output
- Table View: Visualize all your Excel data in an organized table
- Number Processing Comparison:
- Before/after processing view
- Change statistics and validation results
- Automatic format correction preview
- Column Overview: Clear list of available fields and placeholders
- Processing Statistics: Real-time data processing insights
- Automatic Normalization: Standardize phone number formats
- Format Validation: Ensure valid phone number structure
- Country Code Addition: Automatic international format conversion
- Common Format Fixes: Correct typical formatting issues
- Validation Reports: Detailed processing results
- Automatic Resizing: Smart dimension adjustment for optimal delivery
- Smart Compression: Reduce file size while maintaining quality
- Quality Preservation: Advanced algorithms to maintain visual fidelity
- Multi-format Support: JPEG, PNG, WebP, and more
- Batch Processing: Optimize multiple images efficiently
- Multiple Audio Formats: Support for MP3, WAV, M4A, OGG, and AAC files
- Automatic Format Validation: Ensures audio files are in supported formats
- Smart Attachment Detection: Advanced CV2-based button detection for reliable audio attachment
- Robust Retry System: Intelligent retry mechanism for audio file uploads
- File Size Optimization: Automatic handling of audio file constraints
- Multiple Video Formats: Support for MP4, AVI, MOV, MKV, and WebM files
- File Size Validation: Automatic validation with configurable size limits (default 64MB)
- Smart Attachment System: Robust video attachment using CV2-based template matching
- Advanced Error Handling: Multiple retry mechanisms for reliable video uploads
- Preview Functionality: Built-in video information preview with file details
- Configurable Timeouts: Customizable timeout settings for video processing
Click to Open
WhatsappBlitz/
├── src/
│ ├── core/ # Core application logic
│ ├── gui/ # GUI components
│ └── utils/ # Utility functions
├── config/ # Configuration files
├── assets/ # Images and resources
├── tests/ # Test suite
├── scripts/ # Build and utility scripts
├── main.py # Application entry point
├── requirements.txt # Python dependencies
└── README.md # This file
This project is licensed under the GPL License - see the LICENSE file for details.
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b type/branch-name) - Commit your changes (
git commit -m 'type(scope): description') - Push to the branch (
git push origin type/branch-name) - Open a Pull Request
Please open an issue first to discuss major changes.
If you encounter any issues, please create an issue with:
- Detailed problem description
- Steps to reproduce the issue
- Screenshots (if applicable)
- Relevant logs (located in the
logsfolder) - System information (OS, Python version, etc.)
For additional support:
- Email: javierperezdeveloper@gmail.com
- Issues: GitHub Issues
WhatsAppBlitz - Making WhatsApp automation simple and efficient