Image and File Uploads

Stream Chat allows you to upload images, videos, and other files to the Stream CDN or your own CDN. Uploaded files can be used as message attachments, user avatars, or channel images.

Stream's UI SDKs (React, React Native, Flutter, SwiftUI, Jetpack Compose, etc.) handle file uploads automatically through their message composer components. The upload process, progress tracking, and attachment handling are built into these components. Use the methods described on this page only if you need custom upload behavior or are building a custom UI.

Uploading Files to a Channel

Files uploaded to a channel can be attached to messages. You can either upload a file first and then attach it to a message, or let the SDK handle the upload when sending a message with attachments.

// Uploading and sending are separate steps. Upload first, then put the resulting
// attachment in FMessage::Attachments and send that message.
//
// The SDK takes bytes rather than a path, so the choice of file picker, and the
// platform differences that come with it, stay in your app.
Channel->UploadImage(
  TEXT("image.jpg"),
  ImageBytes,
  [Channel](const FAttachment& Attachment)
  {
    FMessage Message{TEXT("Check this out")};
    Message.Attachments.Add(Attachment);
    Channel->SendMessage(Message);
  });

// Anything that is not an image goes through UploadFile. Prefer UploadImage for
// images: the backend recognises them, may generate a thumbnail, and clients
// render them inline.
Channel->UploadFile(
  TEXT("document.pdf"),
  FileBytes,
  [Channel](const FAttachment& Attachment)
  {
    FMessage Message;
    Message.Attachments.Add(Attachment);
    Channel->SendMessage(Message);
  });

// Both are also available as latent Blueprint nodes: Upload File and Upload Image.

Uploading Standalone Files

Files not tied to a specific channel can be used for user avatars and channel images, i.e. stored in the image or image_url field of a user or channel object.

Like channel attachments, standalone Stream CDN URLs expire (see Access Control and Link Expiration). They are refreshed automatically only when stored in the image or image_url field of a user or channel object, which are re-signed when the user or channel is retrieved (e.g. when querying users or channels). A Stream CDN URL kept anywhere else (a different custom field, your own database, etc.) is not refreshed and stops working once it expires. For those use cases, do not use the Stream CDN.

// Uploading outside a channel is not yet available in the Unreal SDK.
// Please let us know if you'd like this feature implemented: https://github.com/GetStream/stream-chat-unreal/issues
// As a workaround, upload through UChatChannel::UploadImage and reuse the returned
// URL when you update the user or channel.
Channel->UploadImage(
  TEXT("avatar.jpg"),
  ImageBytes,
  [](const FAttachment& Attachment)
  {
    const FString ImageUrl = Attachment.GetUrl();
    // Store ImageUrl in the user's or channel's image field
  });

Deleting Files

Delete uploaded files to free storage space. Deleting a file from the CDN does not remove it from message attachments that reference it.

// Routed to the image or the file endpoint depending on the attachment, so you do
// not have to remember which one it was uploaded through.
Channel->DeleteAttachment(
  Attachment,
  [](const bool& bSuccess)
  {
    // Deleted
  });

// Also available as a latent Blueprint node: Delete Attachment.

File Requirements

Images

RequirementValue
Supported formatsBMP, GIF, JPEG, PNG, WebP, HEIC, HEIC-sequence, HEIF, HEIF-sequence, SVG+XML
Maximum file size100 MB

Other Files

RequirementValue
Supported formatsAll file types are allowed by default. Different clients may handle certain types differently.
Maximum file size100 MB

Configuring Allowed File Types

Stream allows every extension and MIME type by default. Your app can be configured to be more restrictive through file_upload_config and image_upload_config:

SettingEffect
allowed_file_extensionsOnly these extensions are accepted. Everything else is rejected.
blocked_file_extensionsThese extensions are rejected. Everything else is accepted.
allowed_mime_typesOnly these MIME types are accepted. Follows the type/subtype format.
blocked_mime_typesThese MIME types are rejected.
size_limitMaximum accepted size in bytes. 0 falls back to the 100 MB default.

Set them in the Dashboard under Chat Overview > Upload Configuration, or with the App Settings endpoint.

Uploads Rejected by Your Configuration

Upload restrictions live on the app, not on the device. A client SDK cannot read or change them, so the same limits apply to every upload from every SDK, and a client integration has to handle the rejection rather than prevent it.

Rejection happens at upload time, before the message is sent. The upload call fails and returns no attachment URL, so the message never gets the attachment. Handle the failure and tell the user which rule they hit. A file over the size limit returns HTTP 413 with Stream code 22, listed in API error codes.

If your app restricts uploads, mirror the same rules in your own file picker. Users get immediate feedback instead of waiting for an upload to fail.

Stream CDN URLs include a signature that validates access to the file. Only channel members can access files uploaded to that channel.

BehaviorDescription
Access controlURLs are signed and only accessible by channel members
Link expirationURLs expire after 14 days
Automatic refreshMessage attachment links are refreshed when messages are retrieved (e.g., when querying a channel). Standalone uploads are refreshed only when stored in image / image_url on a user or channel object, and re-signed when that user or channel is retrieved.
Manual refreshCall getMessage to retrieve fresh URLs for expired attachments

To check when a link expires, examine the Expires query parameter in the URL (Unix timestamp).

Image Resizing

Append query parameters to Stream CDN image URLs to resize images on the fly.

ParameterTypeValuesDescription
wnumberWidth in pixels
hnumberHeight in pixels
resizestringclip, crop, scale, fillResizing mode
cropstringcenter, top, bottom, left, rightCrop anchor position

Images can only be resized if the source image has 16,800,000 pixels or fewer. An image of 4000x4000 pixels (16,000,000) would be accepted, but 4100x4100 (16,810,000) would fail.

Resized images count against your storage quota.

Using Your Own CDN

All SDKs support custom CDN implementations. Implement a custom file uploader to use your own storage solution.

// The Unreal SDK has no custom uploader hook. Nothing about sending a message
// requires the URL to have come from Stream, so upload to your own CDN and then
// build the attachment yourself.
FAttachment Attachment;
Attachment.Type = EAttachmentType::Image;
Attachment.ImageUrl = TEXT("file-url-to-your-cdn");
Attachment.Title = TEXT("image.jpg");

FMessage Message{TEXT("Message with file attachment")};
Message.Attachments.Add(Attachment);
Channel->SendMessage(Message);