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.

const response1 = await channel.sendImage(
  file1,
  file1.name,
  file1.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`Image upload: ${pct}%`);
    },
  },
);

const response2 = await channel.sendFile(
  file2,
  file2.name,
  file2.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`File upload: ${pct}%`);
    },
  },
);

await channel.sendMessage({
  text: "Check these out",
  attachments: [
    {
      type: "image",
      asset_url: response1.file,
      thumb_url: response1.file,
    },
    {
      type: "file",
      asset_url: response2.file,
      title: file2.name,
    },
  ],
});

val channelClient = client.channel("messaging", "general")

// Upload an image
channelClient.sendImage(imageFile).enqueue { result ->
  if (result is Result.Success) {
    val imageUrl = result.value.file
    val attachment = Attachment(
      type = "image",
      imageUrl = imageUrl,
    )
    val message = Message(attachments = mutableListOf(attachment))
    channelClient.sendMessage(message).enqueue { /* ... */ }
  }
}

// Upload a file with progress tracking
channelClient.sendFile(
  file,
  object : ProgressCallback {
    override fun onSuccess(url: String?) {
      // File uploaded successfully
    }
    override fun onError(error: Error) {
      // Handle error
    }
    override fun onProgress(bytesUploaded: Long, totalBytes: Long) {
      // Update progress UI
    }
  }
).enqueue()

ChannelClient channelClient = client.channel("messaging", "general");

// Upload an image
channelClient.sendImage(imageFile).enqueue(result -> {
  if (result.isSuccess()) {
    String imageUrl = result.data().getFile();
    Attachment attachment = new Attachment();
    attachment.setType("image");
    attachment.setImageUrl(imageUrl);

    Message message = new Message();
    message.getAttachments().add(attachment);
    channelClient.sendMessage(message).enqueue(res -> { /* ... */ });
  }
});

// Upload a file with progress tracking
channelClient.sendFile(file, new ProgressCallback() {
  @Override
  public void onSuccess(@NotNull String url) {
    // File uploaded successfully
  }
  @Override
  public void onError(@NotNull ChatError error) {
    // Handle error
  }
  @Override
  public void onProgress(long bytesUploaded, long totalBytes) {
    // Update progress UI
  }
}).enqueue();

let channelId = ChannelId(type: .messaging, id: "general")
let channelController = chatClient.channelController(for: channelId)

// Option 1: Send message with local attachment (SDK handles upload)
let imageAttachment = try AnyAttachmentPayload(
  localFileURL: localImageUrl,
  attachmentType: .image
)
channelController.createNewMessage(
  text: "Hello",
  attachments: [imageAttachment]
)

// Option 2: Upload first, then attach to message
channelController.uploadAttachment(
  localFileURL: localFileUrl,
  type: .image,
  progress: { value in
    // Track upload progress (0.0 to 1.0)
  },
  completion: { result in
    switch result {
    case .success(let uploadedFile):
      let payload = ImageAttachmentPayload(
        title: nil,
        imageRemoteURL: uploadedFile.remoteURL
      )
      let attachment = AnyAttachmentPayload(payload: payload)
      channelController.createNewMessage(
        text: "Hello",
        attachments: [attachment]
      )
    case .failure(let error):
      // Handle upload error
    }
  }
)

// Option 1: Send message with local attachments (SDK handles upload)
final message = Message(text: 'Hello', attachments: [
  Attachment(
    type: 'image',
    file: AttachmentFile(path: 'imagePath/imageName.png', size: 1024),
  ),
]);
await channel.sendMessage(message);

// Option 2: Upload first, then attach to message
await client.sendImage(
  image,
  channelId,
  channelType,
  onSendProgress: (sent, total) {
    // Update progress UI
  },
).then((response) {
  final imageUrl = response.file;
  final message = Message(attachments: [
    Attachment(type: 'image', imageUrl: imageUrl),
  ]);
  return client.sendMessage(message, channelId, channelType);
});

var imageBytes = File.ReadAllBytes("path/to/image.jpg");
var imageUploadResponse = await channel.UploadImageAsync(imageBytes, "image.jpg");
var imageUrl = imageUploadResponse.FileUrl;

var fileBytes = File.ReadAllBytes("path/to/document.pdf");
var fileUploadResponse = await channel.UploadFileAsync(fileBytes, "document.pdf");
var fileUrl = fileUploadResponse.FileUrl;

// Upload multiple images in parallel
const promises = [
  channel.sendImage(
    fs.createReadStream("./image1.jpg"),
    "image1.jpg",
    "image/jpeg",
    { id: "user-id" },
  ),
  channel.sendImage(
    fs.createReadStream("./image2.jpg"),
    "image2.jpg",
    "image/jpeg",
    { id: "user-id" },
  ),
];

const results = await Promise.all(promises);

const attachments = results.map((response) => ({
  type: "image",
  thumb_url: response.file,
  asset_url: response.file,
}));

await channel.sendMessage({
  text: "Check out these images",
  attachments,
});

const fileRes = await channel.sendFile(
  fs.createReadStream("./report.pdf"),
  "report.pdf",
  "application/pdf",
  { id: "user-id" },
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`File upload: ${pct}%`);
    },
  },
);

await channel.sendMessage({
  text: "Here is the report",
  attachments: [{ type: "file", asset_url: fileRes.file, title: "report.pdf" }],
});

// Upload an image to the channel
// Note: actual file upload uses multipart form data
$response = $client->uploadChannelImage("messaging", "general", new Models\UploadChannelRequest(
    // file upload parameters
));

// Upload image
var imgResp = await chat.UploadChannelImageAsync("messaging", channelId,
    new UploadChannelRequest
    {
        File = "/path/to/image.png",
        User = new OnlyUserID { ID = userId }
    });

// Upload file
var fileResp = await chat.UploadChannelFileAsync("messaging", channelId,
    new UploadChannelFileRequest
    {
        File = "/path/to/file.pdf",
        User = new OnlyUserID { ID = userId }
    });

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.

const { file: imageUrl } = await client.uploadImage(
  imageFile,
  imageFile.name,
  imageFile.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`Image: ${pct}%`);
    },
  },
);

// Example: use the image URL as a user avatar
await client.partialUpdateUser({
  id: userId,
  set: { image: imageUrl },
});

val client = ChatClient.instance()

// Upload an image
val uploadResult = client.uploadImage(
  file = imageFile,
  progressCallback = progressCallback,
).await()

when (uploadResult) {
  is Result.Success -> {
    val imageUrl = uploadResult.value.file
    // Use the URL (e.g., update user avatar)
    client.updateUser(user.copy(image = imageUrl)).await()
  }
  is Result.Failure -> {
    // Handle error
  }
}

let channelId = ChannelId(type: .messaging, id: "general")
let channelController = chatClient.channelController(for: channelId)

channelController.uploadAttachment(
  localFileURL: imageLocalFileUrl,
  type: .image,
  progress: { progressValue in
    // Track upload progress (0.0 to 1.0)
  },
  completion: { result in
    switch result {
    case .success(let uploadedFile):
      // Use the URL (e.g., update user avatar)
      chatClient.currentUserController().updateUserData(
        imageURL: uploadedFile.remoteURL
      )
    case .failure(let error):
      // Handle upload error
    }
  }
)

final client = StreamChatClient('api-key');

// Upload an image
final image = AttachmentFile(path: 'imagePath/image.png', size: 1024);
final response = await client.uploadImage(
  image,
  onUploadProgress: (count, total) {
    // Update progress UI
  },
);

final imageUrl = response.file;
// Use the URL (e.g., update user avatar)
final user = User(id: 'user-id', image: imageUrl);
await client.updateUser(user);

// Uploading standalone files via a client-level endpoint is not yet available in the Unity SDK.
// Please let us know if you'd like this feature implemented: https://github.com/GetStream/stream-chat-unity/issues
// As a workaround, upload via channel.UploadImageAsync / channel.UploadFileAsync
// and reuse the returned URL when upserting a user with Client.UpsertUsersAsync.

import fs from "fs";
// const fs = require("fs");

const { file: imageUrl } = await client.uploadImage(
  fs.createReadStream("./avatar.jpg"),
  "avatar.jpg",
  "image/jpeg",
  { id: userId },
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`Image: ${pct}%`);
    },
  },
);

// Example: use the image URL as a user avatar
await client.partialUpdateUser({
  id: userId,
  set: { image: imageUrl },
});

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.

// Delete from channel
channelClient.deleteFile("file-url").enqueue()
channelClient.deleteImage("image-url").enqueue()

// Delete standalone file
client.deleteFile("file-url").enqueue()
client.deleteImage("image-url").enqueue()

// Delete from channel
channelController.deleteFile(url: "remote-url")
channelController.deleteImage(url: "remote-url")

// Delete standalone file
ChatClient.shared.deleteAttachment(remoteUrl: "remote-url") { error in
  // Handle deletion error
}

// Delete from channel
await channel.deleteFile('file-url');
await channel.deleteImage('image-url');

// Delete standalone file
await client.removeFile('file-url');
await client.removeImage('image-url');

channel.DeleteChannelFile(ctx, &getstream.DeleteChannelFileRequest{
    Url: getstream.PtrTo(url),
})
channel.DeleteChannelImage(ctx, &getstream.DeleteChannelImageRequest{
    Url: getstream.PtrTo(url),
})

chat.deleteChannelImage(channelType, channelId, DeleteChannelImageRequest.builder()
    .Url(url)
    .build()).execute();
chat.deleteChannelFile(channelType, channelId, DeleteChannelFileRequest.builder()
    .Url(url)
    .build()).execute();

File Requirements

Images

Requirement	Value
Supported formats	BMP, GIF, JPEG, PNG, WebP, HEIC, HEIC-sequence, HEIF, HEIF-sequence, SVG+XML
Maximum file size	100 MB

Other Files

Requirement	Value
Supported formats	All file types are allowed by default. Different clients may handle certain types differently.
Maximum file size	100 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:

Setting	Effect
`allowed_file_extensions`	Only these extensions are accepted. Everything else is rejected.
`blocked_file_extensions`	These extensions are rejected. Everything else is accepted.
`allowed_mime_types`	Only these MIME types are accepted. Follows the `type/subtype` format.
`blocked_mime_types`	These MIME types are rejected.
`size_limit`	Maximum 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.

Access Control and Link Expiration

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

Behavior	Description
Access control	URLs are signed and only accessible by channel members
Link expiration	URLs expire after 14 days
Automatic refresh	Message 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 refresh	Call `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.

Parameter	Type	Values	Description
w	number		Width in pixels
h	number		Height in pixels
resize	string	clip, crop, scale, fill	Resizing mode
crop	string	center, top, bottom, left, right	Crop 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.

class CustomCDN: CDNClient {
  static var maxAttachmentSize: Int64 { 20 * 1024 * 1024 }

  func uploadAttachment(
    _ attachment: AnyChatMessageAttachment,
    progress: ((Double) -> Void)?,
    completion: @escaping (Result<URL, Error>) -> Void
  ) {
    // Upload to your CDN
    // Call progress() to report upload progress
    // Call completion() with the result
  }
}

// Assign to ChatClientConfig
config.customCDNClient = CustomCDN()

final client = StreamChatClient(
  'api-key',
  attachmentFileUploaderProvider: (httpClient) => MyCustomFileUploader(httpClient),
);

// Upload to your CDN and obtain the file URL
var fileUrl = "file-url-to-your-cdn";

await channel.SendNewMessageAsync(new StreamSendMessageRequest
{
    Text = "Message with file attachment",
    Attachments = new List<StreamAttachmentRequest>
    {
        new StreamAttachmentRequest
        {
            AssetUrl = fileUrl,
        }
    }
});

Messages Overview

Threads & Replies