SMS communication

[pwalsh]

Just like we currently support both inbound email for service requests, and, two-way communication around service requests, we are now implementing the same feature set and UX (to the extent reasonable) via SMS.

This integration is possible due to the extensive APIs that Twilio provides for SMS and phone number management (similar to how we leverage SendGrid, also a Twilio product, for email). Therefore, SMS support requires a direct dependency on Twilio - we are not designing an abstraction for potential use with other SMS backends.

At a high level, we plan to expose the following features:

• Enable submission of new service requests via SMS. The submitter sends a message to a dedicated Phone Number for a given Jurisdiction.
  • We can support an arbitrary number of Phone Numbers for a Jurisdiction, and Phone Numbers are routed into the system using the existing Routing Table with the same routing rules that are currently available for Inbound Emails ref.. This means that, if needed, there can be Phone Numbers for routing to a specific Department, a specific Service, a specific Assignee, and any combination thereof.
• When a Service Request is made via SMS, and, when a Service Request is submitted with Phone Number information, allow two-way communication around the Service Request with the Submitter.
  • Still deciding: Issue a dedicated Phone Number per Service Request - provides identical UX and data management flows to the current email integration, OR, have a "single" Phone Number, and a (more complex) disambiguation process to ensure two way communication is routed correctly to a given existing Service Request (will write about this a bit further below) Moved to Two-way SMS implementation #68
• All the same communication flows that currently exist for Email can apply for SMS - for the server, messages are dispatched via essentially the same data flow, and the difference is "only" the broadcast channel. This provides further basis for the development of more broadcast and input channels (WhatsApp, etc.)
• Jurisdictions can control if and how messages are sent to submitters, and if two-way communication is enabled. The flags for this on the Jurisdiction Model that currently exist, work in the same way for SMS as they do for email (and any other future communication channel).
• Two-way SMS is not only with Submitters. GovFlow should support the exact same flow with Staff Users (again, a near 1:1 feature parity with email). However, we are still a bit undecided on this for our current use cases. Will update as we progress with implementation - may not fully expose this, or, hide it via a Jurisdiction config. - agreed we are not doing this for now, but technically, the server supports Staff Users the same as submitters
• Unsubscribe management - Just like we integrate with SendGrid to keep up to date on which recipients have unsubscribed, bounced, etc., we need the same or similar routines for SMS, using the ChannelStatus model. - moved to Tracking SMS subscription status #69

References

Some links to docs on the inbound email, and two-way email, implementation:

• govflow/inbound-email.md at main · govflow/govflow
• govflow/two-way-email.md at main · govflow/govflow
• govflow/email-delivery-management.md at main · govflow/govflow

[pwalsh]

A bunch of related docs from Twilio:

• Track delivery status and description and list of possible statuses
• SMS Webhooks
• Twilio opt-out keywords

[pwalsh]

We are separating this issue out:

• The foundations and inbound SMS support - shipping in SMS Communication #67
• The actual two-way logic and implementation - moved to Two-way SMS implementation #68
• Tracking subscription status - moved to Tracking SMS subscription status #69

[pwalsh]

Closed by #67