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