<div align="center">
<h1>whatsloon</h1>
<p>A Python wrapper facilitating seamless integration with the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a>. Streamline your messaging workflows and enhance user engagement with this efficient toolkit.
</p>
<a href="https://pepy.tech/projects/whatsloon"><img src="https://static.pepy.tech/badge/whatsloon" alt="PyPI Downloads"></a>
<a href="https://pepy.tech/projects/whatsloon"><img src="https://static.pepy.tech/badge/whatsloon/month" alt="PyPI Downloads"></a>
<a href="https://pepy.tech/projects/whatsloon"><img src="https://static.pepy.tech/badge/whatsloon/week" alt="PyPI Downloads"></a>
</div>
## Overview
whatsloon is a robust Python SDK for the WhatsApp Cloud API. It provides a comprehensive set of mixin classes and utilities to send all supported WhatsApp message types, including text, media, interactive, template, location, reaction, sticker, and more. The package is designed for both synchronous and asynchronous workflows, with strong validation and error handling.
## Features
- Send Text, Image, Video, Audio, and Document messages
- Send Interactive messages: Lists, Reply Buttons, Flows, CTA buttons
- Send Location and Location Request messages
- Send Contact and Address messages
- Send Template messages (with components)
- Send Stickers and Reactions
- Send Typing Indicators
- Mark messages as Read
- Robust validation for API limits (e.g., button/section/row limits)
- Both synchronous and asynchronous support (requests and httpx)
- Clear error handling and logging
## Key Components
- Mixin Classes: Each message type (text, image, video, audio, document, list, flow, reply buttons, template, sticker, reaction, location, location request, contact, address, typing indicator, read receipt) is implemented as a robust, reusable mixin class.
- WhatsAppBaseClient: Easily compose your own client by combining mixins for only the features you need.
- Validation: All payload builders validate API limits and required fields.
- Async & Sync: All senders support both synchronous (requests) and asynchronous (httpx) usage.
## Installation
```sh
pip install whatsloon
```
## Usage Examples
### 1. Using WhatsAppCloudAPIClient (All Features, Easiest)
```python
from whatsloon import WhatsAppCloudAPIClient
client = WhatsAppCloudAPIClient(
access_token="YOUR_API_KEY",
phone_number_id="phone_number_id",
recipient_country_code="91",
recipient_mobile_number="9876543210",
)
# Synchronous usage
result = client.send_text_message("Hello, world!", preview_url=True)
print(result)
# Asynchronous usage
import asyncio
async def main():
result = await client.async_send_text_message("Hello async!", preview_url=True)
print(result)
asyncio.run(main())
# Send an image (sync)
result = client.send_image_message(media_id="MEDIA_ID", caption="A photo")
print(result)
# Send an image (async)
async def main_img():
result = await client.async_send_image_message(media_id="MEDIA_ID", caption="Async photo")
print(result)
asyncio.run(main_img())
```
### 2. Composing Your Own Client (Selected Features Only)
```python
# Import mixins directly from the package root
from whatsloon import WhatsAppBaseClient, TextSender, ImageSender
class MyWhatsAppClient(WhatsAppBaseClient, TextSender, ImageSender):
pass
client = MyWhatsAppClient(
access_token="YOUR_API_KEY",
phone_number_id="phone_number_id",
recipient_country_code="91",
recipient_mobile_number="9876543210",
)
# Use only the features you mix in
result = client.send_text_message("Hello, world!", preview_url=True)
print(result)
```
### 3. Without Mixins (Direct Usage)
```python
from whatsloon import WhatsAppBaseClient
class SimpleClient(WhatsAppBaseClient):
pass
client = SimpleClient(
access_token="YOUR_API_KEY",
phone_number_id="phone_number_id",
recipient_country_code="91",
recipient_mobile_number="9876543210",
)
# You can use the generic send_message method for custom payloads:
payload = {
"type": "text",
"text": {"body": "Hello from custom payload!"}
}
result = client.send_message(payload)
print(result)
# Async version
import asyncio
async def main():
result = await client.async_send_message(payload)
print(result)
asyncio.run(main())
```
## Testing
whatsloon includes comprehensive tests for all mixins, message types, and integration scenarios.
- **Test Dependencies:**
- Requires `pytest` (and optionally `pytest-asyncio` for async tests)
- Install with: `pip install -r requirements.txt` (if provided) or `pip install pytest pytest-asyncio`
- **Running All Tests:**
```sh
pytest tests/
```
- **Running a Specific Test File:**
```sh
pytest tests/test_text.py
```
- **Test Coverage:**
To check coverage (if `pytest-cov` is installed):
```sh
pytest --cov=whatsloon tests/
```
- **Contributing Tests:**
- Add new tests in the `tests/` directory, following the pattern `test_<module>.py`.
- Each test function should include a docstring explaining its purpose and expected input/output.
- Edge cases and error handling are strongly encouraged.
## Contributing
Contributions are welcome! To contribute to whatsloon:
- **Bug Reports & Feature Requests:**
- Please use the [GitHub Issues](https://github.com/maharanasarkar/whatsloon/issues) page to report bugs or suggest features.
- **Pull Requests:**
- Fork the repository and create a new branch for your feature or fix.
- Ensure your code follows the existing style and includes type hints and docstrings.
- Add or update tests as appropriate.
- Run all tests locally with `pytest` before submitting.
- Submit a pull request with a clear description of your changes.
- **Code Style:**
- We recommend using `black` for formatting and `flake8` for linting.
- All public APIs should have type hints and Google-style docstrings.
Thank you for helping improve whatsloon!
Raw data
{
"_id": null,
"home_page": "https://github.com/maharanasarkar/whatsloon",
"name": "whatsloon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.6",
"maintainer_email": null,
"keywords": "whatsloon, whatsloon-library, WhatsApp API in Python, whatsloon-python, WhatsApp Cloud API Wrapper",
"author": "Maharana Sarkar",
"author_email": "Maharana Sarkar <maharana.sarkar2000@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/82/63/4762d57a5a3fb6650ca8827e5858df22665766cf1b9fe5e5617d1fb8d698/whatsloon-2.0.5.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1>whatsloon</h1>\n <p>A Python wrapper facilitating seamless integration with the <a href=\"https://developers.facebook.com/docs/whatsapp/cloud-api\">WhatsApp Cloud API</a>. Streamline your messaging workflows and enhance user engagement with this efficient toolkit.\n </p>\n <a href=\"https://pepy.tech/projects/whatsloon\"><img src=\"https://static.pepy.tech/badge/whatsloon\" alt=\"PyPI Downloads\"></a>\n <a href=\"https://pepy.tech/projects/whatsloon\"><img src=\"https://static.pepy.tech/badge/whatsloon/month\" alt=\"PyPI Downloads\"></a>\n <a href=\"https://pepy.tech/projects/whatsloon\"><img src=\"https://static.pepy.tech/badge/whatsloon/week\" alt=\"PyPI Downloads\"></a>\n</div>\n\n\n## Overview\nwhatsloon is a robust Python SDK for the WhatsApp Cloud API. It provides a comprehensive set of mixin classes and utilities to send all supported WhatsApp message types, including text, media, interactive, template, location, reaction, sticker, and more. The package is designed for both synchronous and asynchronous workflows, with strong validation and error handling.\n\n\n## Features\n- Send Text, Image, Video, Audio, and Document messages\n- Send Interactive messages: Lists, Reply Buttons, Flows, CTA buttons\n- Send Location and Location Request messages\n- Send Contact and Address messages\n- Send Template messages (with components)\n- Send Stickers and Reactions\n- Send Typing Indicators\n- Mark messages as Read\n- Robust validation for API limits (e.g., button/section/row limits)\n- Both synchronous and asynchronous support (requests and httpx)\n- Clear error handling and logging\n\n\n## Key Components\n- Mixin Classes: Each message type (text, image, video, audio, document, list, flow, reply buttons, template, sticker, reaction, location, location request, contact, address, typing indicator, read receipt) is implemented as a robust, reusable mixin class.\n- WhatsAppBaseClient: Easily compose your own client by combining mixins for only the features you need.\n- Validation: All payload builders validate API limits and required fields.\n- Async & Sync: All senders support both synchronous (requests) and asynchronous (httpx) usage.\n\n\n## Installation\n```sh\npip install whatsloon\n```\n\n\n\n## Usage Examples\n\n\n### 1. Using WhatsAppCloudAPIClient (All Features, Easiest)\n```python\nfrom whatsloon import WhatsAppCloudAPIClient\n\nclient = WhatsAppCloudAPIClient(\n access_token=\"YOUR_API_KEY\",\n phone_number_id=\"phone_number_id\",\n recipient_country_code=\"91\",\n recipient_mobile_number=\"9876543210\",\n)\n\n# Synchronous usage\nresult = client.send_text_message(\"Hello, world!\", preview_url=True)\nprint(result)\n\n# Asynchronous usage\nimport asyncio\nasync def main():\n result = await client.async_send_text_message(\"Hello async!\", preview_url=True)\n print(result)\nasyncio.run(main())\n\n# Send an image (sync)\nresult = client.send_image_message(media_id=\"MEDIA_ID\", caption=\"A photo\")\nprint(result)\n\n# Send an image (async)\nasync def main_img():\n result = await client.async_send_image_message(media_id=\"MEDIA_ID\", caption=\"Async photo\")\n print(result)\nasyncio.run(main_img())\n```\n\n### 2. Composing Your Own Client (Selected Features Only)\n```python\n# Import mixins directly from the package root\nfrom whatsloon import WhatsAppBaseClient, TextSender, ImageSender\n\nclass MyWhatsAppClient(WhatsAppBaseClient, TextSender, ImageSender):\n pass\n\nclient = MyWhatsAppClient(\n access_token=\"YOUR_API_KEY\",\n phone_number_id=\"phone_number_id\",\n recipient_country_code=\"91\",\n recipient_mobile_number=\"9876543210\",\n)\n\n# Use only the features you mix in\nresult = client.send_text_message(\"Hello, world!\", preview_url=True)\nprint(result)\n```\n\n\n### 3. Without Mixins (Direct Usage)\n```python\nfrom whatsloon import WhatsAppBaseClient\n\nclass SimpleClient(WhatsAppBaseClient):\n pass\n\nclient = SimpleClient(\n access_token=\"YOUR_API_KEY\",\n phone_number_id=\"phone_number_id\",\n recipient_country_code=\"91\",\n recipient_mobile_number=\"9876543210\",\n)\n\n# You can use the generic send_message method for custom payloads:\npayload = {\n \"type\": \"text\",\n \"text\": {\"body\": \"Hello from custom payload!\"}\n}\nresult = client.send_message(payload)\nprint(result)\n\n# Async version\nimport asyncio\nasync def main():\n result = await client.async_send_message(payload)\n print(result)\nasyncio.run(main())\n```\n\n\n## Testing\nwhatsloon includes comprehensive tests for all mixins, message types, and integration scenarios.\n\n- **Test Dependencies:**\n - Requires `pytest` (and optionally `pytest-asyncio` for async tests)\n - Install with: `pip install -r requirements.txt` (if provided) or `pip install pytest pytest-asyncio`\n\n- **Running All Tests:**\n ```sh\n pytest tests/\n ```\n\n- **Running a Specific Test File:**\n ```sh\n pytest tests/test_text.py\n ```\n\n- **Test Coverage:**\n To check coverage (if `pytest-cov` is installed):\n ```sh\n pytest --cov=whatsloon tests/\n ```\n\n- **Contributing Tests:**\n - Add new tests in the `tests/` directory, following the pattern `test_<module>.py`.\n - Each test function should include a docstring explaining its purpose and expected input/output.\n - Edge cases and error handling are strongly encouraged.\n\n\n## Contributing\n\nContributions are welcome! To contribute to whatsloon:\n\n- **Bug Reports & Feature Requests:**\n - Please use the [GitHub Issues](https://github.com/maharanasarkar/whatsloon/issues) page to report bugs or suggest features.\n\n- **Pull Requests:**\n - Fork the repository and create a new branch for your feature or fix.\n - Ensure your code follows the existing style and includes type hints and docstrings.\n - Add or update tests as appropriate.\n - Run all tests locally with `pytest` before submitting.\n - Submit a pull request with a clear description of your changes.\n\n- **Code Style:**\n - We recommend using `black` for formatting and `flake8` for linting.\n - All public APIs should have type hints and Google-style docstrings.\n\nThank you for helping improve whatsloon!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A user-friendly Python wrapper for the WhatsApp Cloud API. Easily integrate WhatsApp messaging into your applications and enhance user engagement with streamlined workflows.",
"version": "2.0.5",
"project_urls": {
"Homepage": "https://github.com/maharanasarkar/whatsloon"
},
"split_keywords": [
"whatsloon",
" whatsloon-library",
" whatsapp api in python",
" whatsloon-python",
" whatsapp cloud api wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b6c3f347fb88cdce3e042d5580abe82fc1ddc58438dd521d9d015f927242e795",
"md5": "4da3826e1baea8339b4b71134e59c555",
"sha256": "07ccb0fe75c05b21e5072ae9594db5966cbeb9536047ec8fe3414fb3e84731e3"
},
"downloads": -1,
"filename": "whatsloon-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4da3826e1baea8339b4b71134e59c555",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.6",
"size": 39107,
"upload_time": "2025-07-27T07:34:55",
"upload_time_iso_8601": "2025-07-27T07:34:55.005143Z",
"url": "https://files.pythonhosted.org/packages/b6/c3/f347fb88cdce3e042d5580abe82fc1ddc58438dd521d9d015f927242e795/whatsloon-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "82634762d57a5a3fb6650ca8827e5858df22665766cf1b9fe5e5617d1fb8d698",
"md5": "57e6864bbbc666977457f3abc386a57f",
"sha256": "f0e896435c7b0191e6b20bb64d7a4ae72820adfae87c965a9acdac0d9d13f1a9"
},
"downloads": -1,
"filename": "whatsloon-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "57e6864bbbc666977457f3abc386a57f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.6",
"size": 31849,
"upload_time": "2025-07-27T07:34:56",
"upload_time_iso_8601": "2025-07-27T07:34:56.134552Z",
"url": "https://files.pythonhosted.org/packages/82/63/4762d57a5a3fb6650ca8827e5858df22665766cf1b9fe5e5617d1fb8d698/whatsloon-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 07:34:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maharanasarkar",
"github_project": "whatsloon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "whatsloon"
}
JSON
