Meta Cloud API Whatsapp Integration

apps/channels/datamodels.py

@@ -197,6 +197,10 @@ def parse(message_data: dict):
         )
 
 
+# Meta Cloud API uses the same WhatsApp Business API message format as Turn.io
+MetaCloudAPIMessage = TurnWhatsappMessage
+
+
 class FacebookMessage(BaseMessage):
     """
     A wrapper class for user messages coming from Facebook

apps/channels/forms.py

@@ -233,15 +233,32 @@ class WhatsappChannelForm(WebhookUrlFormBase):
     def clean_number(self):
         try:
             number_obj = phonenumbers.parse(self.cleaned_data["number"])
-            number = phonenumbers.format_number(number_obj, phonenumbers.PhoneNumberFormat.E164)
-            service = self.messaging_provider.get_messaging_service()
+            return phonenumbers.format_number(number_obj, phonenumbers.PhoneNumberFormat.E164)
+        except phonenumbers.NumberParseException:
+            raise forms.ValidationError("Enter a valid phone number (e.g. +12125552368).") from None
+
+    def clean(self):
+        cleaned_data = super().clean()
+        number = cleaned_data.get("number")
+        if not number or not self.messaging_provider:
+            return cleaned_data
+
+        service = self.messaging_provider.get_messaging_service()
+        try:
             if not service.is_valid_number(number):
                 self.warning_message = (
                     f"{number} was not found at the provider. Please make sure it is there before proceeding"
                 )
-            return number
-        except phonenumbers.NumberParseException:
-            raise forms.ValidationError("Enter a valid phone number (e.g. +12125552368).") from None
+        except ValueError as e:
+            self.add_error("number", str(e))
+            return cleaned_data
+        except Exception:
+            self.add_error("number", "Could not validate this number right now. Please try again.")
+            return cleaned_data
+
+        if self.messaging_provider.type == MessagingProviderType.meta_cloud_api:
+            cleaned_data["phone_number_id"] = service.get_phone_number_id()
+        return cleaned_data
 
 
 class SureAdhereChannelForm(WebhookUrlFormBase):

apps/channels/meta_webhook.py

@@ -0,0 +1,60 @@
+import hashlib
+import hmac
+
+from django.http import HttpResponse, HttpResponseBadRequest
+from django.utils.crypto import constant_time_compare
+
+from apps.service_providers.models import MessagingProvider, MessagingProviderType
+
+
+def extract_message_values(data: dict) -> list[dict]:
+    """Extract value dicts that contain messages from Meta webhook payload.
+
+    See https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint/
+
+    See https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview for an
+    example of the payload
+    """
+
+    values = []
+    for entry in data.get("entry", []):
+        for change in entry.get("changes", []):
+            value = change.get("value", {})
+            if value.get("messages") and value.get("metadata", {}).get("phone_number_id"):
+                values.append(value)
+    return values
+
+
+def verify_webhook(request) -> HttpResponse:
+    """Handle the Meta webhook GET verification handshake."""
+    mode = request.GET.get("hub.mode")
+    token = request.GET.get("hub.verify_token")
+    challenge = request.GET.get("hub.challenge")
+
+    if mode != "subscribe" or not token or not challenge:
+        return HttpResponseBadRequest("Verification failed.")
+
+    token_hash = hashlib.sha256(token.encode()).hexdigest()
+    exists = MessagingProvider.objects.filter(
+        type=MessagingProviderType.meta_cloud_api,
+        extra_data__verify_token_hash=token_hash,
+    ).exists()
+
+    if exists:
+        return HttpResponse(challenge, content_type="text/plain")
+
+    return HttpResponseBadRequest("Verification failed.")
+
+
+def verify_signature(payload: bytes, signature_header: str, app_secret: str) -> bool:
+    """Verify the X-Hub-Signature-256 header from Meta webhooks."""
+    if not signature_header.startswith("sha256=") or not app_secret:
+        return False
+
+    expected_signature = signature_header.removeprefix("sha256=")
+    computed = hmac.new(
+        app_secret.encode(),
+        payload,
+        hashlib.sha256,
+    ).hexdigest()
+    return constant_time_compare(computed, expected_signature)

apps/channels/models.py

@@ -241,6 +241,8 @@ def webhook_url(self) -> str:
             uri = reverse("channels:new_twilio_message")
         elif provider_type == MessagingProviderType.turnio:
             uri = reverse("channels:new_turn_message", kwargs={"experiment_id": self.experiment.public_id})
+        elif provider_type == MessagingProviderType.meta_cloud_api:
+            uri = reverse("channels:new_meta_cloud_api_message")
         elif provider_type == MessagingProviderType.sureadhere:
             uri = reverse(
                 "channels:new_sureadhere_message",

apps/channels/tasks.py

@@ -7,7 +7,14 @@
 from twilio.request_validator import RequestValidator
 
 from apps.channels.clients.connect_client import CommCareConnectClient, Message
-from apps.channels.datamodels import BaseMessage, SureAdhereMessage, TelegramMessage, TurnWhatsappMessage, TwilioMessage
+from apps.channels.datamodels import (
+    BaseMessage,
+    MetaCloudAPIMessage,
+    SureAdhereMessage,
+    TelegramMessage,
+    TurnWhatsappMessage,
+    TwilioMessage,
+)
 from apps.channels.models import ChannelPlatform, ExperimentChannel
 from apps.chat.channels import (
     ApiChannel,
@@ -174,11 +181,30 @@ def handle_commcare_connect_message(self, experiment_id: int, participant_data_i
 
 def get_experiment_channel(platform, **query_kwargs):
     query = get_experiment_channel_base_query(platform, **query_kwargs)
-    return query.select_related("experiment", "team").first()
+    return query.select_related("experiment", "team", "messaging_provider").first()
 
 
 def get_experiment_channel_base_query(platform, **query_kwargs):
     return ExperimentChannel.objects.filter(
         platform=platform,
         **query_kwargs,
     ).filter(experiment__is_archived=False)
+
+
+@shared_task(bind=True, base=TaskbadgerTask, ignore_result=True)
+def handle_meta_cloud_api_message(self, channel_id: int, team_slug: str, message_data: dict):
+    message = MetaCloudAPIMessage.parse(message_data)
+    experiment_channel = (
+        ExperimentChannel.objects.filter(
+            id=channel_id,
+            experiment__is_archived=False,
+        )
+        .select_related("experiment", "team", "messaging_provider")
+        .first()
+    )
+    if not experiment_channel:
+        log.info("No experiment channel found for channel_id=%s team=%s", channel_id, team_slug)
+        return
+    channel = WhatsappChannel(experiment_channel.experiment.default_version, experiment_channel)
+    update_taskbadger_data(self, channel, message)
+    channel.new_user_message(message)

apps/channels/tests/test_forms.py

@@ -81,6 +81,64 @@ def test_whatsapp_form_checks_number(
         )
 
 
+@pytest.mark.django_db()
+@patch("apps.channels.forms.ExtraFormBase.messaging_provider", new_callable=PropertyMock)
+@patch("apps.service_providers.messaging_service.httpx.get")
+def test_whatsapp_form_meta_cloud_api_resolves_phone_number_id(mock_httpx_get, messaging_provider, experiment):
+    """Test that the phone number ID is fetched from Meta API and stored in extra_data"""
+    import httpx
+
+    mock_httpx_get.return_value = httpx.Response(
+        200,
+        json={
+            "data": [
+                {"id": "12345", "display_phone_number": "+1 (212) 555-2368"},
+            ]
+        },
+        request=httpx.Request("GET", "https://test"),
+    )
+    provider = MessagingProviderFactory.create(
+        type=MessagingProviderType.meta_cloud_api,
+        config={"access_token": "test_token", "business_id": "biz_123"},
+    )
+    messaging_provider.return_value = provider
+
+    form = WhatsappChannelForm(
+        experiment=experiment, data={"number": "+12125552368", "messaging_provider": provider.id}
+    )
+    assert form.is_valid(), f"Form errors: {form.errors}"
+
+    # ChannelFormWrapper.save() passes extra_form.cleaned_data as channel.extra_data,
+    # so phone_number_id should be in cleaned_data directly.
+    assert form.cleaned_data["phone_number_id"] == "12345"
+    assert form.cleaned_data["number"] == "+12125552368"
+
+
+@pytest.mark.django_db()
+@patch("apps.channels.forms.ExtraFormBase.messaging_provider", new_callable=PropertyMock)
+@patch("apps.service_providers.messaging_service.httpx.get")
+def test_whatsapp_form_meta_cloud_api_rejects_unknown_number(mock_httpx_get, messaging_provider, experiment):
+    """Test that form validation fails when the phone number is not found in the Meta Business Account"""
+    import httpx
+
+    mock_httpx_get.return_value = httpx.Response(
+        200,
+        json={"data": []},
+        request=httpx.Request("GET", "https://test"),
+    )
+    provider = MessagingProviderFactory.create(
+        type=MessagingProviderType.meta_cloud_api,
+        config={"access_token": "test_token", "business_id": "biz_123"},
+    )
+    messaging_provider.return_value = provider
+
+    form = WhatsappChannelForm(
+        experiment=experiment, data={"number": "+12125552368", "messaging_provider": provider.id}
+    )
+    assert not form.is_valid()
+    assert "was not found in the WhatsApp Business Account" in form.errors["number"][0]
+
+
 # Slack channel keyword uniqueness tests
 @pytest.mark.django_db()
 def test_slack_channel_new_with_keywords_succeeds(team_with_users, experiment):