Add notifications-sms module to support SMS notifications by jrpbc · Pull Request #256 · navapbc/platform-test

jrpbc · 2026-02-09T19:44:59Z

Ticket

Resolves #976

Changes

What was added, updated, or removed in this PR.

- Implements PinpointSMSVoiceV2 service resources
- Supports SMS configuration sets and opt-out lists
- Includes VPC endpoint for secure connectivity
- Provides IAM policies for SMS sending permissions
- Supports delivery receipt logging to CloudWatch

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers.

Testing

Provide evidence that the code works as expected. Explain what was done for testing and the results of the test plan. Include screenshots, GIF demos, shell commands or output to help show the changes working as expected. ProTip: you can drag and drop or paste images into this textbox.

Waiting for AWS to approve requested phone number +18665684902.

Performed basic validation which includes:
- Go to /sms-notifications -> use AWS provided receiver phone number +14254147755 (This phone number is for successful messages test); validated Cloudwatch logs for message success (TEXT_SUCCESS status)
- Go to /sms-notifications -> use AWS provided receiver phone number +14254147167 (This phone number is for failure messages test); validated Cloudwatch logs for message failure (TEXT_BLOCKED status)

Preview environment for app-nextjs

Service endpoint: https://p-256-app-nextjs-dev-688529323.us-east-1.elb.amazonaws.com
Deployed commit: 599b06a

Preview environment for app

Service endpoint: https://p-256-app-dev-1261677609.us-east-1.elb.amazonaws.com
Deployed commit: 599b06a

Preview environment for app-flask

Service endpoint: https://p-256-app-flask-dev-80272150.us-east-1.elb.amazonaws.com
Deployed commit: b01e304

Preview environment for app-rails

Service endpoint: https://p-256-app-rails-dev-24845359.us-east-1.elb.amazonaws.com
Deployed commit: 599b06a

doshitan

This feels a little complex. Can you update the tech spec with tradeoffs/rationale and future considerations around some of the decisions? It looks like it's been updated a little bit, but a lot of context feels missing.

In particular, the "simulator" stuff doesn't feel very useful. Can we drop it?

infra/modules/network/resources/variables.tf

infra/app/service/notifications.tf

infra/modules/notifications-sms/resources/main.tf

infra/modules/notifications-sms/resources/variables.tf

app/sms_notifications.py

app/app.py

infra/modules/notifications-sms/resources/variables.tf

infra/app/app-config/env-config/variables.tf

infra/modules/notifications-sms/resources/variables.tf

jrpbc · 2026-02-18T02:39:44Z

Updated Tech Specs with: All Considerations; Implementation Options considered.

doshitan · 2026-02-20T22:22:37Z

infra/modules/notifications-sms/resources/access_control.tf

+          # Allow access to the phone pool created by CloudFormation
+          data.aws_cloudformation_stack.sms_config_set_outputs.outputs["PhonePoolArn"],
+          # Allow access to the configuration set created by this module
+          "arn:aws:sms-voice:*:${data.aws_caller_identity.current.account_id}:configuration-set/${var.name}-config-set"


Is it not possible to get this value from the created resource directly?

Due to the use of CloudFormation (via aws_cloudformation_stack) and the inability to fully control the timing of its execution, I was intermittently encountering the following error:
`Error: Provider produced inconsistent final plan

When expanding the plan for module.notifications_sms[0].aws_cloudformation_stack.sms_config_set to include new values learned so far during apply, provider "registry.terraform.io/hashicorp/aws" produced an invalid new value for .outputs: was known, but now unknown.
`
With the use of Terraform "data" here allows us to better control the timing and sequence of execution for the CloudFormation stack, preventing the provider from re-evaluating stack outputs in an inconsistent state and eliminating the intermittent plan inconsistency error.

infra/app/app-config/env-config/variables.tf

docs/infra/sms-notifications.md

infra/app/service/notifications.tf

- Implements PinpointSMSVoiceV2 service resources - Supports SMS configuration sets and opt-out lists - Includes VPC endpoint for secure connectivity - Provides IAM policies for SMS sending permissions - Supports delivery receipt logging to CloudWatch

…ion resources

…a Phone Number resource

…lear

…ications Module

doshitan

A few notes mostly around docs and some cleanup. But I think we are good to create the template PR.

doshitan · 2026-03-13T16:52:02Z

app/templates/sms_form.html

+    <form method="post">
+        <div>
+            <label for="phone_number">Receiver Phone Number (E.164 format: +1234567890):</label><br>
+            <input type="tel" id="phone_number" name="phone_number"


I think we can make this a select element populated by the rendering endpoint, with only the predefined simulator numbers by default.

(longer term we should probably better lock down the email testing endpoint as well, we don't really want to be a vehicle to spam people)

Restricting this to the simulator numbers here will prevent from testing approved phone numbers. I added an extra message to this form, specifying the phone numbers that can be used for testing if using simulator phone number as originator.

doshitan · 2026-03-13T16:56:11Z

infra/app-nextjs/app-config/main.tf

+  # 1. Creates AWS End User Messaging SMS configuration set
+  # 2. Sets up IAM permissions for SMS sending
+  # 3. Configures SMS delivery tracking and opt-out management
+  enable_sms_notifications = true


The default in the template PR should be false.

Applied change

infra/project-config/aws_services.tf

doshitan · 2026-03-13T17:08:16Z

infra/app/service/notifications.tf

+    module.notifications_phone_pool_temp[0].phone_pool_id)
+  ) : null
+
+  #SMS environment variables for notifications-sms module


Suggested change

#SMS environment variables for notifications-sms module

# SMS environment variables for notifications-sms module

Applied change

infra/modules/notifications-phone-pool/data/main.tf

doshitan · 2026-03-13T17:23:04Z

docs/infra/sms-notifications.md

+- **SIMULATOR**: Test numbers for development (immediate approval, limited recipients)
+
+### Simulator Phone Numbers
+AWS Allows to use **simulator** phone numbers as originator to send text.  This simulator phone numbers are only allowed to send SMS text to:


Suggested change

AWS Allows to use **simulator** phone numbers as originator to send text. This simulator phone numbers are only allowed to send SMS text to:

AWS Allows to use **simulator** phone numbers as originator to send text. This simulator phone numbers are only allowed to send SMS text to:

Applied change

doshitan · 2026-03-13T17:24:03Z

docs/infra/sms-notifications.md

+  sms_number_type                        = null # Enter SMS Number Type (e.g: 'SHORT_CODE', 'LONG_CODE', 'TOLL_FREE', 'TEN_DLC', 'SIMULATOR') when available; otherwise leave empty to use simulator number type
+}
+```
+*__Note:__* if an AWS End User SMS Registration ID is not provided, a simulator phone number will be automatically provisioned which will allow applications to send SMS test to:


Can we point to the above Simulator Phone Numbers section rather than duplicating?

Applied change

doshitan · 2026-03-13T17:24:49Z

docs/infra/sms-notifications.md

+*__Note:__* This assumes your AWS End User Messaging SMS Registration has been approved and configured in `infra/<APP_NAME>/app-config/env-config/dev.tf|staging.tf|prod.tf`
+### 1. Verify Destination Numbers (Sandbox Accounts)
+
+In sandbox environments, you can only send SMS to up to 10 verified phone numbers.  Steps to register destination phone numbers:


Suggested change

In sandbox environments, you can only send SMS to up to 10 verified phone numbers. Steps to register destination phone numbers:

In sandbox environments, you can only send SMS to up to 10 verified phone numbers. Steps to register destination phone numbers:

Applied change

doshitan · 2026-03-13T17:28:14Z

docs/infra/sms-notifications.md

+
+## Requirements
+
+1. **AWS End User Messaging SMS Registration**: All provisioned originating phone numbers require a AWS End User Messaging Registration form to be completed in the AWS End User Messaging Service, and approved by the AWS phone carrier.  Without an approved Registration, originating phone numbers cannot be provisioned.


All provisioned originating phone numbers require a AWS End User Messaging Registration form to be completed

Still makes it sound like every phone number will need a registration form completed at first glance. Can we clarify?

Suggested change

1. **AWS End User Messaging SMS Registration**: All provisioned originating phone numbers require a AWS End User Messaging Registration form to be completed in the AWS End User Messaging Service, and approved by the AWS phone carrier. Without an approved Registration, originating phone numbers cannot be provisioned.

1. **AWS End User Messaging SMS Registration**: All provisioned originating phone numbers require a AWS End User Messaging Registration form to be completed in the AWS End User Messaging Service, and approved by the AWS phone carrier. Without an approved Registration, originating phone numbers cannot be provisioned.

Changed the description of the AWS End User Messaging Registration and its purpose and process

docs/infra/sms-notifications.md

- Break notifications-sms module into two components: * notifications-phone-pool: manages phone pools and phone numbers (CloudFormation) * notifications-sms: manages configuration sets and IAM policies (CloudFormation + Terraform) - Add logic to reuse phone pool on temporary environments or create one f none exists - Add logic to create phone pool for production environment - Update documentations

doshitan · 2026-03-17T16:20:47Z

docs/infra/sms-notifications.md

+}
+```
+*__Note:__* if an AWS End User SMS Registration ID is not provided, a simulator phone number will be automatically provisioned.
+### 3. Deploy SMS notification infrastructure


Suggested change

### 3. Deploy SMS notification infrastructure

### 3. Deploy SMS notification infrastructure

doshitan · 2026-03-17T16:21:06Z

docs/infra/sms-notifications.md

+## Testing Setup
+
+*__Note:__* This assumes your AWS End User Messaging SMS Registration has been approved and configured in `infra/<APP_NAME>/app-config/env-config/dev.tf|staging.tf|prod.tf`
+### 1. Verify Destination Numbers (Sandbox Accounts)


Suggested change

### 1. Verify Destination Numbers (Sandbox Accounts)

### 1. Verify Destination Numbers (Sandbox Accounts)

doshitan · 2026-03-17T16:22:54Z

docs/infra/sms-notifications.md

+
+## Testing Setup
+
+*__Note:__* This assumes your AWS End User Messaging SMS Registration has been approved and configured in `infra/<APP_NAME>/app-config/env-config/dev.tf|staging.tf|prod.tf`


The specific environments will vary by project, can we just point back up to the "Configure SMS settings" section?

doshitan · 2026-03-17T16:24:09Z

docs/infra/sms-notifications.md

+- Registration and phone numbers are region-specific
+- You must create separate registrations for each AWS region where you plan to send SMS
+- Phone numbers provisioned in one region cannot be used in other regions
+- Phone numbers must be provisioned by AWS through the End User Messaging service.  You cannot bring existing phone numbers from other carriers or services.


Suggested change

- Phone numbers must be provisioned by AWS through the End User Messaging service. You cannot bring existing phone numbers from other carriers or services.

- Phone numbers must be provisioned by AWS through the End User Messaging service. You cannot bring existing phone numbers from other carriers or services.

doshitan · 2026-03-17T16:24:26Z

docs/infra/sms-notifications.md

+
+A company or entity must be registered and approved in AWS End User Messaging before using the service for SMS notifications.
+
+**Important Regional Considerations:**


Suggested change

**Important Regional Considerations:**

**Important Considerations:**

doshitan · 2026-03-17T16:25:14Z

docs/infra/sms-notifications.md

+- You must create separate registrations for each AWS region where you plan to send SMS
+- Phone numbers provisioned in one region cannot be used in other regions


These feel like sub-points/clarifications of the first one, so indent?

Suggested change

- You must create separate registrations for each AWS region where you plan to send SMS

- Phone numbers provisioned in one region cannot be used in other regions

- You must create separate registrations for each AWS region where you plan to send SMS

- Phone numbers provisioned in one region cannot be used in other regions

doshitan · 2026-03-17T16:25:27Z

docs/infra/sms-notifications.md

+A company or entity must be registered and approved in AWS End User Messaging before using the service for SMS notifications.
+
+**Important Regional Considerations:**
+- Registration and phone numbers are region-specific


Suggested change

- Registration and phone numbers are region-specific

- Registrations and phone numbers are region-specific

doshitan · 2026-03-17T16:26:40Z

infra/modules/notifications-phone-pool/data/find-existing-pools.sh

@@ -0,0 +1,48 @@
+#!/bin/bash


Suggested change

#!/bin/bash

#!/usr/bin/env bash

doshitan · 2026-03-17T16:28:13Z

infra/modules/notifications-phone-pool/data/find-existing-pools.sh

+REGION="${1}"
+
+# Get first available pool without filtering by name
+QUERY="Pools[0].{PoolId:PoolId,PoolArn:PoolArn}"
+
+# List SMS phone pools using AWS CLI with specified region
+pools=$(aws pinpoint-sms-voice-v2 describe-pools \
+    --region "$REGION" \
+    --query "$QUERY" \
+    --output json 2>/dev/null || echo '{}')
+
+# Check if any pools were found
+if [[ "$pools" == "{}" ]] || [[ "$pools" == "null" ]]; then
+    echo '{"pool_id":"","pool_arn":"","exists":"false"}'
+    exit 0
+fi
+
+# Extract pool details
+pool_id=$(echo "$pools" | jq -r '.PoolId // ""')
+pool_arn=$(echo "$pools" | jq -r '.PoolArn // ""')
+
+# Validate that we have valid pool data
+if [[ "$pool_id" == "" ]] || [[ "$pool_id" == "null" ]]; then
+    echo '{"pool_id":"","pool_arn":"","exists":"false"}'
+else
+    echo "{\"pool_id\":\"$pool_id\",\"pool_arn\":\"$pool_arn\",\"exists\":\"true\"}"
+fi


For formatting standards.

Suggested change

REGION="${1}"

# Get first available pool without filtering by name

QUERY="Pools[0].{PoolId:PoolId,PoolArn:PoolArn}"

# List SMS phone pools using AWS CLI with specified region

pools=$(aws pinpoint-sms-voice-v2 describe-pools \

--region "$REGION" \

--query "$QUERY" \

--output json 2>/dev/null || echo '{}')

# Check if any pools were found

if [[ "$pools" == "{}" ]] || [[ "$pools" == "null" ]]; then

echo '{"pool_id":"","pool_arn":"","exists":"false"}'

exit 0

fi

# Extract pool details

pool_id=$(echo "$pools" | jq -r '.PoolId // ""')

pool_arn=$(echo "$pools" | jq -r '.PoolArn // ""')

# Validate that we have valid pool data

if [[ "$pool_id" == "" ]] || [[ "$pool_id" == "null" ]]; then

echo '{"pool_id":"","pool_arn":"","exists":"false"}'

else

echo "{\"pool_id\":\"$pool_id\",\"pool_arn\":\"$pool_arn\",\"exists\":\"true\"}"

fi

# Get region parameter (always provided by Terraform)

region="${1}"

# Get first available pool without filtering by name

query="Pools[0].{PoolId:PoolId,PoolArn:PoolArn}"

# List SMS phone pools using AWS CLI with specified region

pools=$(aws pinpoint-sms-voice-v2 describe-pools \

--region "${region}" \

--query "${query}" \

--output json 2>/dev/null || echo '{}')

# Check if any pools were found

if [[ "${pools}" == "{}" ]] || [[ "${pools}" == "null" ]]; then

echo '{"pool_id":"","pool_arn":"","exists":"false"}'

exit 0

fi

# Extract pool details

pool_id=$(echo "${pools}" | jq -r '.PoolId // ""')

pool_arn=$(echo "${pools}" | jq -r '.PoolArn // ""')

# Validate that we have valid pool data

if [[ -z "${pool_id}" ]] || [[ "${pool_id}" == "null" ]]; then

echo '{"pool_id":"","pool_arn":"","exists":"false"}'

else

echo "{\"pool_id\":\"${pool_id}\",\"pool_arn\":\"${pool_arn}\",\"exists\":\"true\"}"

fi

doshitan · 2026-03-17T16:37:07Z

infra/modules/notifications-phone-pool/data/find-existing-pools.sh

The script looks to only grab the first phone pool in a region? So the name doesn't feel quite right being plural, maybe more find-an-existing-pool.sh?

jrpbc requested a review from doshitan February 13, 2026 14:12

doshitan reviewed Feb 13, 2026

View reviewed changes

jrpbc requested a review from doshitan February 19, 2026 02:01

doshitan reviewed Feb 23, 2026

View reviewed changes

jrpbc requested a review from doshitan February 24, 2026 05:58

jrpbc force-pushed the johan/notifications-sms branch from b01e304 to 1a68e31 Compare March 12, 2026 19:20

jrpbc added 10 commits March 12, 2026 17:06

Allow github-action access to create/update SMS-Voice and CloudFormat…

8a0e374

…ion resources

Add to SNS Notification Module SMS Phone Number Pool associated with …

cfe58e3

…a Phone Number resource

Remove unused variables

63421bb

Make the description of the sms_simulator_phone_number_id variable, c…

004cbed

…lear

Fix terraform formatting

9cbf1ec

Remove SMS Simulator phone number as input variable for the SMS Notif…

346f42b

…ications Module

Fix CloudFormation destroy dependency ordering

7b19e10

Create SMS notifications feature documentation

32e10ba

Create SMS notifications implementation ADR

6c2f7c0

jrpbc force-pushed the johan/notifications-sms branch 5 times, most recently from ae7a043 to e462bbc Compare March 13, 2026 05:34

doshitan reviewed Mar 13, 2026

View reviewed changes

jrpbc force-pushed the johan/notifications-sms branch from e462bbc to 890c33d Compare March 17, 2026 04:28

jrpbc force-pushed the johan/notifications-sms branch from b1aa6cc to 599b06a Compare March 17, 2026 05:36

jrpbc requested a review from doshitan March 17, 2026 05:49

doshitan reviewed Mar 17, 2026

View reviewed changes

	#SMS environment variables for notifications-sms module
	# SMS environment variables for notifications-sms module

	AWS Allows to use simulator phone numbers as originator to send text. This simulator phone numbers are only allowed to send SMS text to:
	AWS Allows to use simulator phone numbers as originator to send text. This simulator phone numbers are only allowed to send SMS text to:

	In sandbox environments, you can only send SMS to up to 10 verified phone numbers. Steps to register destination phone numbers:
	In sandbox environments, you can only send SMS to up to 10 verified phone numbers. Steps to register destination phone numbers:


		## Requirements

		1. AWS End User Messaging SMS Registration: All provisioned originating phone numbers require a AWS End User Messaging Registration form to be completed in the AWS End User Messaging Service, and approved by the AWS phone carrier. Without an approved Registration, originating phone numbers cannot be provisioned.

	### 3. Deploy SMS notification infrastructure

	### 3. Deploy SMS notification infrastructure

	### 1. Verify Destination Numbers (Sandbox Accounts)

	### 1. Verify Destination Numbers (Sandbox Accounts)


		## Testing Setup

		__Note:__ This assumes your AWS End User Messaging SMS Registration has been approved and configured in `infra/<APP_NAME>/app-config/env-config/dev.tf\|staging.tf\|prod.tf`

	- Phone numbers must be provisioned by AWS through the End User Messaging service. You cannot bring existing phone numbers from other carriers or services.
	- Phone numbers must be provisioned by AWS through the End User Messaging service. You cannot bring existing phone numbers from other carriers or services.


		A company or entity must be registered and approved in AWS End User Messaging before using the service for SMS notifications.

		Important Regional Considerations:

	Important Regional Considerations:
	Important Considerations:

		- You must create separate registrations for each AWS region where you plan to send SMS
		- Phone numbers provisioned in one region cannot be used in other regions

	- Registration and phone numbers are region-specific
	- Registrations and phone numbers are region-specific

Conversation

jrpbc commented Feb 9, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Ticket

Changes

Context for reviewers

Testing

Preview environment for app-nextjs

Preview environment for app

Preview environment for app-flask

Preview environment for app-rails

Uh oh!

doshitan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrpbc commented Feb 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

doshitan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrpbc commented Feb 9, 2026 •

edited by github-actions bot

Loading

doshitan Mar 17, 2026 •

edited

Loading