File Uploads

The channel.sendImage and channel.sendFile methods make it easy to upload files.

How to upload a file or image

1. Send image or file to Stream using the sendImage or sendFile methods. It is recommended to also include attachment type: to ensure proper handling by front end. (e.g. image, video, url)

2. This will return a signed URL that points to your file on the Stream CDN. If the file is an image, it will be served inline with HTTP requests, or as an attachment otherwise.

3. Send message with URL as attachment.

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

// Upload an image without detailed progress
channelClient.sendImage(imageFile).enqueue { result ->
  if (result.isSuccess) {
    // Successful upload, you can now attach this image
    // to a message that you then send to a channel
    val imageUrl = result.data().file
    val attachment = Attachment(
      type = "image",
      imageUrl = imageUrl,
    )
    val message = Message(
      attachments = mutableListOf(attachment),
    )
    channelClient.sendMessage(message).enqueue { /* ... */ }
  }
}

// Upload a file, monitoring for progress with a ProgressCallback
channelClient.sendFile(
  anyOtherFile,
  object : ProgressCallback {
    override fun onSuccess(url: String?) {
      val fileUrl = url
    }

    override fun onError(error: ChatError) {
      // Handle error
    }

    override fun onProgress(bytesUploaded: Long, totalBytes: Long) {
      // You can render the uploading progress here.
    }
  }
).enqueue() // No callback passed to enqueue, as we'll get notified above anyway

// Capture a file using the HTML5 input element
// or a similar feature in your preferred web framework.
//
// Example: <input type="file" onChange={getUrl}></input>

async function getUrl(event) {
  const files = event.target.files;
  const response = await channel.sendImage(files[0]);
}

import StreamChat

/// 1: Create a `ChannelId` that represents the channel you want to send a message to.
let channelId = ChannelId(type: .messaging, id: "general")

/// 2: Use the `ChatClient` to create a `ChatChannelController` with the `ChannelId`.
let channelController = chatClient.channelController(for: channelId)

/// 3: Call `ChatChannelController.createNewMessage` to create the message.
channelController.createNewMessage(
  text: "Hello",
  attachments: [try! .init(localFileURL: URL(string: "./my_image.png")!, attachmentType: .image)]
)

$user = [ 'id' => 'jenny' ];

$response = $channel->sendImage('http://bit.ly/2O35mws', 'image.jpeg', $user);

final client = StreamChatClient('api-key');
var attachment = Attachment();

// Upload an image without monitoring send progress
client.sendImage(image, channelId, channelType).then((response) {
 // Successful upload, you can now attach this image
 // to an message that you then send to a channel
 final imageUrl = response.file;
 attachment = attachment.copyWith(
  type: 'image',
  imageUrl: imageUrl,
 );
 final message = Message(attachments: [attachment]);
 client.sendMessage(message, channelId, channelType);
}).catchError((error, stk) {
 // Handle error
});

// Upload an file, monitoring the progress with a onSendProgress callback
await client.sendFile(
 file,
 channelId,
 channelType,
 onSendProgress: (sent, total) {
  // Handle the send progress
  attachment = attachment.copyWith(
   uploadState: UploadState.inProgress(
    uploaded: sent,
    total: total,
    ),
  );
 },
 ).then((response) {
  // Successful upload, you can now attach this file
  // to an message that you then send to a channel
  final fileUrl = response.file;
  attachment = attachment.copyWith(
   type: 'file',
   assetUrl: fileUrl,
   uploadState: UploadState.success(),
  );
  final message = Message(attachments: [attachment]);
  client.sendMessage(message, channelId, channelType);
 }).catchError((error, stk) {
  // Handle error
  attachment = attachment.copyWith(
   uploadState: UploadState.failed(error: error),
  );
 });

// Alternatively you can call the sendMessage directly on the channel
// which will automatically handle all the upload process of the provided
// attachments.
final channel = client.channel(channelType, id: channelId);

// Creating a message object with multiple local attachments
final message = Message(text: 'Hello', attachments: [
 Attachment(
  type: 'image',
  file: AttachmentFile(path: 'imagePath/imageName.png'),
 ),
 Attachment(
  type: 'file',
  file: AttachmentFile(path: 'filePath/fileName.pdf'),
 ),
]);

// Sending the message to the channel
await channel.sendMessage(message);

const promises = [
  channel.sendImage(
    fs.createReadStream("./helloworld.jpg"),
    "hello_world1.jpg",
    "hello_world1/jpg",
    { id: "sara" }, // inform user id if server-side auth
  ),
  channel.sendImage(
    fs.createReadStream("./helloworld.jpg"),
    "hello_world2.jpg",
    "hello_world2/jpg",
    { id: "sara" }, // inform user id if server-side auth
  ),
];

const results = await Promise.all(promises);

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

const response = await channel.sendMessage({
  text: "Check out what I have uploaded in parallel",
  attachments,
});

expect(response.message.attachments).to.equal(attachments);

// Not yet supported in the Unreal SDK

channel.send_image(
  "[http://bit.ly/2O35mws](http://bit.ly/2O35mws)", "helloworld.jpg", {"id": "jenny"}, "image/jpeg",
)

channel.send_image(
  "[http://bit.ly/2O35mws](http://bit.ly/2O35mws)", "helloworld.jpg", {id: "jenny"}, "image/jpeg",
)

var jpegFile = File.ReadAllBytes("helloworld.jpg");

await messageClient.UploadImageAsync(channel.Type, channel.Id, user, jpegFile, "helloworld.jpg");

// Get file byte array however you want e.g. Addressables.LoadAsset, Resources.Load, etc.
var sampleFile = File.ReadAllBytes("path/to/file");
var fileUploadResponse = await channel.UploadFileAsync(sampleFile, "my-file-name");
var fileWebUrl = fileUploadResponse.FileUrl;

// Get image byte array however you want e.g. Addressables.LoadAsset, Resources.Load, etc.
var sampleImage = File.ReadAllBytes("path/to/file");
var imageUploadResponse = await channel.UploadImageAsync(sampleFile, "my-image-name");
var imageWebUrl = imageUploadResponse.FileUrl;

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

// Upload an image without detailed progress
channelClient.sendImage(imageFile).enqueue(result -> {
  if (result.isSuccess()) {
    // Successful upload, you can now attach this image
    // to a message that you then send to a channel
    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, monitoring for progress with a ProgressCallback
channelClient.sendFile(anyOtherFile, new ProgressCallback() {
  @Override
  public void onSuccess(@NotNull String file) {
    String fileUrl = file;
  }

  @Override
  public void onError(@NotNull ChatError error) {
    // Handle error
  }

  @Override
  public void onProgress(long bytesUploaded, long totalBytes) {
    // You can render the uploading progress here
  }
}).enqueue(); // No callback passed to enqueue, as we'll get notified above anyway

// Backend SDK
String pngFileUrl =
  Message.uploadImage("messaging", "general", userId, "image/png")
    .file(new File("./helloworld.png"))
    .request()
    .getFile();
Message.send("messaging", "general")
  .message(
    MessageRequestObject.builder()
      .text("Check out what I have uploaded in parallel")
      .attachment(
        AttachmentRequestObject.builder()
          .type("image")
          .assetURL(pngFileUrl)
          .thumbURL(pngFileUrl)
          .build())
      .userId(userId)
      .build())
  .request();

Deleting Files and Images

We expose two methods for deleting files and images, channel.deleteImage and channel.deleteFile

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

// Deletes the image
channelClient.deleteImage("{{ url of uploaded image }}").enqueue()

// Deletes the file
channelClient.deleteFile("{{ url of uploaded file }}").enqueue()

// Delete File
await channel.deleteFile(fileURL);

// Delete Image
await channel.deleteImage(imageURL);

// Not yet supported in the Unreal SDKChannelClient channelClient = client.channel("messaging", "general");

// Deletes the image
channelClient.deleteImage("{{ url of uploaded image }}").enqueue();

// Deletes the file
channelClient.deleteFile("{{ url of uploaded file }}").enqueue();

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

// Deletes the image
channelClient.deleteImage("{{ url of uploaded image }}").enqueue();

// Deletes the file
channelClient.deleteFile("{{ url of uploaded file }}").enqueue();

// Backend SDK
Message.deleteImage(channelType, channelId, url).request();
Message.deleteFile(channelType, channelId, url).request();

// Delete file
$channel->deleteFile($url);

// Delete image
$channel->deleteImage($url);

# Delete a file
channel.delete_file(url)

# Delete an image
channel.delete_image(url)

# Delete a file
channel.delete_file(url)

# Delete an image
channel.delete_image(url)

// Delete File
channel.DeleteFile(ctx, url)

// Delete Image
channel.DeleteImage(ctx, url)

// Delete File
await messageClient.DeleteFileAsync("<channel-type>", "<channel-id>", url);

// Delete Image
await messageClient.DeleteImageAsync("<channel-type>", "<channel-id>", url);

await channel.DeleteFileOrImageAsync("file-url");

channelController.deleteFile(url: "remote-url") { error in
  // …
}
channelController.deleteImage(url: "remote-url") { error in
  // …
}

Requirements for Images

• Stream supported image types are: image/bmp, image/gif, image/jpeg, image/png, image/webp, image/heic, image/heic-sequence, image/heif, image/heif-sequence, image/svg+xml.

• You can set a more restrictive list for your application if needed.

• The maximum file size is 100MB.

Requirements for Files

• Stream will not block any file types from uploading, however, different clients may handle different types differently or not at all.

• You can set a more restrictive list for your application if needed.

• The maximum file size is 100MB.

How to Allow/Block file extensions

Stream will allow any file extension. If you want to be more restrictive for an application, this is can be set via API or by logging into your dashboard.

• To update via the dashboard, login and go to the Chat Overview page >> Upload Configuration

• API updates are made using UpdateAppSettings, see the App Settings page

Image resizing

You can automatically resize an image appending query parameters to a valid image link stored on the Stream CDN.

There are four supported params - all of them are optional and can be used interchangeably:

Access control and link expiration

The Stream CDN URL returned during the upload contains a signature that validates the access to the file it points to. Only the members of a channel a file was uploaded to can see the attachment and its unique, signed link. Links can only be accessed with a valid signature, which also protects against enumeration attacks.

Whenever messages containing your attachments are retrieved (i.e., when querying a channel), the attachment links will contain a new, fresh signature.

A single Stream CDN URL expires after 14 days, after which its signature will stop working and the link won’t be valid anymore. You can check when a link will expire by comparing the current time with the Unix timestamp in the Expires parameter of the link’s query: https://us-east.stream-io-cdn.com/0000/images/foo.png?…&Expires=1602666347&…

As explained above, all operations that return messages will refresh links automatically, but if you are storing a message containing an expired link you can perform a getMessage call to retrieve fresh links for its attachments.

Using Your Own CDN

All 5 SDKs make it easy to use your own CDN for uploads. The code examples below show how to change where files are uploaded:

// Set a custom FileUploader implementation when building your client
val client = ChatClient.Builder("{{ api_key }}", context)
  .fileUploader(MyFileUploader())
  .build()
}

// react sdk
<MessageInput
  doFileUploadRequest={(file, channel) => {
    return client.sendFile('https://customcdn.url', file); // or your custom upload request.
  }}
  doImageUploadRequest={(file, channel) => {
    return client.sendFile('https://customcdn.url', file); // or your custom upload request.
  }}
/>

// react-native sdk
// For more details on file uploads in React Native, refer to https://getstream.io/chat/docs/sdk/reactnative/guides/message-input-customization/#storing-image-and-file-attachment-to-custom-cdn
<Channel
 doDocUploadRequest={(file, channel) =>
  chatClient?.sendFile(
   `${channel._channelURL()}/file`, // replace this with your own cdn url
   file.uri,
   'name_for_file',
  )
 }
 doImageUploadRequest={(file, channel) =>
  chatClient?.sendFile(
   `https://customcdnurl.com`, // replace this with your own cdn url
   file.uri,
   'name_for_file',
  )
 }
/>

// Set a custom FileUploader implementation when building your client
final client = StreamChatClient(
 'api-key',
 attachmentFileUploader: MyFileUploader(),
);

/// Your custom implementation of `CDNClient`.
class CustomCDN: CDNClient {
  static var maxAttachmentSize: Int64 { 20 * 1024 * 1024 }

  func uploadAttachment(
   _ attachment: AnyChatMessageAttachment,
   progress: ((Double) -> Void)?,
   completion: @escaping (Result<URL, Error>) -> Void
  ) {
    if let imageAttachment = attachment.attachment(
     payloadType: ImageAttachmentPayload.self
    ) {
      // Your code to handle image uploading.
      // Don't forget to call `progress(x)` to report back the uploading progress.
      // When the uploading is finished, call the completion block with the result.

    } else if let fileAttachment = attachment.attachment(
     payloadType: FileAttachmentPayload.self
    ) {
      // Your code to handle file uploading.
      // Don't forget to call `progress(x)` to report back the uploading progress.
      // When the uploading is finished, call the completion block with the result.

    } else {
      // Unsupported attachment type
      struct UnsupportedAttachmentType: Error {}
      completion(.failure(UnsupportedAttachmentType()))
    }
  }
}

// Assign your custom CDN client to the `ChatClientConfig` instance you use
// for creating `ChatClient`.
config.customCDNClient = CustomCDN()

// Not yet supported in the Unreal SDK

// Android SDK

// Set a custom FileUploader implementation when building your client
ChatClient client = new ChatClient.Builder("{{ api_key }}", context)
    .fileUploader(new MyFileUploader())
    .build();

// Backend SDK
Message.uploadFile(
    testChannel.getType(),
    testChannel.getId(),
    testUserRequestObject.getId(),
    "text/plain")
  .file(new File(testFileUrl.getFile()))
  .withFileHandler(fileHandler) // Set custom implementation here
  .request();

// Implement your own CDN upload 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,
    }
  }
});