Customizing Chat Attachment Behavior

This guide is for Flex UI 1.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x or you are starting out, we recommend that you build with Flex Conversations.

Once Webchat attachments are enabled you can configure additional details for what agents and customers are allowed to send, including:

  • The maximum allowed file size
  • Restrict attachments to a limited set of file types.
  • Configure both the agent and customer restrictions independently.

Configure the maximum file size for attachments

You can adjust the maximum file size that can be uploaded by either the agent or the customer. Enter a value in bytes into the maxFileSize value to set the max file size allowed. If no value is provided the default value of 10,485,760 (10Mb) is used.

// Max file size = 10 mb = 10 x 1024 x 1024 = 10,485,760

interface Config {
  fileAttachment?: {
    enabled?: boolean;
    maxFileSize?: number;

Configure which files types can be attached

You can also specify a custom set of file extensions that can be uploaded. Enter all of the accepted file extensions as an array into the acceptedExtensions value.

The client side validation only checks the attached file's size and mime type. You can write business logic to do additional validation of the sent media messages using Programmable Chat webhooks.

All extensions are supported by Programmable Chat, so you should include all of the file types you want to use in your custom array. A custom value entered into the acceptedExtensions array will override the default extensions set.

// Accepted extensions = .png, .txt, .pdf = ["png", "txt", "pdf"]

interface Config {
  fileAttachment?: {
    enabled?: boolean;
    acceptedExtensions?: Array<string>;

Example web chat attachments configuration

An example of both of these settings is shown below.

fileAttachment: {
  enabled: true,
  maxFileSize: 26214400,
  acceptedExtensions: ["png", "txt", "pdf"]


There are four actions that can be invoked programmatically. You can use these to assist agents with quick actions or automate parts of a web chat interaction.

Send media message

Select and send a file as an attachment in a single action.

Actions.invokeAction("SendMediaMessage", { file: file, channelSid: "unique_channel_identifier" });

Attach a file

Add a file as an attachment in the message input field.

⚠️ Note: Attaching a file will replace text that was already entered.

Actions.invokeAction("AttachFile", { file: File, channelSid: "unique_channel_identifier" });

Detach an already attached file

Remove an unsent attached from the message input field.

⚠️ Note: Detaching a file will not restore previous text that was replaced using the attach action.

Actions.invokeAction("DetachFile", { file: File, channelSid: "unique_channel_identifier" });

Preview/download media

Download the file attached to a message. This will return a temporary link that can be used by channel members to download the file. This link is only valid for 5 minutes after which a new temporary link will need to be requested.

Actions.invokeAction("DownloadMedia", { message: message, channelSid: "unique_channel_identifier" });

Send Multiple Files

Only one file can be sent at a time. You can repeat the attachment process to send multiples or compress the files you wish to send into a single file. Note that if you do this you must allow the chosen extension to be sent (e.g. Zip) in your configuration file.

Additionally, you must send messages and files separately. If you enter text into the message input element, the Webchat interface will disable the attachment button. If you select a file, you cannot enter any text.

Sending / Receiving attachments via Programmable Chat REST API or SDK

The Attachments feature is built on Programmable Chat media support capabilities. If you have built a custom chat client on Twilio Programmable Chat, you can still use attachment support for agents in Flex UI. All media messages posted in the channel will be rendered in Flex UI for the agent as attachments.

Security and Compliance

Flex Media Support is GDPR compliant. This means:

  • Metadata logs that contain PII are deleted within 7 days of creation.
  • You can use the Programmable Chat API to delete the message content and associated media.

Both the agent (Flex UI) and customer (Flex web chat UI) must enable attachments in order to send and receive files. If only one side is enabled, the other will not be able to view the attachments received.

Finally, Flex does not handle any virus scanning or content filtering. As this feature is built on Programmable Chat media support capabilities, you can use your inhouse implementation to do additional validation of the sent media messages using Programmable Chat webhooks.

Known issues / limitations

  • Supervisor cannot download attachments when monitoring a live chat.
  • Supervisor cannot download attachments from the Insights transcript of a past chat.
  • Customers will not see an error if the file they have selected doesn’t meet the size or type restrictions.
  • It is not possible to copy and paste or drag files into the message input field.
  • Studio flow does not recognize media messages, so automated responses or “Send to Flex” widget will not be triggered by them
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 Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

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

Thanks for your feedback!