Menu

Expand
Rate this page:

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.

Outbound SMS/MMS

message-privacy-sms-outbound

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.

Inbound SMS/MMS

message-privacy-sms-inbound

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.

Media messages

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-privacy-whatsapp-outbound

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-privacy-whatsapp-inbound

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.

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.

webhooks_configuration_post.jpg

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 Programmable Messaging > Settings > General:

redaction_settings_800.jpg


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 redaction to retain individual message bodies or phone numbers. However, you cannot redact messages and phone numbers at the individual message level if the account-level setting is to retain messages.

If you have enabled Message Redaction at the account level, you may want to retain the message body or phone number on individual messages by setting content_retention and/or address_retention to retain.

Please be aware that the reverse case is not an option: you cannot redact this data at the individual message level.

What’s next?

Rate this page:

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 our Twilio Community forums or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more