Get Presigned URLs (S3 Upload)

Get short-lived S3 presigned URLs so your chat package / client can upload files directly to storage — without sending file bytes through the RealtimeX API server.

For each file you request, the API returns an uploadUrl (PUT the file here) and a fileUrl (the permanent URL to use in messages, profiles, or group images after upload succeeds).

Use Get Presigned URLs when:

• A chat user attaches an image, video, audio, or document in the composer.
• They update a profile avatar or group image from the chat SDK.
• You need to upload several files in one batch (request multiple entries in files).
• You want direct-to-S3 uploads for better performance and smaller API payload size.

Part of the Chat Uploads flow for the chat package / SDK. Requires a chat user Access Token and tenant headers. Presigned URLs expire quickly (see X-Amz-Expires in the URL, often ~300 seconds) — upload promptly after you receive them.

Follow these steps in your chat client every time a user sends or attaches a file. Skipping the PUT step will leave you with a fileUrl that has no file behind it.

Guidance for product and SDK implementers so uploads feel reliable for people using the chat app:

• Show progress — while PUT is in flight, show an upload indicator on the attachment bubble or composer. Do not mark the message as sent until both S3 upload and your message API succeed.
• Validate before requesting URLs — check file size, type, and count in the UI first. Avoid calling this endpoint for empty selections or unsupported MIME types.
• Match Content-Type — the fileType you send in the request and the Content-Type header on the PUT must match the real file MIME type, or S3 may reject the upload.
• Upload before sending the chat message — put fileUrl into the message only after PUT returns success. Otherwise peers open a broken attachment link.
• Handle expiry — if the user stays on a slow network and the presigned URL expires, request new URLs and retry the PUT. Do not reuse an expired uploadUrl.
• Allow cancel / retry — if the user cancels mid-upload, discard the pending message draft. On failure, offer Retry without creating duplicate messages.
• Keep order — data array items align with your request files array order. Map each response pair back to the correct local file.

Example requesting presigned URLs for an image and a PDF in one call:

{
  "files": [
    {
      "filename": "profile-photo.png",
      "fileType": "image/png"
    },
    {
      "filename": "report.pdf",
      "fileType": "application/pdf"
    }
  ]
}

data is an array aligned with your files input. Each entry has:

{
  "success": true,
  "message": "Presigned URLs generated successfully",
  "data": [
    {
      "uploadUrl": "https://example.amazonaws.com/uploads/images/avatar-7f8c9d12.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE123456789%2F20260719%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260719T134500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=9f8a7b6c5d4e3f210987654321abcdef1234567890abcdef1234567890abcdef",
      "fileUrl": "https://example.com/avatar-7f8c9d12.png"
    },
    {
      "uploadUrl": "https://example.amazonaws.com/uploads/files/report-7f8c9d12.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE123456789%2F20260719%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260719T134500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=9f8a7b6c5d4e3f210987654321abcdef1234567890abcdef1234567890abcdef",
      "fileUrl": "https://example.com/report-7f8c9d12.pdf"
    }
  ],
  "error": null
}

This API does not accept file bytes. After you receive uploadUrl, upload directly to S3 with PUT:

// After you receive uploadUrl + fileUrl from this API:
const file = selectedFile; // File from <input type="file"> or picker

const putResponse = await fetch(uploadUrl, {
  method: "PUT",
  headers: {
    "Content-Type": file.type, // must match fileType you sent above
  },
  body: file,
});

if (!putResponse.ok) {
  throw new Error("Upload to storage failed");
}

// Use permanent fileUrl in your chat message / profile payload:
// e.g. { type: "image", attachmentUrl: fileUrl }

Do not attach Authorization headers from RealtimeX when calling uploadUrl — authentication is already embedded in the query string signature. Only send the file body and the correct Content-Type.

This endpoint fails when the token is missing or the files array is empty. S3 PUT errors happen separately after you receive the URLs.

{
  "success": false,
  "message": "No files provided",
  "data": null,
  "error": "No files provided"
}

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

• Request URLs only for files the user has confirmed — then PUT immediately while the signature is valid.
• Never log full uploadUrl values in production (they are temporary credentials in URL form).
• Prefer batching a small number of attachments in one files request when the user multi- selects media.
• After upload, persist fileUrl only — not the expired uploadUrl.
• Always send tenant headers with the chat user Bearer token over HTTPS when calling this API.