Customizing Chat Attachment Behavior

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.
  • Configureboth 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, and logs with PII data are deleted in 7 days. You can also use the Programmable Chat API to delete the media message.

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:

Thanks for rating this page!

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

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