whatsapp-python 4.3.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.3.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.3.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.3.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
@@ -27,12 +28,15 @@ Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: aiohttp
-Requires-Dist: asyncio
 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">
@@ -76,24 +80,26 @@ Documentation is available in the [wiki](https://github.com/filipporomani/whatsa
 - Full support for Graph API error handling
 - Optimized for high-load workflows using asyncronous programming
 - Always up to date
-- All of the WhatsApp chat UI features supported
+- All of the WhatsApp Business chat UI features supported
 
 
 ### All features
-- Event listener (incoming messages)
-- Async ready
+- 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 medias (images, audios, videos, links 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.3.0 → whatsapp_python-4.4.0}/README.md

@@ -39,24 +39,26 @@ Documentation is available in the [wiki](https://github.com/filipporomani/whatsa
 - Full support for Graph API error handling
 - Optimized for high-load workflows using asyncronous programming
 - Always up to date
-- All of the WhatsApp chat UI features supported
+- All of the WhatsApp Business chat UI features supported
 
 
 ### All features
-- Event listener (incoming messages)
-- Async ready
+- 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 medias (images, audios, videos, links 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.3.0 → whatsapp_python-4.4.0}/pyproject.toml

@@ -31,7 +31,15 @@ classifiers=[
 dynamic = [
   "version"
 ]
-dependencies = ["fastapi", "uvicorn", "requests_toolbelt", "asyncio", "aiohttp", "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
+```

whatsapp_python-4.4.0/tests/test_client.py

@@ -0,0 +1,241 @@
+import json
+from unittest.mock import Mock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from whatsapp import AsyncMessage, AsyncWhatsApp, Message, WhatsApp
+from whatsapp.errors import InvalidParameterException
+
+
+def _make_client(cls=WhatsApp, **overrides):
+    kwargs = {
+        "token": "test-token",
+        "phone_number_id": {1: "123456789"},
+        "update_check": False,
+        "version": "v27.0",
+        "verify_token": "verify-me",
+        "logger": False,
+        "debug": False,
+    }
+    kwargs.update(overrides)
+    with patch("whatsapp.graph_api.requests.get") as discover:
+        discover.side_effect = AssertionError("should not discover for pinned version")
+        return cls(**kwargs)
+
+
+def test_init_requires_dict_phone_number_id():
+    with pytest.raises(ValueError, match="dictionary"):
+        WhatsApp(token="x", phone_number_id="123", update_check=False, version="v27.0")
+
+
+def test_pinned_version_sets_urls():
+    app = _make_client()
+    assert app.LATEST == "v27.0"
+    assert app.base_url == "https://graph.facebook.com/v27.0"
+    assert app.url == "https://graph.facebook.com/v27.0/123456789/messages"
+    assert app.VERSION == "4.4.0"
+
+
+def test_create_message_and_send_payload():
+    app = _make_client()
+    msg = app.create_message(to="15550001111", content="hi there")
+    assert isinstance(msg, Message)
+
+    response = Mock()
+    response.status_code = 200
+    response.json.return_value = {"messages": [{"id": "wamid.1"}]}
+    with patch("whatsapp.requests.post", return_value=response) as post:
+        result = msg.send(sender=1)
+        assert result["messages"][0]["id"] == "wamid.1"
+        args, kwargs = post.call_args
+        assert args[0] == "https://graph.facebook.com/v27.0/123456789/messages"
+        assert kwargs["json"]["text"]["body"] == "hi there"
+
+
+def test_mark_as_read_with_typing_indicator():
+    app = _make_client()
+    inbound = {
+        "entry": [
+            {
+                "changes": [
+                    {
+                        "field": "messages",
+                        "value": {
+                            "contacts": [
+                                {
+                                    "wa_id": "15551234567",
+                                    "profile": {"name": "Ada"},
+                                }
+                            ],
+                            "messages": [
+                                {
+                                    "from": "15551234567",
+                                    "id": "wamid.IN",
+                                    "timestamp": "1",
+                                    "type": "text",
+                                    "text": {"body": "ping"},
+                                }
+                            ],
+                        },
+                    }
+                ]
+            }
+        ]
+    }
+    msg = app.create_message(data=inbound)
+    response = Mock()
+    response.status_code = 200
+    response.json.return_value = {"success": True}
+    with patch("whatsapp.requests.post", return_value=response) as post:
+        assert msg.show_typing() == {"success": True}
+        payload = post.call_args.kwargs["json"]
+        assert payload == {
+            "messaging_product": "whatsapp",
+            "status": "read",
+            "message_id": "wamid.IN",
+            "typing_indicator": {"type": "text"},
+        }
+
+
+def test_send_cta_url_and_location_request_payloads():
+    app = _make_client()
+    response = Mock()
+    response.status_code = 200
+    response.json.return_value = {"messages": [{"id": "wamid.x"}]}
+
+    with patch("whatsapp.ext._buttons.requests.post", return_value=response) as post:
+        app.send_cta_url(
+            body="Open our site",
+            display_text="Visit",
+            url="https://example.com",
+            recipient_id="15550001111",
+            header="Hello",
+            footer="Thanks",
+            sender=1,
+        )
+        cta = post.call_args.kwargs["json"]["interactive"]
+        assert cta["type"] == "cta_url"
+        assert cta["action"]["parameters"]["url"] == "https://example.com"
+        assert cta["header"]["text"] == "Hello"
+
+        app.send_location_request(
+            body="Share your location",
+            recipient_id="15550001111",
+            sender=1,
+        )
+        location = post.call_args.kwargs["json"]["interactive"]
+        assert location["type"] == "location_request_message"
+        assert location["action"]["name"] == "send_location"
+
+
+def test_send_audio_voice_and_document_filename():
+    app = _make_client()
+    response = Mock()
+    response.status_code = 200
+    response.json.return_value = {"messages": [{"id": "wamid.media"}]}
+
+    with patch("whatsapp.ext._send_media.requests.post", return_value=response) as post:
+        app.send_audio("media-id", "15550001111", link=False, voice=True, sender=1)
+        audio = post.call_args.kwargs["json"]["audio"]
+        assert audio == {"id": "media-id", "voice": True}
+
+        app.send_document(
+            "https://example.com/a.pdf",
+            "15550001111",
+            caption="Invoice",
+            filename="invoice.pdf",
+            sender=1,
+        )
+        document = post.call_args.kwargs["json"]["document"]
+        assert document["filename"] == "invoice.pdf"
+        assert document["caption"] == "Invoice"
+        assert document["link"] == "https://example.com/a.pdf"
+
+
+def test_send_template_omits_null_components():
+    app = _make_client()
+    response = Mock()
+    response.status_code = 200
+    response.json.return_value = {"messages": [{"id": "wamid.t"}]}
+    with patch("whatsapp.ext._message.requests.post", return_value=response) as post:
+        app.send_template("hello_world", "15550001111", sender=1)
+        template = post.call_args.kwargs["json"]["template"]
+        assert template == {
+            "name": "hello_world",
+            "language": {"code": "en_US"},
+        }
+        assert "components" not in template
+
+
+def test_error_handle_raises_typed_exception():
+    app = _make_client(cls=AsyncWhatsApp)
+    with pytest.raises(InvalidParameterException):
+        app.handle(
+            {
+                "error": {
+                    "message": "Invalid parameter",
+                    "code": 100,
+                }
+            }
+        )
+
+
+def test_webhook_verification_and_message_dispatch():
+    app = _make_client()
+    received = {}
+
+    async def on_message(msg):
+        received["msg"] = msg
+
+    app.on_message(on_message)
+    client = TestClient(app.app)
+
+    ok = client.get("/", params={"hub.verify_token": "verify-me", "hub.challenge": "42"})
+    assert ok.status_code == 200
+    assert ok.json() == 42
+
+    bad = client.get("/", params={"hub.verify_token": "nope", "hub.challenge": "42"})
+    assert bad.status_code == 200
+    assert bad.json() == {"success": False}
+
+    payload = {
+        "entry": [
+            {
+                "changes": [
+                    {
+                        "field": "messages",
+                        "value": {
+                            "contacts": [
+                                {
+                                    "wa_id": "15551234567",
+                                    "profile": {"name": "Ada"},
+                                }
+                            ],
+                            "messages": [
+                                {
+                                    "from": "15551234567",
+                                    "id": "wamid.IN",
+                                    "timestamp": "1",
+                                    "type": "text",
+                                    "text": {"body": "ping"},
+                                }
+                            ],
+                        },
+                    }
+                ]
+            }
+        ]
+    }
+    posted = client.post("/", content=json.dumps(payload))
+    assert posted.status_code == 200
+    assert posted.json() == {"success": True}
+    assert isinstance(received["msg"], Message)
+    assert received["msg"].content == "ping"
+    assert received["msg"].sender == "15551234567"
+
+
+def test_async_client_creates_async_message():
+    app = _make_client(cls=AsyncWhatsApp)
+    msg = app.create_message(to="15550001111", content="async hi")
+    assert isinstance(msg, AsyncMessage)

whatsapp_python-4.4.0/tests/test_errors.py

@@ -0,0 +1,28 @@
+import pytest
+
+from whatsapp.errors import (
+    DisplayNameApprovalException,
+    Handle,
+    MarketingOptOutException,
+    TemplateClassificationLimitException,
+)
+
+
+@pytest.mark.parametrize(
+    "code,exc",
+    [
+        (131037, DisplayNameApprovalException),
+        (131050, MarketingOptOutException),
+        (131064, TemplateClassificationLimitException),
+    ],
+)
+def test_new_error_mappings(code, exc):
+    with pytest.raises(exc):
+        Handle({"error": {"message": "boom", "code": code}})
+
+
+def test_unknown_error_falls_back_to_handler():
+    from whatsapp.errors import Handler
+
+    with pytest.raises(Handler):
+        Handle({"error": {"message": "mystery", "code": 999999}})

whatsapp_python-4.4.0/tests/test_graph_api.py

@@ -0,0 +1,60 @@
+from unittest.mock import Mock, patch
+
+import pytest
+
+from whatsapp.constants import DEFAULT_GRAPH_API_VERSION
+from whatsapp.graph_api import (
+    normalize_graph_api_version,
+    resolve_graph_api_version,
+)
+
+
+def test_normalize_graph_api_version():
+    assert normalize_graph_api_version("v27.0") == "v27.0"
+    assert normalize_graph_api_version("27.0") == "v27.0"
+    assert normalize_graph_api_version(" latest ") == "latest"
+    with pytest.raises(ValueError):
+        normalize_graph_api_version("not-a-version")
+
+
+def test_resolve_explicit_version_skips_network():
+    with patch("whatsapp.graph_api.requests.get") as get:
+        assert resolve_graph_api_version("v25.0") == "v25.0"
+        get.assert_not_called()
+
+
+def test_resolve_latest_from_labeled_table():
+    html = """
+    <html><body>
+      <table><tr><td>The latest Graph API version is:</td><td>v27.0</td></tr></table>
+    </body></html>
+    """
+    response = Mock()
+    response.text = html
+    response.raise_for_status = Mock()
+    with patch("whatsapp.graph_api.requests.get", return_value=response) as get:
+        assert resolve_graph_api_version("latest") == "v27.0"
+        assert get.call_count == 1
+
+
+def test_resolve_latest_falls_back_when_pages_fail():
+    with patch(
+        "whatsapp.graph_api.requests.get", side_effect=RuntimeError("offline")
+    ):
+        assert resolve_graph_api_version("latest") == DEFAULT_GRAPH_API_VERSION
+
+
+def test_resolve_latest_from_version_list_when_label_missing():
+    html = """
+    <html><body>
+      <table>
+        <tr><td>v26.0</td><td>July 29, 2026</td><td>TBD</td></tr>
+        <tr><td>v25.0</td><td>February 18, 2026</td><td>TBD</td></tr>
+      </table>
+    </body></html>
+    """
+    response = Mock()
+    response.text = html
+    response.raise_for_status = Mock()
+    with patch("whatsapp.graph_api.requests.get", return_value=response):
+        assert resolve_graph_api_version("latest") == "v26.0"

whatsapp_python-4.4.0/tests/test_static_parsers.py

@@ -0,0 +1,115 @@
+from whatsapp.ext._static import (
+    changed_field,
+    get_author,
+    get_delivery,
+    get_interactive_response,
+    get_message,
+    get_message_id,
+    get_message_type,
+    get_mobile,
+    get_name,
+    get_reaction,
+    is_message,
+)
+
+
+SAMPLE_TEXT = {
+    "entry": [
+        {
+            "changes": [
+                {
+                    "field": "messages",
+                    "value": {
+                        "contacts": [
+                            {
+                                "wa_id": "15551234567",
+                                "profile": {"name": "Ada"},
+                            }
+                        ],
+                        "messages": [
+                            {
+                                "from": "15551234567",
+                                "id": "wamid.TEXT",
+                                "timestamp": "1700000000",
+                                "type": "text",
+                                "text": {"body": "hello"},
+                            }
+                        ],
+                    },
+                }
+            ]
+        }
+    ]
+}
+
+SAMPLE_REACTION = {
+    "entry": [
+        {
+            "changes": [
+                {
+                    "field": "messages",
+                    "value": {
+                        "messages": [
+                            {
+                                "from": "15551234567",
+                                "id": "wamid.REACT",
+                                "timestamp": "1700000001",
+                                "type": "reaction",
+                                "reaction": {
+                                    "message_id": "wamid.TEXT",
+                                    "emoji": "👍",
+                                },
+                            }
+                        ]
+                    },
+                }
+            ]
+        }
+    ]
+}
+
+SAMPLE_STATUS = {
+    "entry": [
+        {
+            "changes": [
+                {
+                    "field": "messages",
+                    "value": {
+                        "statuses": [
+                            {
+                                "id": "wamid.OUT",
+                                "status": "played",
+                                "timestamp": "1700000002",
+                            }
+                        ]
+                    },
+                }
+            ]
+        }
+    ]
+}
+
+
+def test_text_message_parsers():
+    assert is_message(SAMPLE_TEXT) is True
+    assert changed_field(SAMPLE_TEXT) == "messages"
+    assert get_mobile(SAMPLE_TEXT) == "15551234567"
+    assert get_name(SAMPLE_TEXT) == "Ada"
+    assert get_author(SAMPLE_TEXT) == "15551234567"
+    assert get_message(SAMPLE_TEXT) == "hello"
+    assert get_message_id(SAMPLE_TEXT) == "wamid.TEXT"
+    assert get_message_type(SAMPLE_TEXT) == "text"
+    assert get_interactive_response(SAMPLE_TEXT) is None
+
+
+def test_reaction_parser():
+    assert get_message_type(SAMPLE_REACTION) == "reaction"
+    assert get_reaction(SAMPLE_REACTION) == {
+        "message_id": "wamid.TEXT",
+        "emoji": "👍",
+    }
+
+
+def test_delivery_status_parser():
+    assert is_message(SAMPLE_STATUS) is False
+    assert get_delivery(SAMPLE_STATUS) == "played"