rooms.media API endpoint doesn't create messages - breaks file upload with captions

[a-beleg]

The /api/v1/rooms.media endpoint only uploads files to storage but doesn't create messages in
rooms. This makes it impossible to send media with captions as a single message. Meanwhile,
rooms.upload is marked as deprecated but is the only endpoint that actually works correctly.

The Problem

RocketChat is deprecating rooms.upload in favor of rooms.media, BUT:

• rooms.media: Only uploads file to database, returns URL, does NOT create a message in the room
• rooms.upload: Creates proper message with file + caption (but marked as deprecated)

Current Broken Behavior with rooms.media

  curl --request POST \
    --url http://localhost:3000/api/v1/rooms.media/ROOM_ID \
    --form file=@image.png \
    --form msg="This caption is completely ignored"

Result:

• ✅ File uploaded to database
• ✅ Returns file URL
• ❌ NO message created in room
• ❌ Caption completely ignored
• ❌ Room shows nothing

Expected Behavior

The "new" rooms.media endpoint should:

1. Upload the file
2. Create a message in the specified room
3. Include the caption from msg parameter
4. Show the media with caption as a single message

Why This Is Critical

• You're deprecating the ONLY working endpoint (rooms.upload)
• The "replacement" endpoint (rooms.media) is broken/incomplete
• All integrations using file uploads with captions will break
• There's no working alternative

Test Results Proving the Issue

rooms.media - BROKEN (ignores msg, doesn't create message):

{
   "file": {
     "_id": "68b821adc9d07159776790ba",
     "url": "/file-upload/68b821adc9d07159776790ba/icon.png"
   },
   "success": true
 }

Room shows: NOTHING

rooms.upload - WORKS (but deprecated):

{
   "message": {
     "_id": "zbgZpQDRKvaY9nFu3",
     "msg": "Test caption with media",
     "file": {...},
     "attachments": [...]
   },
   "success": true
 }

Room shows: Message with media and caption

The Ask

Either:

1. Fix rooms.media to actually create messages with captions like rooms.upload does
2. Stop deprecating rooms.upload until rooms.media has feature parity
3. Add a new parameter to rooms.media like createMessage=true to make it create messages

[a-beleg]

{"level":40,"time":"2025-09-03T13:43:34.263Z","pid":1,"hostname":"b0e30d732876","name":"DeprecationWarning","section":"API","msg":"The endpoint "undefined" is deprecated and will be removed on version 8.0.0 ( Please use the alternative(s): rooms.media)"}

[abhinavkrin]

I checked this and this works as expected.

1. When one calls rooms.media, It uploads to the database and returns a file object with _id and url data.

curl --location 'http://localhost:3000/api/v1/rooms.media/<roomId>' \
--header 'X-Auth-Token: <token>' \
--header 'X-User-Id: <userId>' \
--form 'file=@"/paht/to/file"'

You should expect a response:

{
    "file": {
        "_id": "68b955287662d0e96dbef7a7",
        "url": "/file-upload/68b955287662d0e96dbef7a7/stats.png"
    },
    "success": true
}

2. Having done that, we need to call rooms.mediaConfirm to send a message to desired room with the caption and the above uploaded file.

curl --location 'http://localhost:3000/api/v1/rooms.mediaConfirm/GENERAL/<fileIdFromAbove>' \
--header 'X-Auth-Token: <token>' \
--header 'X-User-Id: <userId>' \
--header 'Content-Type: application/json' \
--data '{
    "description": "optional caption,
    "msg": "<optional>"
}'

[a-beleg]

I can confirm that the /api/v1/rooms.mediaConfirm endpoint works as a second step after rooms.media.

Important: The rooms.mediaConfirm endpoint is completely undocumented in the official API documentation. This should be added to the docs as it's the only way to properly send media with captions using the new rooms.media flow.

[abhinavkrin]

Thanks for reporting about the documentation. Should be updated.

[a-beleg]

Limitations discovered:

• Cannot pass customFields object
• Cannot pass alias for bot display name
• Cannot pass bot parameters
• Cannot pass other standard message parameters like tmid, emoji, avatar

[abhinavkrin]

Limitations discovered:

• Cannot pass customFields object
• Cannot pass alias for bot display name
• Cannot pass bot parameters
• Cannot pass other standard message parameters like tmid, emoji, avatar

Are these concerns about the rooms.mediaConfirm endpoint?

[a-beleg]

Key point

The current (but deprecated) rooms.upload endpoint already supports posting media and setting message properties in a single, atomic call — including message-level customFields — so no additional method calls are required for the media to render correctly. Deprecating it without feature parity in the new flow is a regression for integrations that depend on one-shot media posting with enriched message metadata.

By contrast, the new rooms.media → rooms.mediaConfirm sequence increases complexity and, as currently documented, does not expose a way to set message-level custom fields or extended IMessage properties during the upload/confirm flow. The rooms.media docs only list file and msg in the multipart body, with no mention of customFields. If rooms.mediaConfirm is intended to carry these, this is not documented either.

---

Concrete example (docs-compliant customFields)

With rooms.upload, it’s possible to send a file and include message fields in one request.
A typical multipart/form-data body looks like this:

• file → binary file contents
• payloadJson → JSON with message fields, for example:

{
  "msg": "Here is the requested file:",
  "alias": "Support Bot",
  "avatar": "https://example.com/bot-avatar.png",
  "attachments": [
    { "title": "Log file", "title_link": "https://example.com/logs/123" }
  ],
  "customFields": {
    "fromExternalSource": true
  }
}

This pattern preserves atomicity (media + metadata together) and allows consistent rendering and downstream processing based on customFields.

---

Backward-compatibility concern

rooms.upload is scheduled for removal in 8.0.0. Removing it before the new media workflow reaches feature parity will break existing bots, bridges, and middleware that rely on:

• single-call media posting, and
• attaching validated custom metadata (customFields) to messages.

This is a significant functional regression.

---

Path to parity

If the intention is to migrate fully to the new media API, please consider one of the following before removing rooms.upload:

1. Add parity to the new flow
   Allow customFields, alias, avatar, attachments, tmid, etc. to be supplied in either rooms.media or rooms.mediaConfirm, respecting the same validation as chat.postMessage.

2. Delay deprecation
   Keep rooms.upload available until the new endpoints can accept arbitrary IMessage fields and customFields, preserving atomic media+metadata posting.

---

Without one of these, previously working one-shot integrations must be rewritten into multi-step flows and will lose the ability to attach custom metadata to media messages.