whatsapp-python 4.2.0__tar.gz → 4.4.0__tar.gz

whatsapp_python-4.4.0/.github/workflows/python-publish.yml

@@ -0,0 +1,46 @@
+# Upload to PyPI when a GitHub Release is published.
+# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  # Re-run from Actions after workflow fixes (uses the selected branch/ref).
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deployment:
+    runs-on: ubuntu-latest
+    environment: publish
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade "twine>=7"
+          twine check dist/*
+
+      # hatchling emits Metadata-Version 2.5; Twine 6 rejects it.
+      # gh-action-pypi-publish v1.14.2+ ships Twine 7 which accepts 2.5.
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@v1.14.3
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

whatsapp_python-4.4.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# How to contribute
+
+First of all, thank you for considering contributing to this project! It's people like you that make it a reality and help me keep it alive and updated.
+
+If you are unsure about anything, feel free to ask me. I am here to help you.
+
+Any bug report, feature request, or code contribution is welcome. Here are some guidelines to help you get started.
+
+## Submitting changes
+
+Please open a [Pull Request](https://github.com/filipporomani/whatsapp-python/pull/new/master) with a list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). Make sure, if possible, that all of your commits are atomic (one feature per commit).
+
+Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
+
+    $ git commit -m "feat: a brief summary of the commit
+    > 
+    > A paragraph describing what changed and its impact."
+
+
+  * This is an open source software. Keep in mind to make your code readable to others. It's sort of like driving a car: perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth as possible.
+
+There isn't any other particular guideline, feel free to contribute!

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/LICENSE

@@ -1,7 +1,7 @@
                     GNU AFFERO GENERAL PUBLIC LICENSE
                        Version 3, 19 November 2007
 
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Copyright © Filippo Romani
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.5
 Name: whatsapp-python
-Version: 4.2.0
+Version: 4.4.0
 Summary: Open source Python wrapper for the WhatsApp Cloud API
 Project-URL: Homepage, https://github.com/filipporomani/whatsapp-python
 Project-URL: Docs, https://github.com/filipporomani/whatsapp-python/wiki
@@ -8,6 +8,7 @@ Project-URL: Issues Reporting, https://github.com/filipporomani/whatsapp-python/
 Project-URL: Download, https://github.com/filipporomani/whatsapp-python/releases/latest
 Project-URL: Changelog, https://github.com/filipporomani/whatsapp-python/releases
 Author-email: Filippo Romani <mail@filipporomani.it>
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Customer Service
 Classifier: Intended Audience :: Developers
@@ -26,18 +27,23 @@ Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: aiohttp
 Requires-Dist: beautifulsoup4
 Requires-Dist: fastapi
 Requires-Dist: python-dotenv
 Requires-Dist: requests
 Requires-Dist: requests-toolbelt
 Requires-Dist: uvicorn
+Provides-Extra: test
+Requires-Dist: httpx; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 <div align="center">
   <img src="https://gist.githubusercontent.com/boywithkeyboard/e8dc5b1810bd29e1d70346ca11d7f09d/raw/7f7eeea482f5047e62944e54182aa26c89cc299a/whatsapp_python.svg" alt="logo" width="128px">
   <h1>whatsapp-python</h1>
-  <p>Free, open-source Python wrapper for the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a>.<br>Forked from <a href="https://github.com/Neurotech-HQ/heyoo">Neurotech-HQ/heyoo</a>.</p>
+  <p>Free, open-source Python wrapper for the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a>.<br>Forked from <a href="https://github.com/Neurotech-HQ/heyoo">Neurotech-HQ/heyoo</a>.
+  </p>
   <img src="https://img.shields.io/badge/made%20in-italy-008751.svg?style=flat-square" alt="Made in Italy">
   <a href="https://pepy.tech/project/whatsapp-python"><img src="https://static.pepy.tech/personalized-badge/whatsapp-python?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads" alt="Downloads"></a>
   <a href="https://pepy.tech/project/whatsapp-python"><img src="https://pepy.tech/badge/whatsapp-python/month" alt="Monthly Downloads"></a>
@@ -69,32 +75,31 @@ hatch shell
 
 Documentation is available in the [wiki](https://github.com/filipporomani/whatsapp/wiki) here on GitHub.
 
-## Why choose this library?
+### Key features:
+- Modern interface using `async` and `await`
+- Full support for Graph API error handling
+- Optimized for high-load workflows using asyncronous programming
+- Always up to date
+- All of the WhatsApp Business chat UI features supported
 
-The main reason why I decided to fork the original `heyoo` library is that it uses an old version of the API, it's missing many and it's not mantained anymore.
 
-In this fork I added app events (to listen to incoming messages) and implemented an easier way to send/receive messages and media by using the `Message` object.
-The API version is always up to date and I'm always adding new features and fixing bugs.
-
-I also added a full asyncronous version of the library, which is faster and more efficient than the syncronous one.
-
-I fixed some bugs and added many features, however the library can still be improved.
-
-### Supported features:
-
-- Listening to events (messages, media, etc.)
-- Async version available
+### All features
+- Event listening (incoming messages)
+- Asyncronous API calls
+- Error handling
 - Sending messages
 - Sending messages from different numbers individually
-- Marking messages as read
+- Marking messages as read (optional typing indicator)
 - Replying to messages
 - Reacting to messages
-- Sending Media (images, audio, video and documents)
-- Sending location
-- Sending interactive buttons
+- Sending medias (images, audios/voice notes, videos, links and documents)
+- Sending location and location-request prompts
+- Sending interactive buttons, lists, and CTA URL buttons
 - Sending template messages
-- Parsing messages and media received
+- Parsing messages and media received (including reactions)
 - Sending contacts
+- Uploading media to the Facebook cloud
+- Automatic Graph API version discovery with a safe fallback (`v27.0`)
 
 ## Obtaining the WhatsApp API credentials
 

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/README.md

@@ -1,7 +1,8 @@
 <div align="center">
   <img src="https://gist.githubusercontent.com/boywithkeyboard/e8dc5b1810bd29e1d70346ca11d7f09d/raw/7f7eeea482f5047e62944e54182aa26c89cc299a/whatsapp_python.svg" alt="logo" width="128px">
   <h1>whatsapp-python</h1>
-  <p>Free, open-source Python wrapper for the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a>.<br>Forked from <a href="https://github.com/Neurotech-HQ/heyoo">Neurotech-HQ/heyoo</a>.</p>
+  <p>Free, open-source Python wrapper for the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a>.<br>Forked from <a href="https://github.com/Neurotech-HQ/heyoo">Neurotech-HQ/heyoo</a>.
+  </p>
   <img src="https://img.shields.io/badge/made%20in-italy-008751.svg?style=flat-square" alt="Made in Italy">
   <a href="https://pepy.tech/project/whatsapp-python"><img src="https://static.pepy.tech/personalized-badge/whatsapp-python?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads" alt="Downloads"></a>
   <a href="https://pepy.tech/project/whatsapp-python"><img src="https://pepy.tech/badge/whatsapp-python/month" alt="Monthly Downloads"></a>
@@ -33,32 +34,31 @@ hatch shell
 
 Documentation is available in the [wiki](https://github.com/filipporomani/whatsapp/wiki) here on GitHub.
 
-## Why choose this library?
+### Key features:
+- Modern interface using `async` and `await`
+- Full support for Graph API error handling
+- Optimized for high-load workflows using asyncronous programming
+- Always up to date
+- All of the WhatsApp Business chat UI features supported
 
-The main reason why I decided to fork the original `heyoo` library is that it uses an old version of the API, it's missing many and it's not mantained anymore.
 
-In this fork I added app events (to listen to incoming messages) and implemented an easier way to send/receive messages and media by using the `Message` object.
-The API version is always up to date and I'm always adding new features and fixing bugs.
-
-I also added a full asyncronous version of the library, which is faster and more efficient than the syncronous one.
-
-I fixed some bugs and added many features, however the library can still be improved.
-
-### Supported features:
-
-- Listening to events (messages, media, etc.)
-- Async version available
+### All features
+- Event listening (incoming messages)
+- Asyncronous API calls
+- Error handling
 - Sending messages
 - Sending messages from different numbers individually
-- Marking messages as read
+- Marking messages as read (optional typing indicator)
 - Replying to messages
 - Reacting to messages
-- Sending Media (images, audio, video and documents)
-- Sending location
-- Sending interactive buttons
+- Sending medias (images, audios/voice notes, videos, links and documents)
+- Sending location and location-request prompts
+- Sending interactive buttons, lists, and CTA URL buttons
 - Sending template messages
-- Parsing messages and media received
+- Parsing messages and media received (including reactions)
 - Sending contacts
+- Uploading media to the Facebook cloud
+- Automatic Graph API version discovery with a safe fallback (`v27.0`)
 
 ## Obtaining the WhatsApp API credentials
 

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/reply_to_message_obj.py

@@ -4,11 +4,11 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     data = {"your": "data"}
 
-    msg = Message(data=data, instance=messenger,sender=1)
+    msg = Message(data=data, instance=messenger, sender=1)
     msg.reply("lol")
 
     print(msg)

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_audio.py

@@ -4,13 +4,12 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_audio(
         audio="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
         recipient_id="255757xxxxxx",
-        sender=1
+        sender=1,
     )
 
     print(response)

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_button.py

@@ -4,8 +4,7 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_button(
         recipient_id="255757xxxxxx",
@@ -30,5 +29,5 @@ if __name__ == "__main__":
                 ],
             },
         },
-        sender=1
+        sender=1,
     )

whatsapp_python-4.4.0/examples/sending_button_async.py

@@ -0,0 +1,40 @@
+from os import getenv
+from whatsapp import AsyncWhatsApp, AsyncMessage
+import asyncio
+from dotenv import load_dotenv
+
+if __name__ == "__main__":
+    load_dotenv()
+    messenger = AsyncWhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
+
+    async def run_test():
+        response = await messenger.send_button(
+            recipient_id="255757xxxxxx",
+            button={
+                "header": "Header Testing",
+                "body": "Body Testing",
+                "footer": "Footer Testing",
+                "action": {
+                    "button": "Button Testing",
+                    "sections": [
+                        {
+                            "title": "iBank",
+                            "rows": [
+                                {"id": "row 1", "title": "Send Money", "description": ""},
+                                {
+                                    "id": "row 2",
+                                    "title": "Withdraw money",
+                                    "description": "",
+                                },
+                            ],
+                        }
+                    ],
+                },
+            },
+            sender=1,
+        )
+        while not response.done():
+            await asyncio.sleep(.1)
+        print(response.result())
+        
+    asyncio.run(run_test())

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_document.py

@@ -5,13 +5,12 @@ from dotenv import load_dotenv
 if __name__ == "__main__":
     load_dotenv()
 
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_document(
         document="http://www.africau.edu/images/default/sample.pdf",
         recipient_id="255757294146",
-        sender=1
+        sender=1,
     )
 
     print(response)

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_image.py

@@ -1,3 +1,6 @@
+
+
+
 from os import getenv
 from whatsapp import WhatsApp
 from dotenv import load_dotenv

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_location.py

@@ -4,8 +4,7 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_location(
         lat=1.29,
@@ -13,7 +12,7 @@ if __name__ == "__main__":
         name="Singapore",
         address="Singapore",
         recipient_id="255757294146",
-        sender=1
+        sender=1,
     )
 
     print(response)

whatsapp_python-4.4.0/examples/sending_message.py

@@ -0,0 +1,14 @@
+from os import getenv
+from whatsapp import WhatsApp, Message
+from dotenv import load_dotenv
+
+if __name__ == "__main__":
+    load_dotenv()
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
+
+    msg = Message(
+        instance=messenger, content="Hello World!", to="919999999999", sender=1
+    )
+    response = msg.send()
+
+    print(response)

whatsapp_python-4.4.0/examples/sending_message_async.py

@@ -0,0 +1,19 @@
+from os import getenv
+from whatsapp import AsyncWhatsApp, AsyncMessage
+import asyncio
+from dotenv import load_dotenv
+
+if __name__ == "__main__":
+    load_dotenv()
+    messenger = AsyncWhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
+
+    msg = AsyncMessage(
+        instance=messenger, content="Hello World!", to="919999999999", sender=1
+    )
+    async def run_test():
+        response = await msg.send()
+        while not response.done():
+            await asyncio.sleep(.1)
+        print(response.result())
+        
+    asyncio.run(run_test())

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_template_message.py

@@ -4,10 +4,10 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_template(
-        "hello_world", "255757xxxxxx", components=[], lang="en_US", sender=1)
+        "hello_world", "255757xxxxxx", components=[], lang="en_US", sender=1
+    )
 
     print(response)

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/sending_video.py

@@ -4,13 +4,12 @@ from dotenv import load_dotenv
 
 if __name__ == "__main__":
     load_dotenv()
-    messenger = WhatsApp(token=getenv("TOKEN"),
-                         phone_number_id={1:"1234", 2: "5678"})
+    messenger = WhatsApp(token=getenv("TOKEN"), phone_number_id={1: "1234", 2: "5678"})
 
     response = messenger.send_video(
         video="https://www.youtube.com/watch?v=K4TOrB7at0Y",
         recipient_id="255757xxxxxx",
-        sender=1
+        sender=1,
     )
 
     print(response)

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/examples/standalone_hook.py

@@ -9,8 +9,7 @@ app = Flask(__name__)
 
 # Load .env file
 load_dotenv("../.env")
-messenger = WhatsApp(os.getenv("TOKEN"),
-                     phone_number_id=os.getenv("ID"))
+messenger = WhatsApp(os.getenv("TOKEN"), phone_number_id=os.getenv("ID"))
 VERIFY_TOKEN = "30cca545-3838-48b2-80a7-9e43b1ae8ce4"
 
 # Logging
@@ -51,8 +50,7 @@ def hook():
                 message = msg.content
                 name = msg.name
                 logging.info("Message: %s", message)
-                m = Message(instance=messenger, to=mobile,
-                            content="Hello World")
+                m = Message(instance=messenger, to=mobile, content="Hello World")
                 m.send()
 
             elif message_type == "interactive":
@@ -62,8 +60,7 @@ def hook():
                 interactive_type = message_response.get("type")
                 message_id = message_response[interactive_type]["id"]
                 message_text = message_response[interactive_type]["title"]
-                logging.info(
-                    f"Interactive Message; {message_id}: {message_text}")
+                logging.info(f"Interactive Message; {message_id}: {message_text}")
 
             elif message_type == "location":
                 message_location = msg.location
@@ -71,8 +68,7 @@ def hook():
                     return Response(status=400)
                 message_latitude = message_location["latitude"]
                 message_longitude = message_location["longitude"]
-                logging.info("Location: %s, %s",
-                             message_latitude, message_longitude)
+                logging.info("Location: %s, %s", message_latitude, message_longitude)
 
             elif message_type == "image":
                 image = msg.image

{whatsapp_python-4.2.0 → whatsapp_python-4.4.0}/pyproject.toml

@@ -31,7 +31,15 @@ classifiers=[
 dynamic = [
   "version"
 ]
-dependencies = ["fastapi", "uvicorn", "requests_toolbelt", "requests", "python-dotenv", "BeautifulSoup4"]
+dependencies = [
+    "fastapi",
+    "uvicorn",
+    "requests",
+    "requests_toolbelt",
+    "aiohttp",
+    "python-dotenv",
+    "beautifulsoup4",
+]
 
 [project.urls]
 Homepage = "https://github.com/filipporomani/whatsapp-python"
@@ -41,9 +49,17 @@ Download = "https://github.com/filipporomani/whatsapp-python/releases/latest"
 Changelog = "https://github.com/filipporomani/whatsapp-python/releases"
 
 
+[project.optional-dependencies]
+test = ["pytest>=8.0", "httpx"]
+
 [tool.hatch.version]
 path = "whatsapp/constants.py"
 variable = "VERSION"
 
 [tool.hatch.build.targets.wheel]
-packages = ["whatsapp"]
+packages = ["whatsapp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-q"

whatsapp_python-4.4.0/tests/manual/README.md

@@ -0,0 +1,15 @@
+# Manual / live API smoke tests
+
+These scripts call the real WhatsApp Cloud API and require environment variables:
+
+- `GRAPH_API_TOKEN`
+- `TEST_PHONE_NUMBER_ID`
+- `DEST_PHONE_NUMBER`
+- `TEST_IMAGE_PATH` (async upload smoke only)
+
+Run from the repo root after exporting those values:
+
+```bash
+python3 tests/manual/sync_smoke.py
+python3 tests/manual/async_smoke.py
+```