{"id":28950064,"url":"https://github.com/a3ro-dev/whatsapp_api_wrapper","last_synced_at":"2026-03-16T06:37:04.436Z","repository":{"id":297786568,"uuid":"997898611","full_name":"a3ro-dev/whatsapp_api_wrapper","owner":"a3ro-dev","description":"A comprehensive, production-ready Python wrapper around the WhatsApp Web API that provides strongly-typed interfaces, comprehensive error handling, automatic retries, and full test coverage.","archived":false,"fork":false,"pushed_at":"2025-06-22T16:44:41.000Z","size":77,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-22T17:27:06.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a3ro-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T12:36:25.000Z","updated_at":"2025-06-22T16:44:45.000Z","dependencies_parsed_at":"2025-06-07T13:39:00.620Z","dependency_job_id":"7dc52643-5ba9-4d0e-87ba-705319fb2dd9","html_url":"https://github.com/a3ro-dev/whatsapp_api_wrapper","commit_stats":null,"previous_names":["a3ro-dev/whatsapp_api_wrapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/a3ro-dev/whatsapp_api_wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a3ro-dev%2Fwhatsapp_api_wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a3ro-dev%2Fwhatsapp_api_wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a3ro-dev%2Fwhatsapp_api_wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a3ro-dev%2Fwhatsapp_api_wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a3ro-dev","download_url":"https://codeload.github.com/a3ro-dev/whatsapp_api_wrapper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a3ro-dev%2Fwhatsapp_api_wrapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261483989,"owners_count":23165419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-23T13:04:54.825Z","updated_at":"2026-03-16T06:37:04.418Z","avatar_url":"https://github.com/a3ro-dev.png","language":"Python","readme":"# WhatsApp API Python Wrapper\n\nA comprehensive, production-ready Python wrapper around the WhatsApp Web API that provides strongly-typed interfaces, comprehensive error handling, automatic retries, and full test coverage.\n\n[![Python Version](https://img.shields.io/pypi/pyversions/whatsapp-api-py)](https://pypi.org/project/whatsapp-api-py/)\n[![PyPI Version](https://img.shields.io/pypi/v/whatsapp-api-py)](https://pypi.org/project/whatsapp-api-py/)\n[![License](https://img.shields.io/pypi/l/whatsapp-api-py)](https://github.com/a3ro-dev/whatsapp_api_wrapper/blob/main/LICENSE)\n[![Tests](https://img.shields.io/badge/tests-passing-green)](https://github.com/a3ro-dev/whatsapp_api_wrapper/actions)\n\n## About This Project\n\nThis project is a Python wrapper for the Node.js-based WhatsApp REST API located in the [`whatsapp-api/`](../whatsapp-api/) directory. The underlying API is a REST wrapper for the [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) library, designed to be used as a Docker container and to provide easy integration with non-Node.js projects.\n\n### Underlying WhatsApp API\n\nThe core WhatsApp API server (located in [`whatsapp-api/`](whatsapp-api/)) provides:\n\n- **REST API Endpoints**: Complete WhatsApp Web functionality via HTTP endpoints\n- **Docker Support**: Ready-to-use Docker container for easy deployment\n- **Session Management**: Multiple WhatsApp sessions with QR code authentication\n- **Media Support**: Send/receive images, videos, documents, and audio files\n- **Group Management**: Create groups, manage participants, and handle group settings\n- **Real-time Callbacks**: WebSocket callbacks for incoming messages and status changes\n\nFor detailed information about setting up and running the underlying API server, see the [WhatsApp API README](whatsapp-api/README.md).\n\n### Prerequisites\n\nBefore using this Python wrapper, you need to have the WhatsApp API server running:\n\n```bash\n# Navigate to the WhatsApp API directory\ncd whatsapp-api\n\n# Run with Docker Compose\ndocker-compose pull \u0026\u0026 docker-compose up\n```\n\nThe API server will be available at `http://localhost:3000` with documentation at `http://localhost:3000/api-docs/`.\n\n#### API Server Features\n\nThe underlying WhatsApp API server supports a comprehensive range of WhatsApp Web functionalities:\n\n**Messaging:**\n- Send text, image, video, audio, and document messages\n- Send contact and location messages\n- Send button and list messages\n- Message reactions and replies\n- Download media attachments\n\n**Session Management:**\n- Multiple concurrent WhatsApp sessions\n- QR code authentication\n- Session health monitoring\n- Automatic session recovery\n\n**Chat \u0026 Contact Management:**\n- Retrieve all chats and contacts\n- Block/unblock contacts\n- Archive/unarchive chats\n- Check if number is registered on WhatsApp\n\n**Group Operations:**\n- Create and manage groups\n- Add/remove participants\n- Promote/demote administrators\n- Group invite management\n\n**Profile \u0026 Status:**\n- Update profile picture and status\n- Get user presence information\n- Send typing/recording indicators\n\nFor a complete list of available endpoints and features, visit the API documentation at `http://localhost:3000/api-docs/` when the server is running.\n\n## Features\n\n- 🚀 **Full API Coverage**: Complete implementation of all WhatsApp Web API endpoints\n- 🔒 **Type Safety**: Fully typed with Pydantic models for request/response validation\n- 🛡️ **Error Handling**: Comprehensive error handling with custom exceptions\n- 🔄 **Automatic Retries**: Built-in retry logic with exponential backoff for transient failures\n- 📊 **Logging**: Detailed logging for debugging and monitoring\n- 🧪 **Well Tested**: Comprehensive test suite with unit and integration tests\n- 📖 **Documentation**: Complete API documentation and examples\n\n## Architecture\n\nThis Python wrapper is built with the following key components:\n\n- **HTTP Client**: Uses `httpx` for robust HTTP communication with retry mechanisms\n- **Data Validation**: `Pydantic` models ensure type safety for all requests and responses\n- **Error Handling**: Custom exception hierarchy for different error types\n- **Retry Logic**: `tenacity` library provides automatic retries with exponential backoff\n- **Testing**: Comprehensive test suite using `pytest` with unit and integration tests\n\n### Package Structure\n\n```\nwhatsapp_api_wrapper/\n├── __init__.py         # Main package exports\n├── client.py           # WhatsAppAPI client class\n├── models.py           # Pydantic models for requests \u0026 responses\n├── exceptions.py       # Custom exception classes\n├── utils.py            # Utility functions and helpers\n└── py.typed           # Type hints marker file\ntests/                  # Pytest test suites\n├── unit/              # Unit tests\n└── integration/       # Integration tests\n```\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install whatsapp-api-py\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/a3ro-dev/whatsapp_api_wrapper.git\ncd whatsapp_api_wrapper/whatsapp-api-py\n\n# Install the package\npip install -e .\n```\n\n### Development Installation\n\n```bash\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Install all optional dependencies\npip install -e \".[all]\"\n```\n\n## Quick Start\n\n```python\nfrom whatsapp_api_wrapper import WhatsAppAPI\nfrom whatsapp_api_wrapper.models import TextMessage\n\n# Initialize the client\napi = WhatsAppAPI(\n    api_key=\"your-api-key\",  # Optional, can be None for local development\n    base_url=\"http://localhost:3000\"  # Your WhatsApp API server URL\n)\n\n# Start a session\nsession_id = \"my-session-123\"\nsession_status = api.start_session(session_id)\nprint(f\"Session started: {session_status.success}\")\n\n# Get QR code for initial setup\nqr_response = api.get_qr_code(session_id)\nprint(f\"QR Code: {qr_response.qr}\")\n\n# Send a text message\nmessage_request = TextMessage(\n    to=\"1234567890@c.us\",  # Phone number with @c.us suffix\n    body=\"Hello from Python!\"\n)\nresponse = api.send_message(session_id, message_request)\nprint(f\"Message sent: {response.success}, ID: {response.messageId}\")\n\n# Get all chats\nchats = api.get_chats(session_id)\nfor chat in chats.chats:\n    print(f\"Chat: {chat.name} ({chat.id})\")\n\n# Get all contacts\ncontacts = api.get_contacts(session_id)\nfor contact in contacts.contacts:\n    print(f\"Contact: {contact.name} ({contact.number})\")\n```\n\n## Advanced Usage\n\n### Media Messages\n\n```python\nfrom whatsapp_api_wrapper.models import MediaMessage\n\n# Send an image\nmedia_request = MediaMessage(\n    to=\"1234567890@c.us\",\n    media=\"base64-encoded-image-data\",  # or URL to image\n    type=\"image\",\n    caption=\"Check out this photo!\",\n    filename=\"photo.jpg\"\n)\nresponse = api.send_message(session_id, media_request)\n```\n\n### Group Management\n\n```python\nfrom whatsapp_api_wrapper.models import GroupActionRequest\n\n# Create a group\ngroup_request = GroupActionRequest(\n    name=\"My Python Group\",\n    participants=[\"1234567890@c.us\", \"0987654321@c.us\"]\n)\ngroup_response = api.create_group(session_id, group_request)\n\n# Add participants to the group\nadd_request = GroupActionRequest(\n    chatId=group_response.groupId,\n    participants=[\"1111111111@c.us\"]\n)\napi.add_participants(session_id, add_request)\n```\n\n### Error Handling\n\n```python\nfrom whatsapp_api_wrapper.exceptions import (\n    WhatsAppAPIError,\n    WhatsAppConnectionError,\n    WhatsAppHTTPError,\n    WhatsAppSessionError,\n    WhatsAppRateLimitError\n)\n\ntry:\n    response = api.send_message(session_id, message_request)\nexcept WhatsAppSessionError as e:\n    print(f\"Session error: {e.message}\")\nexcept WhatsAppRateLimitError as e:\n    print(f\"Rate limited. Retry after: {e.retry_after} seconds\")\nexcept WhatsAppConnectionError as e:\n    print(f\"Connection failed: {e.message}\")\nexcept WhatsAppHTTPError as e:\n    print(f\"HTTP error {e.status_code}: {e.message}\")\nexcept WhatsAppAPIError as e:\n    print(f\"API error: {e.message}\")\n```\n\n### Context Manager\n\n```python\n# Use as a context manager for automatic cleanup\nwith WhatsAppAPI(base_url=\"http://localhost:3000\") as api:\n    api.start_session(session_id)\n    # ... do work ...\n# Session automatically closed\n```\n\n### Custom Configuration\n\n```python\nimport httpx\n\n# Custom HTTP client with specific timeout and headers\ncustom_client = httpx.Client(\n    timeout=60.0,\n    headers={\"User-Agent\": \"My-Custom-Agent\"}\n)\n\napi = WhatsAppAPI(\n    api_key=\"your-api-key\",\n    base_url=\"http://localhost:3000\",\n    timeout=60,\n    max_retries=5,\n    backoff_factor=2.0,\n    session=custom_client\n)\n)\n```\n\n## API Reference\n\n### Session Management\n\n- `start_session(session_id)` - Start a new WhatsApp session\n- `get_session_status(session_id)` - Get session status\n- `get_qr_code(session_id)` - Get QR code for session setup\n- `get_qr_code_image(session_id)` - Get QR code as PNG image\n- `restart_session(session_id)` - Restart a session\n- `terminate_session(session_id)` - Terminate a session\n- `terminate_inactive_sessions()` - Terminate all inactive sessions\n- `terminate_all_sessions()` - Terminate all sessions\n\n### Messaging\n\n- `send_message(session_id, request)` - Send various types of messages\n- `delete_message(session_id, request)` - Delete a message\n- `forward_message(session_id, request)` - Forward a message\n- `react_to_message(session_id, request)` - React to a message\n- `download_media(session_id, request)` - Download media from a message\n\n### Chat Management\n\n- `get_chats(session_id)` - Get all chats\n- `get_chat_by_id(session_id, request)` - Get specific chat\n- `archive_chat(session_id, request)` - Archive a chat\n- `unarchive_chat(session_id, request)` - Unarchive a chat\n- `mute_chat(session_id, request)` - Mute a chat\n- `unmute_chat(session_id, request)` - Unmute a chat\n- `pin_chat(session_id, request)` - Pin a chat\n- `unpin_chat(session_id, request)` - Unpin a chat\n- `clear_messages(session_id, request)` - Clear chat messages\n- `delete_chat(session_id, request)` - Delete a chat\n- `fetch_messages(session_id, request)` - Fetch chat messages\n- `search_messages(session_id, request)` - Search messages\n\n### Contact Management\n\n- `get_contacts(session_id)` - Get all contacts\n- `get_contact_by_id(session_id, request)` - Get specific contact\n- `block_contact(session_id, request)` - Block a contact\n- `unblock_contact(session_id, request)` - Unblock a contact\n- `get_blocked_contacts(session_id)` - Get blocked contacts\n- `is_registered_user(session_id, request)` - Check if number is registered\n- `get_number_id(session_id, request)` - Get WhatsApp ID for number\n- `get_profile_pic_url(session_id, request)` - Get profile picture URL\n- `get_contact_about(session_id, request)` - Get contact's about text\n\n### Group Management\n\n- `create_group(session_id, request)` - Create a new group\n- `add_participants(session_id, request)` - Add group participants\n- `remove_participants(session_id, request)` - Remove group participants\n- `promote_participants(session_id, request)` - Promote to admin\n- `demote_participants(session_id, request)` - Demote from admin\n- `get_invite_code(session_id, request)` - Get group invite code\n- `revoke_invite(session_id, request)` - Revoke group invite\n- `leave_group(session_id, request)` - Leave a group\n- `set_group_subject(session_id, request)` - Set group name\n- `set_group_description(session_id, request)` - Set group description\n- `set_group_picture(session_id, request)` - Set group picture\n- `delete_group_picture(session_id, request)` - Delete group picture\n\n### Profile Management\n\n- `set_status(session_id, request)` - Set status message\n- `set_display_name(session_id, request)` - Set display name\n- `set_profile_picture(session_id, request)` - Set profile picture\n- `send_presence_available(session_id, request)` - Set presence as available\n- `send_presence_unavailable(session_id, request)` - Set presence as unavailable\n\n### State Management\n\n- `send_seen(session_id, request)` - Mark messages as seen\n- `send_state_typing(session_id, request)` - Send typing indicator\n- `send_state_recording(session_id, request)` - Send recording indicator\n\n## Error Handling\n\nThe wrapper provides comprehensive error handling with specific exception types:\n\n- `WhatsAppAPIError` - Base exception for all API errors\n- `WhatsAppConnectionError` - Network connectivity issues\n- `WhatsAppHTTPError` - HTTP errors (4xx, 5xx status codes)\n- `WhatsAppValidationError` - Request/response validation errors\n- `WhatsAppSessionError` - Session-related errors\n- `WhatsAppRateLimitError` - Rate limiting errors (429 status)\n- `WhatsAppAuthenticationError` - Authentication errors (403 status)\n- `WhatsAppNotFoundError` - Resource not found errors (404 status)\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=whatsapp_api_wrapper\n\n# Run only unit tests\npytest -m unit\n\n# Run only integration tests\npytest -m integration\n```\n\n## Development\n\n### Setting up development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/a3ro-dev/whatsapp_api_wrapper.git\ncd whatsapp_api_wrapper/whatsapp-api-py\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Code formatting\n\n```bash\n# Format code\nblack whatsapp_api_wrapper/ tests/\nisort whatsapp_api_wrapper/ tests/\n\n# Type checking\nmypy whatsapp_api_wrapper/\n\n# Linting\nflake8 whatsapp_api_wrapper/ tests/\n```\n\n## Requirements\n\n- **Python 3.10+**\n- **WhatsApp Web API server** (from [`../whatsapp-api/`](../whatsapp-api/) directory) running at `http://localhost:3000`\n  - This is the underlying Node.js API that this wrapper communicates with\n  - Must be running before using this Python wrapper\n- Optional: API key for authentication\n\n### Starting the Required API Server\n\n```bash\n# Navigate to the WhatsApp API directory (from the project root)\ncd ../whatsapp-api\n\n# Start the API server with Docker\ndocker-compose pull \u0026\u0026 docker-compose up\n\n# The server will be available at http://localhost:3000\n# API documentation will be at http://localhost:3000/api-docs/\n```\n\n## Dependencies\n\n- `httpx` - Modern HTTP client\n- `pydantic` - Data validation and serialization\n- `tenacity` - Retry logic with exponential backoff\n\n## Future Enhancements\n\n- **Bulk Operations**: Enhanced support for bulk message sending with rate limiting and queue management\n- **Concurrency**: Improved concurrent session handling for high-throughput applications\n- **Async Support**: Full async/await support using `httpx.AsyncClient` for better performance\n- **Advanced Retry Strategies**: Configurable retry strategies for different error types\n- **Webhook Support**: Built-in webhook handling for real-time message callbacks\n- **Message Templates**: Template system for common message types and formats\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\n**IMPORTANT**: This wrapper uses WhatsApp Web protocol through the underlying API server. WhatsApp does not allow bots or unofficial clients on their platform. Use this wrapper at your own risk - there's no guarantee you won't be blocked by WhatsApp for using unofficial API methods.\n\nThis project is for educational and development purposes. Always comply with WhatsApp's Terms of Service and local regulations when using this tool.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for your changes\n5. Ensure all tests pass (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## Disclaimer\n\nThis project is not affiliated with WhatsApp or Meta. Use at your own risk and ensure compliance with WhatsApp's Terms of Service.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa3ro-dev%2Fwhatsapp_api_wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa3ro-dev%2Fwhatsapp_api_wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa3ro-dev%2Fwhatsapp_api_wrapper/lists"}