Add support for specifying MessagingServiceSid in Twilio API requests

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 - Upgrade to cronsim 2.4
 - Update Signal notification template to include more data
 - Add Profile.deletion_scheduled_deleted field, and UI banner when it's set
+- Add support for specifying MessagingServiceSid when sending SMS and WA messages
 
 ### Bug Fixes
 - Fix a race condition when pinging and deleting checks at the same time

hc/api/tests/test_notify_sms.py

@@ -7,6 +7,7 @@ from datetime import timedelta as td
 from unittest.mock import patch
 
 from django.core import mail
+from django.test.utils import override_settings
 from django.utils.timezone import now
 
 from hc.api.models import Channel, Check, Notification
@@ -28,6 +29,7 @@ class NotifySmsTestCase(BaseTestCase):
         self.channel.save()
         self.channel.checks.add(self.check)
 
+    @override_settings(TWILIO_FROM="+000", TWILIO_MESSAGING_SERVICE_SID=None)
     @patch("hc.api.transports.curl.request")
     def test_it_works(self, mock_post):
         self.check.last_ping = now() - td(hours=2)
@@ -35,9 +37,9 @@ class NotifySmsTestCase(BaseTestCase):
 
         self.channel.notify(self.check)
 
-        args, kwargs = mock_post.call_args
-        payload = kwargs["data"]
+        payload = mock_post.call_args.kwargs["data"]
         self.assertEqual(payload["To"], "+1234567890")
+        self.assertEqual(payload["From"], "+000")
         self.assertNotIn("\xa0", payload["Body"])
         self.assertIn("is DOWN", payload["Body"])
 
@@ -49,6 +51,18 @@ class NotifySmsTestCase(BaseTestCase):
         self.profile.refresh_from_db()
         self.assertEqual(self.profile.sms_sent, 1)
 
+    @override_settings(TWILIO_MESSAGING_SERVICE_SID="dummy-sid")
+    @patch("hc.api.transports.curl.request")
+    def test_it_uses_messaging_service(self, mock_post):
+        self.check.last_ping = now() - td(hours=2)
+        mock_post.return_value.status_code = 200
+
+        self.channel.notify(self.check)
+
+        payload = mock_post.call_args.kwargs["data"]
+        self.assertEqual(payload["MessagingServiceSid"], "dummy-sid")
+        self.assertFalse("From" in payload)
+
     @patch("hc.api.transports.curl.request")
     def test_it_enforces_limit(self, mock_post):
         # At limit already:
@@ -90,8 +104,7 @@ class NotifySmsTestCase(BaseTestCase):
 
         self.channel.notify(self.check)
 
-        args, kwargs = mock_post.call_args
-        payload = kwargs["data"]
+        payload = mock_post.call_args.kwargs["data"]
         self.assertIn("Foo > Bar & Co", payload["Body"])
 
     @patch("hc.api.transports.curl.request")
@@ -113,6 +126,5 @@ class NotifySmsTestCase(BaseTestCase):
 
         self.channel.notify(self.check)
 
-        args, kwargs = mock_post.call_args
-        payload = kwargs["data"]
+        payload = mock_post.call_args.kwargs["data"]
         self.assertIn("is UP", payload["Body"])

hc/api/tests/test_notify_whatsapp.py

@@ -7,6 +7,7 @@ from datetime import timedelta as td
 from unittest.mock import patch
 
 from django.core import mail
+from django.test.utils import override_settings
 from django.utils.timezone import now
 
 from hc.api.models import Channel, Check, Notification
@@ -27,6 +28,7 @@ class NotifyWhatsAppTestCase(BaseTestCase):
         self.channel.save()
         self.channel.checks.add(self.check)
 
+    @override_settings(TWILIO_FROM="+000", TWILIO_MESSAGING_SERVICE_SID=None)
     @patch("hc.api.transports.curl.request")
     def test_it_works(self, mock_post):
         mock_post.return_value.status_code = 200
@@ -34,8 +36,8 @@ class NotifyWhatsAppTestCase(BaseTestCase):
 
         self.channel.notify(self.check)
 
-        args, kwargs = mock_post.call_args
-        payload = kwargs["data"]
+        payload = mock_post.call_args.kwargs["data"]
+        self.assertEqual(payload["From"], "whatsapp:+000")
         self.assertEqual(payload["To"], "whatsapp:+1234567890")
 
         n = Notification.objects.get()
@@ -46,6 +48,18 @@ class NotifyWhatsAppTestCase(BaseTestCase):
         self.profile.refresh_from_db()
         self.assertEqual(self.profile.sms_sent, 1)
 
+    @override_settings(TWILIO_MESSAGING_SERVICE_SID="dummy-sid")
+    @patch("hc.api.transports.curl.request")
+    def test_it_uses_messaging_service(self, mock_post):
+        mock_post.return_value.status_code = 200
+        self._setup_data()
+
+        self.channel.notify(self.check)
+
+        payload = mock_post.call_args.kwargs["data"]
+        self.assertEqual(payload["MessagingServiceSid"], "dummy-sid")
+        self.assertFalse("From" in payload)
+
     @patch("hc.api.transports.curl.request")
     def test_it_obeys_up_down_flags(self, mock_post):
         self._setup_data(notify_down=False)
@@ -87,6 +101,5 @@ class NotifyWhatsAppTestCase(BaseTestCase):
 
         self.channel.notify(self.check)
 
-        args, kwargs = mock_post.call_args
-        payload = kwargs["data"]
+        payload = mock_post.call_args.kwargs["data"]
         self.assertIn("Foo > Bar & Co", payload["Body"])

hc/api/transports.py

@@ -687,11 +687,15 @@ class Sms(HttpTransport):
         text = tmpl("sms_message.html", check=check, site_name=settings.SITE_NAME)
 
         data = {
-            "From": settings.TWILIO_FROM,
             "To": self.channel.phone_number,
             "Body": text,
         }
 
+        if settings.TWILIO_MESSAGING_SERVICE_SID:
+            data["MessagingServiceSid"] = settings.TWILIO_MESSAGING_SERVICE_SID
+        else:
+            data["From"] = settings.TWILIO_FROM
+
         if notification:
             data["StatusCallback"] = notification.status_url()
 
@@ -746,11 +750,15 @@ class WhatsApp(HttpTransport):
         text = tmpl("whatsapp_message.html", check=check, site_name=settings.SITE_NAME)
 
         data = {
-            "From": "whatsapp:%s" % settings.TWILIO_FROM,
-            "To": "whatsapp:%s" % self.channel.phone_number,
+            "To": f"whatsapp:{self.channel.phone_number}",
             "Body": text,
         }
 
+        if settings.TWILIO_MESSAGING_SERVICE_SID:
+            data["MessagingServiceSid"] = settings.TWILIO_MESSAGING_SERVICE_SID
+        else:
+            data["From"] = f"whatsapp:{settings.TWILIO_FROM}"
+
         if notification:
             data["StatusCallback"] = notification.status_url()
 

hc/settings.py

@@ -285,6 +285,7 @@ TELEGRAM_TOKEN = os.getenv("TELEGRAM_TOKEN")
 TWILIO_ACCOUNT = os.getenv("TWILIO_ACCOUNT")
 TWILIO_AUTH = os.getenv("TWILIO_AUTH")
 TWILIO_FROM = os.getenv("TWILIO_FROM")
+TWILIO_MESSAGING_SERVICE_SID = os.getenv("TWILIO_MESSAGING_SERVICE_SID")
 TWILIO_USE_WHATSAPP = envbool("TWILIO_USE_WHATSAPP", "False")
 
 # Trello

templates/docs/self_hosted_configuration.html-fragment

@@ -74,6 +74,7 @@ from environment variables. Below is a list of variables it reads and uses.</p>
 <li><a href="#TWILIO_ACCOUNT">TWILIO_ACCOUNT</a></li>
 <li><a href="#TWILIO_AUTH">TWILIO_AUTH</a></li>
 <li><a href="#TWILIO_FROM">TWILIO_FROM</a></li>
+<li><a href="#TWILIO_MESSAGING_SERVICE_SID">TWILIO_MESSAGING_SERVICE_SID</a></li>
 <li><a href="#TWILIO_USE_WHATSAPP">TWILIO_USE_WHATSAPP</a></li>
 <li><a href="#USE_PAYMENTS">USE_PAYMENTS</a></li>
 <li><a href="#VICTOROPS_ENABLED">VICTOROPS_ENABLED</a></li>
@@ -585,6 +586,20 @@ and as the caller for Call integrations.</p>
 <div class="highlight"><pre><span></span><code><span class="na">TWILIO_FROM</span><span class="o">=</span><span class="s">+15017122661</span>
 </code></pre></div>
 
+<h2 id="TWILIO_MESSAGING_SERVICE_SID"><code>TWILIO_MESSAGING_SERVICE_SID</code></h2>
+<p>Default: <code>None</code></p>
+<p>Optional, the Twilio Messaging Service SID for sending SMS and WhatsApp notifications.</p>
+<p>If <code>TWILIO_MESSAGING_SERVICE_SID</code> is specified, Healthchecks will include it in the
+"MessagingServiceSid" field when sending SMS and WhatsApp messages via Twilio API.
+This will result in Twilio using a Messaging Service instead of a plain sender number
+to deliver the SMS and WhatsApp messages.</p>
+<p>If <code>TWILIO_MESSAGING_SERVICE_SID</code> is not set, Healthchecks will fall back to using
+the "From" field with the value configured in <a href="#TWILIO_FROM">TWILIO_FROM</a> in API
+requests.</p>
+<p>Example:</p>
+<div class="highlight"><pre><span></span><code><span class="na">TWILIO_MESSAGING_SERVICE_SID</span><span class="o">=</span><span class="s">MGe56e622d540e6badc52ae0ac4af028c6</span>
+</code></pre></div>
+
 <h2 id="TWILIO_USE_WHATSAPP"><code>TWILIO_USE_WHATSAPP</code></h2>
 <p>Default: <code>False</code></p>
 <p>A boolean that turns on/off the WhatsApp integration.</p>

templates/docs/self_hosted_configuration.md

@@ -76,6 +76,7 @@ from environment variables. Below is a list of variables it reads and uses.
 <li><a href="#TWILIO_ACCOUNT">TWILIO_ACCOUNT</a></li>
 <li><a href="#TWILIO_AUTH">TWILIO_AUTH</a></li>
 <li><a href="#TWILIO_FROM">TWILIO_FROM</a></li>
+<li><a href="#TWILIO_MESSAGING_SERVICE_SID">TWILIO_MESSAGING_SERVICE_SID</a></li>
 <li><a href="#TWILIO_USE_WHATSAPP">TWILIO_USE_WHATSAPP</a></li>
 <li><a href="#USE_PAYMENTS">USE_PAYMENTS</a></li>
 <li><a href="#VICTOROPS_ENABLED">VICTOROPS_ENABLED</a></li>
@@ -854,6 +855,27 @@ Example:
 TWILIO_FROM=+15017122661
 ```
 
+## `TWILIO_MESSAGING_SERVICE_SID` {: #TWILIO_MESSAGING_SERVICE_SID }
+
+Default: `None`
+
+Optional, the Twilio Messaging Service SID for sending SMS and WhatsApp notifications.
+
+If `TWILIO_MESSAGING_SERVICE_SID` is specified, Healthchecks will include it in the
+"MessagingServiceSid" field when sending SMS and WhatsApp messages via Twilio API.
+This will result in Twilio using a Messaging Service instead of a plain sender number
+to deliver the SMS and WhatsApp messages.
+
+If `TWILIO_MESSAGING_SERVICE_SID` is not set, Healthchecks will fall back to using
+the "From" field with the value configured in [TWILIO_FROM](#TWILIO_FROM) in API
+requests.
+
+Example:
+
+```ini
+TWILIO_MESSAGING_SERVICE_SID=MGe56e622d540e6badc52ae0ac4af028c6
+```
+
 ## `TWILIO_USE_WHATSAPP` {: #TWILIO_USE_WHATSAPP }
 
 Default: `False`