AWS Public Sector Blog

Supporting state agencies with Medicaid unwinding outreach: Creating a multi-lingual two-way messaging system

During the COVID-19 public health emergency, a continuous coverage requirement was put in place for Medicaid beneficiaries, meaning millions were automatically reenrolled in healthcare coverage without needing to renew eligibility. The forthcoming expiration of this requirement presents one of the largest-ever health coverage transition events, and states will need to move quickly to return to normal eligibility and enrollment operations.

A key focus for the Department of Health and Human Services (HHS) and state Medicaid agencies is making sure those eligible for Medicaid maintain coverage and supporting transition to alternatives, such as subsidized Marketplace coverage, for others.

Medicaid agencies need to conduct outreach to make their millions of members aware of the process for redetermination. When information is physically mailed to enrollees, those who have changed their address, moved, or are homeless, may be at risk of missing the alert and losing coverage. However, new guidance from the Federal Communications Commission (FCC) has made an important determination to allow government agencies to use calling and texting to verify Medicaid beneficiaries’ current addresses so the reenrollment materials reach them.

With cloud-based tools from Amazon Web Services (AWS), state agencies can conduct this outreach using no code/low code, serverless, elastic services that can scale to two billion text messages a day.

In this blog post, learn how to set up a multi-lingual, interactive SMS message campaign that can automatically verify and update member information on file based on member responses. Then, learn how to monitor the campaign’s effectiveness and response rates in a visual dashboard.

Solution overview: Create a multi-lingual interactive messaging campaign to support Medicaid member outreach

This solution is an example of an address update process through which a list of members are asked to update or confirm their address via SMS text messages. This solution uses the following communication services, serverless technologies, and managed services to deliver a scalable and cost-effective architecture:

  • Amazon Pinpoint, a flexible and scalable outbound and inbound marketing communications service.
  • Amazon QuickSight, a cloud-scale business intelligence (BI) service that you can use to deliver simple-to-understand insights to teams, wherever they are.
  • AWS Lambda, a serverless compute service that lets you run code in response to events such as changes in data, shifts in system state, or user actions.
  • Amazon DynamoDB, a key-value and document database that delivers single-digit millisecond performance at any scale.

The effectiveness of the process, including engagement and response rates, are tracked and displayed in a QuickSight dashboard. Below are examples of the address update conversation, and a dashboard with sample data (Figure 1).

SYSTEM > Hello John Stiles, this is AnyState Human Services with an important message about your Medicaid coverage. To confirm this is a real government message, visit https://anystate-website/medicaidrenewal.
To keep your Medicaid benefits, you need to fill out a renewal form. We will send you this form in the mail. To confirm or update your mailing address, reply YES. Reply STOP to opt out at any time.
SYSTEM > Thank you. Please verify you are John Stiles by providing your date of birth (MM/DD/YYYY).
MEMBER > 01/01/1970
SYSTEM > Thank you. Your identity has been verified.
We have your mailing address saved as:
“123 Any Street, Any Town, USA”
If that’s right, reply YES. If that’s wrong, reply NO.
SYSTEM > Thank you. Please reply with your updated address. You can also update your address at https://anystate-website/medicaidrenewal.
MEMBER > 100 Main Street, Anytown, USA
SYSTEM > Thank you. Your address is:
100 Main Street, Anytown, USA
Is this correct? Please reply YES or NO.
SYSTEM > Thank you. Your updated address is:
100 Main Street, Anytown, USA
You should receive an address confirmation letter in 2-4 weeks. If it doesn’t arrive, or if you have questions, visit https://anystate-website/medicaidrenewal.

Figure 1. An example of the reporting dashboard in QuickSight showing metrics on engagement and response rates.

Figure 1. An example of the reporting dashboard in QuickSight showing metrics on engagement and response rates.

Architecture overview

Figure 2. The architecture overview of AWS services involved in the communication workflow, described in detail in the following section.

Figure 2. The architecture overview of AWS services involved in the communication workflow, described in detail in the following section.

  1. First, a member’s contact information is loaded into the contact data table. While this solution uses DynamoDB to host the contact data table, this component can be refactored to another platform, including an existing database with member contact information.
  2. Member information is pushed to an Amazon Pinpoint segment where it is stored awaiting communication activity.
  3. An administrator creates and schedules an Amazon Pinpoint customer journey which applies workflow logic to send customized messages by language to the list of contacts in the Amazon Pinpoint segments.
  4. The customer journey launches at the scheduled time, sending the initial greeting SMS text messages to all members.
  5. Member recipients respond to the message, which launches the SMS reply processing AWS Lambda function.
  6. The SMS reply processing lambda function assesses the member’s current stage of the conversation, the message data, and formulates a response. Data is updated in the contact data table, and a response SMS text message is sent via Amazon Pinpoint. See an example conversation above in the solution overview section.
  7. Administrators view the QuickSight dashboard, which displays live reporting data from the contact data table.

Solution deployment


For this walkthrough, you must have the following prerequisites:

Section 1: Deploy SAM application

The AWS SAM CLI is an open-source command line tool used to locally build, test, debug, and deploy serverless applications defined with AWS SAM templates.

Download the source code from the AWS Samples Multi-Lingual Interactive SMS For Medicaid Unwinding GitHub and extract locally.

Build and deploy the stack

1. In a terminal, navigate to the root directory of the repository.

2. Run the following command to build and package the project for deployment:
sam build

3. Deploy the SAM template to your account. The wizard will guide you through the process of deploying the SAM AWS CloudFormation stack. Find more details on this process in the sam build documentation.

a. Run the following command:
sam deploy --guided --capabilities CAPABILITY_NAMED_IAM
b. Select the supported Region you chose in the prerequisites section.
c. The default parameters are suggested.
d. Choose Y for all Y or N items.

4. Wait for the deployment to complete. This process takes approximately five minutes.

a. Note the Outputs section. You will need the value of the KMSKeyArn output for Section 3, Step 1 below.

5. Next, import contacts into the DynamoDB Table:

a. In the AWS Management Console, navigate to the DynamoDB table in the selected Region, which includes the stack name in the table name.
b. Create a new table item for each recipient using the following format. These users will automatically populate into the Amazon Pinpoint application’s segment. Replace the fields last_name, dob, first_name, and pk. “pk” is the user’s phone number, including the country code (no plus sign).

     "conversation_status": { "S": "NONE" },
     "chat_list": { "L": [] },
     "opted_out": { "BOOL": false },
     "last_name": { "S": "LastNameHere" },
     "dob": { "S": "01/01/2000" },
     "first_name": { "S": "FirstNameHere" },
     "locale": { "S": "en" },
     "Language": { "S": "EN" },
     "physical_address": { "S": "NO ADDRESS ON FILE" },
     "pk": { "S": "14445550100" }

Section 2: Set up Amazon Pinpoint Journey

Figure 3. The Amazon Pinpoint journey configuration for this solution.

When you create an Amazon Pinpoint journey, start by choosing a segment that defines which customers will participate in the journey. After that, add the activities that customers pass through on their journeys. Activities can include sending messages or splitting customers into groups based on their attributes or behaviors.

In this step we will create a Journey which sends the initial SMS message, and then configure Amazon Pinpoint to forward reply SMS messages to our SMS reply processing function.

1. Navigate to the Amazon Pinpoint service in the AWS Management Console. Check that you’re in the same AWS Region you selected during the stack deployment step.

2. Select the application InteractiveSMS, and choose Create Journey:

a. Close introduction wizard popup and set a name, like “InteractiveSMS.”
b. Select Set entry condition:

i. Choose Add participants from a segment.
ii. Choose the InteractiveSMS-All segment.
iii. Save.

c. Add the activity Multivariate split:

i. Add a branch for every non-English and non-All segment (“ES” and “VI”, the language codes for Spanish and Vietnamese, if you’re using the default stack). This creates branches titled Branch A, Branch B, and so on.

d. Add the “else” (default) language:

i. Add the activity Send an SMS message. Choose the SMS template InteractiveSMSGreeting_EN. Save.
ii. Add the activity Send through a custom channel. Select the Lambda function which starts with the stack name, and includes “MarkConversationInitiated” in the function name. Under Specify the endpoint types that will receive this message, choose only SMS, then Save the popup box, and Save the custom channel activity.

e. Add the additional languages for each branch by following the “else” (default) language steps, choosing the relevant SMS template for that language.

f. Review the journey, but do not publish it. The workflow should match Figure 3.

3. Set up two-way SMS:

a. In the left column under SMS and Voice choose Phone Numbers and select one of the existing phone numbers.
b. Expand Two-way SMS and check the box to Enable two-way SMS.
c. Select Choose an existing Amazon SNS topic, and in the dropdown select the Amazon Simple Notification Service (Amazon SNS) topic which starts with the stack name and includes ReceiveSMSTopic in the function name. Save.

At this point the solution is functional.

Section 3: Set up analytics

Now, we set up a live reporting dashboard in QuickSight to visualize the progress and effectiveness of the campaign’s engagement.

1. Set up Amazon Athena:

a. Navigate to the Amazon Athena service in the AWS Management Console. Set up the Athena service and configure the Amazon Simple Storage Service (Amazon S3) buckets for query results.
b. Create a new Athena data source for DynamoDB and name it InteractiveSMSDDB. This process involves deploying a new Lambda function to query data from DynamoDB and deploying an Amazon S3 bucket for data to reside in.

i. After the connector Lambda function is deployed, modify the function’s IAM role to include a new in-line policy (below) granting access to read the encrypted DynamoDB database. Replace the INSERT-KMS-KEY-ARN-HERE with the value for KMSKeyArn you obtained in Section 1 Step 4.

    "Statement": [
            "Action": "kms:Decrypt",
            "Resource": "INSERT-KMS-KEY-ARN-HERE",
            "Effect": "Allow"

c. Use the Athena query editor to test and verify that you can list the contacts in the InteractiveSMS contacts table.

2. Set up QuickSight:

a. Navigate to the Amazon QuckSight service in the AWS Management Console and sign up for QuickSight if it is not already enabled.
b. You only need a standard license to support this solution.
c. On the Create your QuickSight account page make sure that access and auto-discovery is enabled for AWS Identity and Access Management (IAM), Amazon Athena, and the Amazon S3 bucket for Athena query results.
d. Add the following inline policy to the aws-quicksight-service-role-v0 role in IAM.

i. Replace the INSERT-ATHENA-CONNECTOR-LAMBDA-ARN-HERE with the ARN of the function deployed during the DynamoDB Athena data source setup previously in Section 3 Step 1B.

     "Version": "2012-10-17",
     "Statement": [
             "Sid": "InvokeAthenaFedereted",
             "Effect": "Allow",
             "Action": "lambda:InvokeFunction",

3. Create a dataset in QuickSight:

a. In the top navigation bar, select the person-shaped Account icon and verify that your QuickSight console is connected to the same AWS Region as your deployment.
b. Select Datasets in the left navigation area, and choose New dataset.
c. Select Athena and then enter a data source name and leave the primary Athena workgroup selected. Select Create data source. Choose the Athena catalog, database, and table (the DynamoDB source) referenced earlier in Step 1B. Advance to the next page with Select.
d. Choose Directly query your data then select Edit/Preview data.
e. Add calculated fields as described in the file within the GitHub repository.
f. Make sure the initial manually-added contact from Section 1 Step 5 appears in the Dataset table in the bottom-right portion of the screen.
g. Choose Save & Publish.

4. Create a QuickSight dashboard:

a. Reference Figure 1 and the file within the GitHub repository to re-create the visualization in the figure. Adjust the visual appearance (text size, legends, etc) to accommodate you and your teams’ needs.
b. Choose the Share icon and Publish the dashboard.

Section 4: Test the Solution

In this section, we test the solution and view the metrics in the QuickSight dashboard.

1. Send the greeting SMS message:

a. Navigate to the Amazon Pinpoint service in the AWS Management Console. Select the application InteractiveSMS. Under the Journeys section, select the InteractiveSMS Journey. Select Actions and choose Duplicate Journey.
b. Choose a new name for the journey. Select a start time a few minutes in the future. Choose Review, then move through the review process, and Publish the journey.
c. The journey metrics panel should display and begin a count-down. After the journey launches, wait a few minutes to receive the SMS message.

2. Engage the Address Update Wizard and test the QuickSight dashboard:

a. Navigate to the published QuickSight dashboard created in Section 3. Refresh the dashboard throughout the following steps and observe how the metrics change, notably the conversation_status column of the contact table.
b. Walk through the following address update process, referring to the data entered into the DynamoDB table in Section 1. The default Date-of-Birth is 01/01/2000.

i. Reply YES to the message to begin the update process. The QuickSight dashboard should display a non-zero number of respondents (or 100% respondents if you only had one contact in the DynamoDB table).
ii. Once your address has been confirmed or updated via SMS or text, note how the Successful Address Engagements gauge changes and the Contact Table updates the physical_address value.

3. You can reset the environment by clearing the contents of the DynamoDB table and re-adding items as described in Section 1.

Clean Up

This is an entirely serverless solution, so costs are directly related to usage. The persistent cost to maintaining this application when not in use is in the user data stored in Amazon DynamoDB.

To avoid incurring future charges, delete the resources. To deprovision all resources:

1. In the AWS Management Console, navigate to AWS CloudFormation and select the stack specified in the deployment section of this post.

2. Choose Delete near the top and stack title to begin deleting the stack. This process will take approximately five minutes.

NOTE: This will NOT delete the contents of the Amazon DynamoDB table which includes all user contact information and SMS message logs.

Security considerations

The Introduction to AWS Security whitepaper is intended to provide an introduction to AWS’s approach to security, including the controls in the AWS environment and some of the products and features that AWS makes available to customers to meet security objectives.

Resources deployed by this solution encrypt content at rest and in transit using a customer managed AWS Key Management Service (AWS KMS) key. Please consult the AWS KMS key policy documentation and review the policy to ensure it meets your needs. Additionally if you require more network control and traffic observability, you can evaluate the benefits of refactoring the configuration of the Lambda functions to place them within a virtual private cloud (VPC) you control.


Agencies can use this solution to perform an elastic and scalable outreach campaign for their members and beneficiaries. This solution as described is flexible, low-code, and cost optimized. Plus, this solution can act as a template that can be repurposed for many other outreach-related use cases as well.

Health and human services (HHS) agencies across the country are using the power of AWS to unlock their data, improve citizen experience, and deliver better outcomes. See more Health and Human Services Cloud Resources here. Learn more about how governments use AWS to innovate for their constituents, design engaging constituent experiences, and more at the AWS Cloud for State and Local Governments hub.

Subscribe to the AWS Public Sector Blog newsletter to get the latest in AWS tools, solutions, and innovations from the public sector delivered to your inbox, or contact us.

Please take a few minutes to share insights regarding your experience with the AWS Public Sector Blog in this survey, and we’ll use feedback from the survey to create more content aligned with the preferences of our readers.

Caesar Kabalan

Caesar Kabalan

Caesar Kabalan is a solutions architect at Amazon Web Services (AWS). He brings together his development and enterprise infrastructure experience to invent solutions to solve customer challenges. He also restores, tweaks, and reprograms 1970s-era pinball machines as a hobby.

Vignesh Srinivasan

Vignesh Srinivasan

Vignesh Srinivasan is a senior solutions architect at Amazon Web Services (AWS). He spent a decade working with CMS, including helping to implement the Federal Health Exchange as part of the Affordable Care Act. He was also an integral part of the team responsible for fixing the system and eventually successfully migrating the system to AWS. His passion is in enabling states to make their own decisions. Vignesh has a master’s degree from Rochester Institute of Technology and an MBA from the University of Maryland, in addition to several professional certifications.