Changes to file events in the Real-Time Messaging API

If you parse events referencing files in the real-time messaging API, you may have noticed we send a sometimes comically large packet of information when streaming nearly anything related to a file.

To improve performance and provide a better user experience, we’re reducing the payload of most file-related events in the RTM API to include only the file’s ID. You’ll need to use the API method to retrieve additional information about files.

These changes will roll out gradually beginning May 16th, 2016 — read below to understand how this change may effect you, especially if you work with bot users.

Bot users will gain comparable capabilities, allowing bot user tokens to work with based on the channel memberships and related capabilities granted to them.

What’s changing:

The following Real Time Messaging events will be modified:

When pins or stars are applied to or removed from messages containing files, you’ll also find this new behavior in these associated events:

How these events will change

After release, you will receive abbreviated file events, with only the id attribute:

"file_id": "F2147483862",
"type": "file_shared",
"file": {
"id": "F2147483862"

This id value may be used with the API method to obtain fresh information about the file it represents. We’ll also include a top-level file_id field, which you may want to use going forward instead.

Until now, these events would have had more verbose file details included:

"type": "file_shared",
"file": {
"id" : "F2147483862",
"created" : 1356032811,
"timestamp" : 1356032811,
"name" : "file.htm",
"title" : "My HTML file",
"mimetype" : "text\/plain",
"filetype" : "text",
"pretty_type": "Text",
"user" : "U2147483697",
"mode" : "hosted",
"editable" : true,
"is_external": false,
"external_type": "",
"username": "",
"size" : 12345,
"url_private": "https:\/\/\/files-pri\/T024BE7LD-F024BERPE\/1.png",
"url_private_download": "https:\/\/\/files-pri\/T024BE7LD-F024BERPE\/download\/1.png",
"thumb_64": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_64.png",
"thumb_80": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_80.png",
"thumb_360": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_360.png",
"thumb_360_gif": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_360.gif",
"thumb_360_w": 100,
"thumb_360_h": 100,
"thumb_480": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_480.png",
"thumb_480_w": 480,
"thumb_480_h": 480,
"thumb_160": "https:\/\/\/files-tmb\/T024BE7LD-F024BERPE-c66246\/1_160.png",
"permalink" : "https:\/\/\/files\/cal\/F024BERPE\/1.png",
"permalink_public" : "https:\/\/\/T024BE7LD-F024BERPE-3f9216b62c",
"edit_link" : "https:\/\/\/files\/cal\/F024BERPE\/1.png/edit",
"preview" : "<!DOCTYPE html>\n<html>\n<meta charset='utf-8'>",
"preview_highlight" : <div class=\"sssh-code\"><div class=\"sssh-line\"><pre><!DOCTYPE html...",
"lines" : 123,
"lines_more": 118,
"is_public": true,
"public_url_shared": false,
"display_as_bot" : false,
"channels": ["C024BE7LT", ...],
"groups": ["G12345", ...],
"ims": ["D12345", ...],
"initial_comment": {...},
"num_stars": 7,
"is_starred": true,
"pinned_to": ["C024BE7LT", ...],
"reactions": [
"name": "astonished",
"count": 3,
"users": [ "U1", "U2", "U3" ]
"name": "facepalm",
"count": 1034,
"users": [ "U1", "U2", "U3", "U4", "U5" ]
"comments_count": 1

Bot users

Today, some bot users may rely on the current behavior to utilize or index files referenced in the channels they belong to. To support that use case, we will improve the method to make it accessible to bot users and scoped only to the files that a bot has access to when using its bot user token.

We’ll post a follow up within the next two weeks when we’re ready to release these new capabilities.

Update, April 27th, 2016: Bot user tokens may now use to retrieve information about files appearing in the channels they belong to.

How to prepare:

Review your streaming integration to determine where and when you rely on the full file object being present in events. If you don’t need the full file object, consume only the file ID. If you need the full file object, request it using

When it’s happening:

May 16th, 2016.

We want to make these improvements as soon as possible, beginning a gradual roll out on May 16th, 2016. If you believe that your application, custom integration, or third party library will outright break or non-gracefully degrade as a result of this change, please let us know immediately so we may work together to make this transition as seamless as possible.

Show your support

Clapping shows how much you appreciated Slack API’s story.