A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
SPDX-License-Identifier: AGPL-3.0-or-later
title: Attachment uploads description: Upload message attachments and stream previews before you use them.
You can send attachments as files[n] parts in a multipart message, or upload them first and attach them by their upload key (upload_filename). Uploading first takes four steps.
- Request an upload plan.
- Send the bytes to its upload URLs.
- Complete the upload if it is multipart.
- Attach the upload by its upload key when you create or edit a message or start a thread.
Uploading first needs presigned_attachment_uploads set to true in instance features. When it is off, the plan and completion requests return 403 FEATURE_TEMPORARILY_DISABLED.
Choose how to upload
Each file can be up to the max_attachment_file_size limit. A bot gets the lower of that limit and max_bot_attachment_file_size, which is 52428800 bytes (50 MiB) unless the instance admins change it.
In a multipart message, Fluxer checks each file part while it arrives. When a part goes over the limit, the request fails with 400 FILE_SIZE_TOO_LARGE. When Content-Length is larger than every allowed file plus the rest of the message, the request fails with 413 FILE_SIZE_TOO_LARGE and Fluxer saves none of it. In both cases Fluxer reads up to 64 MiB of the rest of the body before it answers. If more is left, it answers right away and closes the connection, and some HTTP clients then report a connection reset instead of the response. Check file sizes against the limit before you send to avoid this.
When the instance is already streaming many files, a file part can wait up to 10 seconds and then fail with 503 and a Retry-After header. A multipart request also has to finish within the instance's request timeout, which is 120 seconds by default.
The web and desktop apps upload files first whenever the instance has presigned_attachment_uploads on, and bots should do the same for large files. The bytes go to storage or the upload relay in parts of 10 MiB or more, and the API request timeout doesn't apply to them.
Request an upload plan
Call Request attachment upload URLs with up to 10 files, each with its exact byte count. Each file in the plan has an upload_mode that decides which fields it gets.
| Value | When | Added fields |
|---|---|---|
| singlepart | A file_size of at most 10485760 bytes (10 MiB) |
upload_url |
| multipart | A file_size above 10485760 bytes |
upload_id, part_size and parts |
Each parts entry has a part_number starting at 1 and its own upload_url.
Upload the bytes
Send a PUT to each upload_url exactly as returned, with no Authorization header. Fluxer picks content_type from the file name, and a singlepart upload must send the whole file with it as Content-Type. A multipart upload sends each part to its own URL, with exactly part_size bytes in every part except the last.
An upload URL points to storage or to the upload relay, and it expires after the time below.
| Upload URL | Lifetime |
|---|---|
| Storage, singlepart | 5 minutes |
| Storage, multipart part | 1 hour |
| Upload relay | 15 minutes by default, and the instance can change it |
Keep upload URLs out of logs, because anyone who has one can upload to it until it expires. When a URL expires, request a new plan and upload the file again.
Complete a multipart upload
After every part has uploaded, call Complete attachment upload with the upload_filename and upload_id of up to 10 uploads. Fluxer checks permissions and the file size limit again. If completion fails because no parts arrived, the parts are too large or storage can't finish the upload, Fluxer cancels the upload and you need a new plan.
Attach the upload
Put the upload_filename in a pre-uploaded attachment when you call Create message, Modify message or Start thread in a forum or media channel.
An upload key works once, for the user and channel that requested it. Using a key that belongs to someone else, was requested for another channel or was already used returns 400 INVALID_FORM_BODY with UPLOADED_ATTACHMENT_NOT_FOUND. A key whose bytes never uploaded returns the same error with FILE_NOT_FOUND.
Stream previews
A stream preview is a JPEG of at most 1000000 bytes that shows for a voice stream. You can upload it with either of these Streams API endpoints.
- Upload stream preview takes the image as canonical base64 in JSON, using the standard alphabet with padding. Other encodings return 400
INVALID_STREAM_THUMBNAIL_PAYLOAD. - Create stream preview upload URL returns a URL. Send the JPEG to it with
PUTand the returnedcontent_typebeforeexpires_at, and keep it at or undermax_bytes.
A preview expires one day after you upload it or request its upload URL, and after that Get stream preview returns 404.