| Name | whatsplay JSON |
| Version |
1.4.6
JSON |
| download |
| home_page | None |
| Summary | A modern Python library for automating WhatsApp Web using Playwright |
| upload_time | 2025-07-25 15:49:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
whatsapp
automation
playwright
bot
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# WhatsPlay 🚀
Automatización avanzada de WhatsApp Web usando Playwright, Python y visión por computadora (OpenCV).
Permite interactuar con mensajes no leídos, autenticar mediante código QR, y realizar acciones complejas a través de eventos personalizados y filtrado de mensajes.
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://playwright.dev/)
## 🧠 Descripción
WhatsPlay es una librería modular diseñada para automatizar WhatsApp Web desde Python. La arquitectura está inspirada en el patrón de eventos y la separación de responsabilidades, con módulos independientes para autenticación, interacción con la UI, lógica base, y procesamiento de imágenes.
### ✨ Características principales
- **Automatización de navegador** con Playwright para máxima compatibilidad
- **extraccion automática de QR** sin intervención manual
- **Sistema de eventos personalizado** para manejo asíncrono de mensajes
- **Detección inteligente** de mensajes no leídos
- **Arquitectura modular** con separación clara de responsabilidades
## 🖼️ Arquitectura del sistema
La arquitectura modular permite:
- **Escalabilidad**: Fácil adición de nuevas funcionalidades
- **Mantenibilidad**: Componentes independientes y bien definidos
- **Testabilidad**: Cada módulo puede probarse por separado
- **Reutilización**: Los módulos pueden usarse en otros proyectos
## 🚀 Instalación
### Prerrequisitos
- Python 3.8 o superior
### Instalación desde PyPI
```bash
pip install whatsplay
```
## 🧪 Ejemplos de uso
### Uso básico
```python
from whatsplay import WhatsAppClient
# Crear cliente
client = WhatsAppClient()
# Handler para mensajes no leídos
@client.on_unread_chat
def handle_unread(chats):
print("chat name: ", chats[0]['name'])
success = await client.send_message(chats[0]['name'], "Hello!")
if success:
print("✅ Mensaje enviado con éxito")
else:
print("❌ Falló el envío del mensaje")
# Iniciar cliente
client.run()
```
## 📁 Estructura del proyecto
```
whatsplay/
├───examples
│ simple_example.py
│ test_client.py
│ test_main_loop.py
│
└───src
└───whatsplay
│ base_client.py
│ client.py
│ event.py
│ utils.py
│ wa_elements.py
│ __init__.py
│
├───auth
│ auth.py
│ local_profile_auth.py
│ no_auth.py
│ __init__.py
│
├───constants
│ locator.py
│ states.py
│
├───events
│ event_handler.py
│ event_types.py
│ __init__.py
│
└───filters
message_filter.py
__init__.py
```
## 📦 Dependencias
### Principales
- `playwright` - Automatización de navegador
- `opencv-python` - Procesamiento de imágenes (opcional)
- `pillow` - Manipulación de imágenes
- `requests` - Cliente HTTP
### Desarrollo
- `pytest` - Framework de testing
- `black` - Formateador de código
- `flake8` - Linter
- `mypy` - Verificación de tipos
## 🤝 Contribuciones
Las contribuciones son bienvenidas. Por favor:
1. Fork el repositorio
2. Crea una rama para tu feature (`git checkout -b feature/nueva-funcionalidad`)
3. Commit tus cambios (`git commit -am 'Agrega nueva funcionalidad'`)
4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abre un Pull Request
### Guías de desarrollo
- Sigue PEP 8 para el estilo de código
- Actualiza la documentación cuando sea necesario
- Usa type hints en todas las funciones públicas
## 📋 Roadmap
- [✅] Soporte para mensajes multimedia (imágenes, videos, audios)
- [ ] MessageFilter
## ❓ FAQ
**¿Es seguro usar WhatsPlay?**
WhatsPlay utiliza WhatsApp Web oficial, por lo que es tan seguro como usar WhatsApp en tu navegador.
**¿Puede ser detectado por WhatsApp?**
WhatsPlay simula interacciones humanas normales, pero siempre existe un riesgo al automatizar servicios web, hagalo bajo su propia responsabilidad.
**¿Funciona en servidores sin GUI?**
Sí, usando el modo headless de Playwright.
## 🐛 Reporte de bugs
Si encuentras un bug, por favor [abre un issue](https://github.com/markbus-ai/whatsplay/issues) incluyendo:
- Descripción del problema
- Pasos para reproducirlo
- Versión de Python y dependencias
- Logs relevantes
## 🤝 Agradecimientos
Este proyecto está inspirado y utiliza partes del código de [RedShot](https://github.com/akrentz6/RedShot), licenciado bajo la licencia Apache 2.0.
## 📄 Licencia
Este proyecto está licenciado bajo la **Licencia Apache 2.0**.
```
Copyright 2025 WhatsPlay
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
Consultá el archivo [LICENSE](./LICENSE) para más información.
---
<div align="center">
**[⭐ Star este proyecto](https://github.com/markbus-ai/whatsplay)** si te resulta útil
Made with ❤️ by [Markbusking]
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "whatsplay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "whatsapp, automation, playwright, bot",
"author": null,
"author_email": "Marcos Bustos <markbustos1912@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/66/b2/40288e13f846d09143e38c1fc41aad5be8966839484b584f30aa9e1c3714/whatsplay-1.4.6.tar.gz",
"platform": null,
"description": "# WhatsPlay \ud83d\ude80\n\nAutomatizaci\u00f3n avanzada de WhatsApp Web usando Playwright, Python y visi\u00f3n por computadora (OpenCV). \nPermite interactuar con mensajes no le\u00eddos, autenticar mediante c\u00f3digo QR, y realizar acciones complejas a trav\u00e9s de eventos personalizados y filtrado de mensajes.\n\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://www.python.org/downloads/)\n[](https://playwright.dev/)\n\n## \ud83e\udde0 Descripci\u00f3n\n\nWhatsPlay es una librer\u00eda modular dise\u00f1ada para automatizar WhatsApp Web desde Python. La arquitectura est\u00e1 inspirada en el patr\u00f3n de eventos y la separaci\u00f3n de responsabilidades, con m\u00f3dulos independientes para autenticaci\u00f3n, interacci\u00f3n con la UI, l\u00f3gica base, y procesamiento de im\u00e1genes.\n\n### \u2728 Caracter\u00edsticas principales\n\n- **Automatizaci\u00f3n de navegador** con Playwright para m\u00e1xima compatibilidad\n- **extraccion autom\u00e1tica de QR** sin intervenci\u00f3n manual\n- **Sistema de eventos personalizado** para manejo as\u00edncrono de mensajes\n- **Detecci\u00f3n inteligente** de mensajes no le\u00eddos\n- **Arquitectura modular** con separaci\u00f3n clara de responsabilidades\n\n## \ud83d\uddbc\ufe0f Arquitectura del sistema\n\n\n\nLa arquitectura modular permite:\n- **Escalabilidad**: F\u00e1cil adici\u00f3n de nuevas funcionalidades\n- **Mantenibilidad**: Componentes independientes y bien definidos \n- **Testabilidad**: Cada m\u00f3dulo puede probarse por separado\n- **Reutilizaci\u00f3n**: Los m\u00f3dulos pueden usarse en otros proyectos\n\n## \ud83d\ude80 Instalaci\u00f3n\n\n### Prerrequisitos\n\n- Python 3.8 o superior\n\n### Instalaci\u00f3n desde PyPI \n\n```bash\npip install whatsplay\n```\n\n## \ud83e\uddea Ejemplos de uso\n\n### Uso b\u00e1sico\n\n```python\nfrom whatsplay import WhatsAppClient\n\n# Crear cliente\nclient = WhatsAppClient()\n\n# Handler para mensajes no le\u00eddos\n@client.on_unread_chat\ndef handle_unread(chats):\n print(\"chat name: \", chats[0]['name'])\n success = await client.send_message(chats[0]['name'], \"Hello!\")\n if success:\n print(\"\u2705 Mensaje enviado con \u00e9xito\")\n else:\n print(\"\u274c Fall\u00f3 el env\u00edo del mensaje\")\n\n# Iniciar cliente\nclient.run()\n```\n\n## \ud83d\udcc1 Estructura del proyecto\n\n```\nwhatsplay/\n\u251c\u2500\u2500\u2500examples\n\u2502 simple_example.py\n\u2502 test_client.py\n\u2502 test_main_loop.py\n\u2502 \n\u2514\u2500\u2500\u2500src\n \u2514\u2500\u2500\u2500whatsplay\n \u2502 base_client.py\n \u2502 client.py\n \u2502 event.py\n \u2502 utils.py\n \u2502 wa_elements.py\n \u2502 __init__.py\n \u2502\n \u251c\u2500\u2500\u2500auth\n \u2502 auth.py\n \u2502 local_profile_auth.py\n \u2502 no_auth.py\n \u2502 __init__.py\n \u2502\n \u251c\u2500\u2500\u2500constants\n \u2502 locator.py\n \u2502 states.py\n \u2502\n \u251c\u2500\u2500\u2500events\n \u2502 event_handler.py\n \u2502 event_types.py\n \u2502 __init__.py\n \u2502\n \u2514\u2500\u2500\u2500filters\n message_filter.py\n __init__.py\n```\n\n## \ud83d\udce6 Dependencias\n\n### Principales\n- `playwright` - Automatizaci\u00f3n de navegador\n- `opencv-python` - Procesamiento de im\u00e1genes (opcional)\n- `pillow` - Manipulaci\u00f3n de im\u00e1genes\n- `requests` - Cliente HTTP\n\n### Desarrollo\n- `pytest` - Framework de testing\n- `black` - Formateador de c\u00f3digo\n- `flake8` - Linter\n- `mypy` - Verificaci\u00f3n de tipos\n\n\n## \ud83e\udd1d Contribuciones\n\nLas contribuciones son bienvenidas. Por favor:\n\n1. Fork el repositorio\n2. Crea una rama para tu feature (`git checkout -b feature/nueva-funcionalidad`)\n3. Commit tus cambios (`git commit -am 'Agrega nueva funcionalidad'`)\n4. Push a la rama (`git push origin feature/nueva-funcionalidad`)\n5. Abre un Pull Request\n\n### Gu\u00edas de desarrollo\n\n- Sigue PEP 8 para el estilo de c\u00f3digo\n- Actualiza la documentaci\u00f3n cuando sea necesario\n- Usa type hints en todas las funciones p\u00fablicas\n\n## \ud83d\udccb Roadmap\n\n- [\u2705] Soporte para mensajes multimedia (im\u00e1genes, videos, audios)\n- [ ] MessageFilter\n\n## \u2753 FAQ\n\n**\u00bfEs seguro usar WhatsPlay?**\nWhatsPlay utiliza WhatsApp Web oficial, por lo que es tan seguro como usar WhatsApp en tu navegador.\n\n**\u00bfPuede ser detectado por WhatsApp?**\nWhatsPlay simula interacciones humanas normales, pero siempre existe un riesgo al automatizar servicios web, hagalo bajo su propia responsabilidad.\n\n**\u00bfFunciona en servidores sin GUI?**\nS\u00ed, usando el modo headless de Playwright.\n\n## \ud83d\udc1b Reporte de bugs\n\nSi encuentras un bug, por favor [abre un issue](https://github.com/markbus-ai/whatsplay/issues) incluyendo:\n\n- Descripci\u00f3n del problema\n- Pasos para reproducirlo\n- Versi\u00f3n de Python y dependencias\n- Logs relevantes\n\n## \ud83e\udd1d Agradecimientos\n\nEste proyecto est\u00e1 inspirado y utiliza partes del c\u00f3digo de [RedShot](https://github.com/akrentz6/RedShot), licenciado bajo la licencia Apache 2.0.\n\n## \ud83d\udcc4 Licencia\n\nEste proyecto est\u00e1 licenciado bajo la **Licencia Apache 2.0**.\n\n```\nCopyright 2025 WhatsPlay\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\nConsult\u00e1 el archivo [LICENSE](./LICENSE) para m\u00e1s informaci\u00f3n.\n\n---\n\n<div align=\"center\">\n\n**[\u2b50 Star este proyecto](https://github.com/markbus-ai/whatsplay)** si te resulta \u00fatil\n\nMade with \u2764\ufe0f by [Markbusking]\n\n</div>\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern Python library for automating WhatsApp Web using Playwright",
"version": "1.4.6",
"project_urls": {
"Documentation": "https://github.com/markbus-ai/whatsplay#readme",
"Homepage": "https://github.com/markbus-ai/whatsplay",
"Issues": "https://github.com/markbus-ai/whatsplay/issues"
},
"split_keywords": [
"whatsapp",
" automation",
" playwright",
" bot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "59b11f041179a79465a22c1ecbfca4f435e9bf864482174c4ba23749efd4ef87",
"md5": "d8bd3458400e1ba092f51f447cecebd8",
"sha256": "2d04b36505914de1ad7904f1ed2c6fd51c6d89cd6573bb13eb8907576dc1c56f"
},
"downloads": -1,
"filename": "whatsplay-1.4.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8bd3458400e1ba092f51f447cecebd8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28801,
"upload_time": "2025-07-25T15:48:40",
"upload_time_iso_8601": "2025-07-25T15:48:40.707381Z",
"url": "https://files.pythonhosted.org/packages/59/b1/1f041179a79465a22c1ecbfca4f435e9bf864482174c4ba23749efd4ef87/whatsplay-1.4.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "66b240288e13f846d09143e38c1fc41aad5be8966839484b584f30aa9e1c3714",
"md5": "fc34a4fa13b7891a367971b0cfd3662f",
"sha256": "b4978140db7023bb71d61280474b81d29fec629e23de03746c620c63fa05b648"
},
"downloads": -1,
"filename": "whatsplay-1.4.6.tar.gz",
"has_sig": false,
"md5_digest": "fc34a4fa13b7891a367971b0cfd3662f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26769,
"upload_time": "2025-07-25T15:49:27",
"upload_time_iso_8601": "2025-07-25T15:49:27.722022Z",
"url": "https://files.pythonhosted.org/packages/66/b2/40288e13f846d09143e38c1fc41aad5be8966839484b584f30aa9e1c3714/whatsplay-1.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 15:49:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "markbus-ai",
"github_project": "whatsplay#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "whatsplay"
}
