Support messaging over WhatsApp (foundation only)

.testenv

@@ -28,7 +28,7 @@ FLASK_RECAPTCHA_PRIVATE_KEY=6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe
 FLASK_RECAPTCHA_OPTIONS=""
 # Use hostaliases on supported platforms
 HOSTALIASES=${PWD}/HOSTALIASES
-# These settings should be customisable from a .env file (TODO)
+# These settings can be customised in .env.testing
 FLASK_SECRET_KEYS='["testkey"]'
 FLASK_LASTUSER_SECRET_KEYS='["testkey"]'
 FLASK_LASTUSER_COOKIE_DOMAIN='.funnel.test:3002'
@@ -45,6 +45,11 @@ FLASK_IMGEE_HOST='http://imgee.test:4500'
 FLASK_IMAGE_URL_DOMAINS='["images.example.com"]'
 FLASK_IMAGE_URL_SCHEMES='["https"]'
 FLASK_SES_NOTIFICATION_TOPICS=null
+# WhatsApp config (These null entries disable production entries in .env)
+FLASK_WHATSAPP_PHONE_ID_META=null
+FLASK_WHATSAPP_TOKEN_META=null
+FLASK_WHATSAPP_PHONE_ID_HOSTED=null
+FLASK_WHATSAPP_TOKEN_HOSTED=null
 # Per app config
 APP_FUNNEL_SITE_ID=hasgeek-test
 APP_FUNNEL_SERVER_NAME=funnel.test:3002

funnel/models/account.py

@@ -1515,7 +1515,7 @@ class AccountEmail(EmailAddressMixin, BaseMixin, Model):
         'related': {'email', 'private', 'type'},
     }
 
-    def __init__(self, account: Account, **kwargs) -> None:
+    def __init__(self, *, account: Account, **kwargs) -> None:
         email = kwargs.pop('email', None)
         if email:
             kwargs['email_address'] = EmailAddress.add_for(account, email)
@@ -1701,13 +1701,11 @@ class AccountEmailClaim(EmailAddressMixin, BaseMixin, Model):
         'related': {'email', 'private', 'type'},
     }
 
-    def __init__(self, account: Account, **kwargs) -> None:
-        email = kwargs.pop('email', None)
-        if email:
-            kwargs['email_address'] = EmailAddress.add_for(account, email)
+    def __init__(self, account: Account, email: str, **kwargs) -> None:
+        kwargs['email_address'] = EmailAddress.add_for(account, email)
         super().__init__(account=account, **kwargs)
-        self.blake2b = hashlib.blake2b(
-            self.email.lower().encode(), digest_size=16
+        self.blake2b = hashlib.blake2b(  # self.email is not optional, so this ignore:
+            self.email.lower().encode(), digest_size=16  # type: ignore[union-attr]
         ).digest()
 
     def __repr__(self) -> str:
@@ -1887,7 +1885,7 @@ class AccountPhone(PhoneNumberMixin, BaseMixin, Model):
         'related': {'phone', 'private', 'type'},
     }
 
-    def __init__(self, account, **kwargs) -> None:
+    def __init__(self, *, account: Account, **kwargs) -> None:
         phone = kwargs.pop('phone', None)
         if phone:
             kwargs['phone_number'] = PhoneNumber.add_for(account, phone)
@@ -1902,7 +1900,7 @@ def __str__(self) -> str:
         return self.phone or ''
 
     @cached_property
-    def parsed(self) -> phonenumbers.PhoneNumber:
+    def parsed(self) -> phonenumbers.PhoneNumber | None:
         """Return parsed phone number using libphonenumbers."""
         return self.phone_number.parsed
 

funnel/models/notification.py

@@ -1427,7 +1427,7 @@ def main_notification_preferences(self) -> NotificationPreferences:
                 by_sms=True,
                 by_webpush=False,
                 by_telegram=False,
-                by_whatsapp=False,
+                by_whatsapp=True,
             )
             db.session.add(main)
             return main

funnel/models/phone_number.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, overload
 
 import base58
@@ -260,12 +261,14 @@ class PhoneNumber(BaseMixin, Model):
 
     #: The phone number, centrepiece of this model. Stored normalized in E164 format.
     #: Validated by the :func:`_validate_phone` event handler
-    number = sa.orm.mapped_column(sa.Unicode, nullable=True, unique=True)
+    number: Mapped[str | None] = sa.orm.mapped_column(
+        sa.Unicode, nullable=True, unique=True
+    )
 
     #: BLAKE2b 160-bit hash of :attr:`phone`. Kept permanently even if phone is
     #: removed. SQLAlchemy type LargeBinary maps to PostgreSQL BYTEA. Despite the name,
     #: we're only storing 20 bytes
-    blake2b160 = immutable(
+    blake2b160: Mapped[bytes] = immutable(
         sa.orm.mapped_column(
             sa.LargeBinary,
             sa.CheckConstraint(
@@ -282,37 +285,53 @@ class PhoneNumber(BaseMixin, Model):
     # device, we record distinct timestamps for last sent, delivery and failure.
 
     #: Cached state for whether this phone number is known to have SMS support
-    has_sms = sa.orm.mapped_column(sa.Boolean, nullable=True)
+    has_sms: Mapped[bool | None] = sa.orm.mapped_column(sa.Boolean, nullable=True)
     #: Timestamp at which this number was determined to be valid/invalid for SMS
-    has_sms_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    has_sms_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
     #: Cached state for whether this phone number is known to be on WhatsApp or not
-    has_wa = sa.orm.mapped_column(sa.Boolean, nullable=True)
+    has_wa: Mapped[bool | None] = sa.orm.mapped_column(sa.Boolean, nullable=True)
     #: Timestamp at which this number was tested for availability on WhatsApp
-    has_wa_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    has_wa_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
 
     #: Timestamp of last SMS sent
-    msg_sms_sent_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    msg_sms_sent_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
     #: Timestamp of last SMS delivered
-    msg_sms_delivered_at = sa.orm.mapped_column(
+    msg_sms_delivered_at: Mapped[datetime | None] = sa.orm.mapped_column(
         sa.TIMESTAMP(timezone=True), nullable=True
     )
     #: Timestamp of last SMS delivery failure
-    msg_sms_failed_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    msg_sms_failed_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
 
     #: Timestamp of last WA message sent
-    msg_wa_sent_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    msg_wa_sent_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
     #: Timestamp of last WA message delivered
-    msg_wa_delivered_at = sa.orm.mapped_column(
+    msg_wa_delivered_at: Mapped[datetime | None] = sa.orm.mapped_column(
         sa.TIMESTAMP(timezone=True), nullable=True
     )
     #: Timestamp of last WA message delivery failure
-    msg_wa_failed_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    msg_wa_failed_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
 
     #: Timestamp of last known recipient activity resulting from sent messages
-    active_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    active_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
 
     #: Is this phone number blocked from being used? :attr:`phone` should be null if so.
-    blocked_at = sa.orm.mapped_column(sa.TIMESTAMP(timezone=True), nullable=True)
+    blocked_at: Mapped[datetime | None] = sa.orm.mapped_column(
+        sa.TIMESTAMP(timezone=True), nullable=True
+    )
 
     __table_args__ = (
         # If `blocked_at` is not None, `number` and `has_*` must be None

funnel/transports/__init__.py

@@ -1,7 +1,5 @@
 """Transport layer for communication with users (email, SMS, others)."""
 
-from __future__ import annotations
-
 from . import email, sms, telegram, webpush, whatsapp
 from .base import init, platform_transports
 from .exc import (

funnel/transports/base.py

@@ -17,10 +17,12 @@
 }
 
 
-def init():
+def init() -> None:
     if app.config.get('MAIL_SERVER'):
         platform_transports['email'] = True
     if sms_init():
         platform_transports['sms'] = True
+    if app.config.get('WHATSAPP_TOKEN') and app.config.get('WHATSAPP_PHONE_ID'):
+        platform_transports['whatsapp'] = True
 
     # Other transports are not supported yet

funnel/transports/exc.py

@@ -1,9 +1,6 @@
 """Transport exceptions."""
 
 
-from __future__ import annotations
-
-
 class TransportError(Exception):
     """Base class for transport exceptions."""
 

funnel/transports/sms/__init__.py

@@ -1,7 +1,5 @@
 """SMS transport support."""
 # flake8: noqa
 
-from __future__ import annotations
-
 from .send import *
 from .template import *

funnel/transports/whatsapp/__init__.py

@@ -0,0 +1,5 @@
+"""WhatsApp transport support."""
+# flake8: noqa
+
+from .send import *
+from .template import *

funnel/transports/whatsapp/send.py

@@ -0,0 +1,161 @@
+"""Support functions for sending an WhatsApp messages."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import cast
+
+import phonenumbers
+import requests
+
+from baseframe import _
+
+from ... import app
+from ...models import PhoneNumber, PhoneNumberBlockedError, sa
+from ..exc import (
+    TransportConnectionError,
+    TransportRecipientError,
+    TransportTransactionError,
+)
+from .template import WhatsappTemplate
+
+
+@dataclass
+class WhatsappSender:
+    """A WhatsApp sender."""
+
+    requires_config: set[str]
+    func: Callable[[str, WhatsappTemplate], str]
+    init: Callable | None = None
+
+
+def get_phone_number(
+    phone: str | phonenumbers.PhoneNumber | PhoneNumber,
+) -> PhoneNumber:
+    if isinstance(phone, PhoneNumber):
+        if not phone.number:
+            raise TransportRecipientError(_("This phone number is not available"))
+        # TODO: Confirm this phone number is available on WhatsApp
+        return phone
+    try:
+        phone_number = PhoneNumber.add(phone)
+    except PhoneNumberBlockedError as exc:
+        raise TransportRecipientError(_("This phone number has been blocked")) from exc
+    if not phone_number.number:
+        # This should never happen as :meth:`PhoneNumber.add` will restore the number
+        raise TransportRecipientError(_("This phone number is not available"))
+    # TODO: Confirm this phone number is available on WhatsApp
+    return phone_number
+
+
+def send_via_meta(phone: str, message: WhatsappTemplate) -> str:
+    """
+    Send the WhatsApp message using Meta Cloud API.
+
+    :param phone: Phone number
+    :param message: Message to deliver to phone number
+    :return: Transaction id
+    """
+    phone_number = get_phone_number(phone)
+    sid = app.config['WHATSAPP_PHONE_ID']
+    token = app.config['WHATSAPP_TOKEN']
+    headers = {'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'}
+    payload = {
+        'messaging_product': 'whatsapp',
+        'recipient_type': 'individual',
+        'to': cast(str, phone_number.number).lstrip('+'),
+        'type': 'template',
+        'template': json.dumps(message.template),
+    }
+    try:
+        r = requests.post(
+            f'https://graph.facebook.com/v18.0/{sid}/messages',
+            timeout=30,
+            headers=headers,
+            data=payload,
+        )
+        if r.status_code == 200:
+            jsonresponse = r.json()
+            transactionid = jsonresponse['messages'][0].get('id')
+            phone_number.msg_wa_sent_at = sa.func.utcnow()
+            return transactionid
+        raise TransportTransactionError(_("WhatsApp API error"), r.status_code, r.text)
+    except requests.ConnectionError as exc:
+        raise TransportConnectionError(_("WhatsApp not reachable")) from exc
+
+
+def send_via_hosted(phone: str, message: WhatsappTemplate) -> str:
+    """
+    Send the WhatsApp message using On-Premise API.
+
+    :param phone: Phone number
+    :param message: Message to deliver to phone number
+    :return: Transaction id
+    """
+    phone_number = get_phone_number(phone)
+    sid = app.config['WHATSAPP_PHONE_ID']
+    token = app.config['WHATSAPP_TOKEN']
+    payload = {
+        'messaging_product': 'whatsapp',
+        'recipient_type': 'individual',
+        'to': cast(str, phone_number.number).lstrip('+'),
+        'type': 'template',
+        'body': str(message),
+    }
+    try:
+        r = requests.post(
+            f'https://graph.facebook.com/v18.0/{sid}/messages',
+            timeout=30,
+            auth=(token),  # FIXME: This is not a valid auth parameter
+            data=payload,
+        )
+        if r.status_code == 200:
+            jsonresponse = r.json()
+            transactionid = jsonresponse['messages'].get('id')
+            phone_number.msg_wa_sent_at = sa.func.utcnow()
+
+            return transactionid
+        raise TransportTransactionError(_("WhatsApp API error"), r.status_code, r.text)
+    except requests.ConnectionError as exc:
+        raise TransportConnectionError(_("WhatsApp not reachable")) from exc
+
+
+#: Supported senders (ordered by priority)
+sender_registry = [
+    WhatsappSender(
+        {'WHATSAPP_PHONE_ID_HOSTED', 'WHATSAPP_TOKEN_HOSTED'}, send_via_hosted
+    ),
+    WhatsappSender({'WHATSAPP_PHONE_ID_META', 'WHATSAPP_TOKEN_META'}, send_via_meta),
+]
+
+senders: list[Callable[[str, WhatsappTemplate], str]] = []
+
+
+def init() -> bool:
+    """Process available senders."""
+    for provider in sender_registry:
+        if all(app.config.get(var) for var in provider.requires_config):
+            senders.append(provider.func)
+            if provider.init:
+                provider.init()
+    return bool(senders)
+
+
+def send_whatsapp(
+    phone: str | phonenumbers.PhoneNumber | PhoneNumber,
+    message: WhatsappTemplate,
+) -> str:
+    """
+    Send a WhatsApp message to a given phone number and return a transaction id.
+
+    :param phone_number: Phone number
+    :param message: Message to deliver to phone number
+    :return: Transaction id
+    """
+    phone_number = get_phone_number(phone)
+    phone = cast(str, phone_number.number)
+    for sender in senders:
+        return sender(phone, message)
+    raise TransportRecipientError(_("No service provider available for this recipient"))