Protect Communication Content and User Identity with Message Redaction
With Twilio’s Message Redaction feature, you protect customers’ messaging privacy by redacting the message body and phone number. You can enable this privacy feature at the account level so that Twilio does not retain sensitive customer information by default.
If you are building for highly regulated industries, such as health care, financial services, and education, content redaction may be required to ensure your application’s regulatory compliance. Privacy and anonymous communications may also be a value proposition for your application.
This guide shows you how to set up your Twilio account correctly for content and phone number redaction, and includes code samples that retain this information at an individual message level.
Message body redaction vs. phone number redaction
With message body redaction, you ensure that Twilio never retains message bodies that may contain sensitive information. Phone number redaction will obfuscate the last four digits of the non-Twilio phone number in the message request.
How redaction works: SMS/MMS
SMS/MMS and WhatsApp redaction vary slightly in implementation. For more information about WhatsApp message redaction, please continue to the next section.
Once an outbound SMS/MMS message is sent via Twilio’s API, it will be retained in the queue for up to four hours, depending on message volume.
During the In-transit phase, Twilio sends the message to the carrier/provider and waits for an acknowledgment before redacting the message body and phone number. Once the provider acknowledges receipt of the message, Twilio stores the sensitive information for up to six hours before redaction. This is for disaster recovery purposes.
In the Post-transit stage, the message with redacted information is held for long-term storage, billing, and debugger notification purposes.
Twilio receives an inbound SMS/MMS message from the carrier/provider. Twilio stores the message up to six hours for disaster recovery purposes while it attempts to pass along the message information in the form of an HTTP request to your customer-defined A message comes in webhook. If the request to your primary webhook fails, Twilio tries the fallback webhook.
To avoid the potential loss of message data due to redaction, it is best to set both the primary and fallback webhooks for incoming messages. Twilio redacts the sensitive phone number and body information on incoming messages before the message is saved for billing, debugging, and other long-term storage purposes.
When Message Privacy is enabled, the direction and location in which an MMS (media message) are sent affect the length of time before the redaction of its associated media.
For outbound MMS messages in the US and Canada, Twilio deletes the media after a 15-minute period. During this time, Twilio processes the messages for hand-off to the carrier/provider.
For outbound (“pseudo”) MMS messages (outside the US and Canada), Twilio’s MMS Converter feature converts the original MMS to an SMS with a link to the media file. The media is retained for seven days to give the recipient time to click on the media link.
For inbound MMS messages, Twilio will delete media files after 24 hours. This gives the customer’s applications time to access the associated files.
How redaction works: WhatsApp
When Message Privacy features are enabled, WhatsApp messages flow through Twilio in the same way as SMS/MMS messages do, with two differences:
- 24-hour sessions: Twilio keeps track of WhatsApp’s sessions for billing purposes.
- WhatsApp containers: Messaging through the WhatsApp Business API requires the use of container infrastructure. Containers are hosted by Twilio, but WhatsApp is responsible for the containers. Twilio has very limited controls over how data is managed inside WhatsApp containers.
The impact of these differences on how messages are transmitted is explained below.
Outbound WhatsApp Messages
Message content, including body and media, are deleted from the WhatsApp containers as soon as there is an acknowledgment that the message was delivered.
If a message is undelivered, WhatsApp’ container system may keep the message while it retries delivery, but no longer than seven days. Messages may go undelivered if the end user’s device is turned off or if the user has blocked the business. In addition, WhatsApp currently stores non-Twilio phone numbers indefinitely in its container infrastructure, even if Phone Number Redaction is enabled and Twilio has obfuscated the last four digits of non-Twilio numbers in its systems.
Inbound WhatsApp Messages
Message content, including body and media, are deleted by WhatsApp from the containers once the message is received by the business. Deletion in WhatsApp containers occurs at random intervals but generally take a few hours. WhatsApp stores non-Twilio phone numbers indefinitely in its container infrastructure, even if Phone Number Redaction is enabled and Twilio has obfuscated the last four digits of non-Twilio numbers in its systems.
In addition, Twilio maintains a list of recipients contacted in last 24 hours. This is done for billing purposes, in order to calculate WhatsApp’s 24-hour session.
If you are interested in these advanced privacy features, talk to Sales about getting access to Message Redaction.
Set up your Twilio Account for Message Privacy
To enable Message Privacy features, you’ll need to talk to Sales. However, there are also a few things to configure in your account to support redaction.
Before you can redact message body and phone numbers, you should ensure that your account is properly configured to support these privacy features. Taking the following steps will help you get started right away once Twilio has approved your request to enable Message Privacy features on your account.
Disable Sticky Sender and Fallback to Long Code on your Message Service
In order to redact message bodies and phone numbers, you must disable two features on your Messaging Service:
- Sticky Sender
- Fallback to Long Code
Sticky Sender on Messaging Services is incompatible with phone number redaction in order to maintain the mapping of recipients and numbers.
Fallback to Long Code is incompatible with message redaction due to the immediate deletion of the body and phone number after the message has been handed off to the provider.
Scheduled SMS messaging is incompatible with message body or phone number redaction at this time.
To disable these features, visit the Console’s SMS Services section. There, you can select your Message Service(s) and disable Sticky Sender and Fallback to Long Code.
Disable built-in STOP filtering
When Twilio receives a
stop message, the built-in STOP filtering saves the incoming phone number to Twilio’s internal list of blocked numbers for that account. Therefore, using Twilio’s built-in STOP filtering could potentially violate the phone number redaction guarantee for customers who choose to opt-out of messages.
Please note that if you disable this feature, you will need to build STOP filtering yourself as this is generally required by telecommunications carriers as well as anti-spam laws.
To disable automatic STOP filtering, contact Support.
Use POST requests in your SMS webhooks
Twilio logs GET request parameters for up to seven days. When setting the A Message Comes In webhook on a Phone Number or Messaging Service, make sure that the method is set to POST, not GET. You must use POST on both the primary and fallback webhooks to ensure redaction.
To verify your webhook configuration, visit the Console’s Phone Numbers, Messaging Services, and TwiML Apps sections.
Verify your privacy use cases
Twilio Studio, Flex, and Conversations are not compatible with redaction because Twilio will log message data for these products. If you are using these products in your application, the message data will be logged automatically.
Enable Message Redaction for your account
After you receive access to and configure your account for Message Redaction, make sure to enable it for your account. You can do this in the Twilio Console via Messaging > Settings > General:
When you enable either Messaging Body Redaction or Phone Number Redaction, Twilio will scan your account and verify that it is configured correctly. You will receive a debugger notification for any features that are misconfigured.
Retain Message Body and Phone Number on a Single Message
Customers can override account-level privacy settings for individual message bodies or phone numbers.
Thus, if Phone Number and/or Message Body Redaction is enabled on your account and you wish to retain this data on specific messages, you may set ContentRetention and AddressRetention parameters to 'retain' on the Create a Message Resource request.
If these features are disabled on your account and you wish to redact this data on specific messages, you may set ContentRetention to 'discard' and/or AddressRetention to 'obfuscate' on the Create a Message Resource request.
- Request Message Redaction
- Configure your account for redaction in the Console
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.