Merge pull request #10 from edx/zamir/VAN-1142/add_send_canvas_messag…

…e_method

feat: add method to send canvas message

CHANGELOG.rst

@@ -14,6 +14,10 @@ Change Log
 Unreleased
 ~~~~~~~~~~
 
+[0.1.5]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+feat: add send_canvas_message method
+
 [0.1.4]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 feat: add identify_users method

braze/__init__.py

@@ -2,4 +2,4 @@
 Python client for interacting with Braze APIs.
 """
 
-__version__ = '0.1.4'
+__version__ = '0.1.5'

braze/client.py

@@ -308,7 +308,7 @@ def send_campaign_message(
         https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns/
 
         Arguments:
-            campaign_id (dict): The campaign identifier, the campaign must
+            campaign_id (str): The campaign identifier, the campaign must
             be an API-triggered campaign (set up via delivery settings)
             emails (list): e.g. ['test1@example.com', 'test2@example.com']
             recipients (list): The recipients objects
@@ -347,3 +347,56 @@ def send_campaign_message(
             recipients.append(recipient)
 
         return self._post_request(message, BrazeAPIEndpoints.SEND_CAMPAIGN)
+
+    def send_canvas_message(
+        self,
+        canvas_id,
+        emails=None,
+        recipients=None,
+        canvas_entry_properties=None,
+    ):
+        """
+        Send a canvas message via API-triggered delivery.
+
+        https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_canvases/
+
+        Arguments:
+            canvas_id (str): The canvas identifier, the canvas must
+            be an API-triggered campaign (set up via delivery settings)
+            emails (list): e.g. ['test1@example.com', 'test2@example.com']
+            recipients (list): The recipients objects
+            canvas_entry_properties: Personalization key-value pairs that will
+            apply to all users
+        Returns:
+            response (dict): The response object
+        """
+        if not (emails or recipients):
+            msg = 'Bad arguments, please check that emails or recipients are non-empty.'
+            raise BrazeClientError(msg)
+
+        emails = emails or []
+        recipients = recipients or []
+
+        for email in emails:
+            external_user_id = self.get_braze_external_id(email)
+
+            recipient = {
+                'external_user_id': external_user_id,
+            }
+
+            if not external_user_id:
+                raise BrazeClientError(
+                    f'Braze user with email {email} was not found. Please pass in custom recipients '
+                    f'if you wish to send campaign messages to anonymous users.'
+                )
+
+            recipients.append(recipient)
+
+        message = {
+            'canvas_id': canvas_id,
+            'canvas_entry_properties': canvas_entry_properties or {},
+            'recipients': recipients,
+            'broadcast': False
+        }
+
+        return self._post_request(message, BrazeAPIEndpoints.SEND_CANVAS)

braze/constants.py

@@ -9,6 +9,7 @@ class BrazeAPIEndpoints:
     """
 
     SEND_CAMPAIGN = '/campaigns/trigger/send'
+    SEND_CANVAS = '/canvas/trigger/send'
     EXPORT_IDS = '/users/export/ids'
     SEND_MESSAGE = '/messages/send'
     NEW_ALIAS = '/users/alias/new'

tests/braze/test_client.py

@@ -29,6 +29,7 @@ class BrazeClientTests(TestCase):
     """
     BRAZE_URL = 'http://braze-api-url.com'
     CAMPAIGN_SEND_URL = BRAZE_URL + BrazeAPIEndpoints.SEND_CAMPAIGN
+    CANVAS_SEND_URL = BRAZE_URL + BrazeAPIEndpoints.SEND_CANVAS
     EXPORT_ID_URL = BRAZE_URL + BrazeAPIEndpoints.EXPORT_IDS
     MESSAGE_SEND_URL = BRAZE_URL + BrazeAPIEndpoints.SEND_MESSAGE
     NEW_ALIAS_URL = BRAZE_URL + BrazeAPIEndpoints.NEW_ALIAS
@@ -147,8 +148,6 @@ def test_track_user(self):
         """
         Tests a successful call to /users/track.
         """
-        client = self._get_braze_client()
-
         responses.add(
             responses.POST,
             self.USERS_TRACK_URL,
@@ -178,8 +177,6 @@ def test_track_user_batching(self):
         """
         Tests that calls to /users/track are batched correctly.
         """
-        client = self._get_braze_client()
-
         responses.add(
             responses.POST,
             self.USERS_TRACK_URL,
@@ -370,8 +367,6 @@ def test_send_email_user_not_found(self):
             status=201
         )
 
-        client = self._get_braze_client()
-
         with self.assertRaises(BrazeClientError):
             client = self._get_braze_client()
             client.send_email(
@@ -428,15 +423,68 @@ def test_send_campaign_message_user_not_found(self):
             status=201
         )
 
-        client = self._get_braze_client()
-
         with self.assertRaises(BrazeClientError):
             client = self._get_braze_client()
             client.send_campaign_message(
                 emails=['test@example.com'],
                 campaign_id='campaign_id'
             )
 
+    def test_send_canvas_message_bad_args(self):
+        """
+        Tests that arguments are validated.
+        """
+        client = self._get_braze_client()
+        with self.assertRaises(BrazeClientError):
+            client.send_canvas_message(canvas_id='1', emails=[], recipients=[])
+
+    @responses.activate
+    def test_send_canvas_message_success(self):
+        """
+        Tests a successful call to /canvas/trigger/send.
+        """
+        responses.add(
+            responses.POST,
+            self.CANVAS_SEND_URL,
+            json={'dispatch_id': 'dispatch_id', 'message': 'success'},
+            status=201
+        )
+
+        responses.add(
+            responses.POST,
+            self.EXPORT_ID_URL,
+            json={'users': [{'external_id': '1'}], 'message': 'success'},
+            status=201
+        )
+
+        client = self._get_braze_client()
+        response = client.send_canvas_message(
+            emails=['test@example.com'],
+            canvas_id='canvas_id'
+        )
+
+        assert len(responses.calls) == 2
+        self.assertEqual(response['dispatch_id'], 'dispatch_id')
+
+    @responses.activate
+    def test_send_canvas_message_user_not_found(self):
+        """
+        Tests that an error is thrown if braze user is not found.
+        """
+        responses.add(
+            responses.POST,
+            self.EXPORT_ID_URL,
+            json={'users': [], 'invalid_ids': ['1'], 'message': 'success'},
+            status=201
+        )
+
+        with self.assertRaises(BrazeClientError):
+            client = self._get_braze_client()
+            client.send_canvas_message(
+                emails=['test@example.com'],
+                canvas_id='canvas_id'
+            )
+
     @responses.activate
     def test_braze_bad_request_error(self):
         """