Go to Slack

File threads to replace file comments soon

Updated: 2018-05-01 APIs

We're fixing file comments and in the process we're phasing out some related API methods and events.

File comments look like messages in a channel but they aren't. They travel with files, wherever shared, disrupting conversation at inopportune moments.

Sometime after June 20, 2018, file threads will begin replacing file comments. Sharing a file with a channel will create a message. People and bots will then reply to that message as they would with any other message.

What's changing?

Here is an overview of the changes to expect. We'll go into greater detail in the coming weeks.

  • Files no longer have an associated, global collection of comments or reactions against it.
  • Commenting or reacting to files is done on a per-conversation basis.
  • As users share files to channels, messages are created and any replies to the file are created as threaded replies.
  • Users cannot react to files directly.
  • Reactions apply on a per-conversation basis to the message announcing the file (the file thread parent) — not to the file itself.
  • files:read used to be sufficient to read file comments but as comments become messages in a thread, your app must be awarded a conversations "history" scope like channels:history.
  • files:write was once adequate to comment on a file but since comments are now messages in a thread, your app must be awarded a chat:write scope to comment on files.

Transitioning OAuth scopes

With file comments becoming threaded messages, the files:read, files:write, and files:write:user scopes will no longer be the right scopes for accessing content about files.

To read file message threads, your app or bot will need to "listen" for messages dispatched to the RTM and Events APIs and/or use methods like conversations.replies with the appropriate related conversation scope like channels:history, groups:history, im:history, and mpim:history.

To write to file message threads, your app will need one of chat:write, chat:write:user, and/or chat:write:bot to post messages targeting a thread's thread_ts. When using a bot user token, your bot must be a member of the channel its writing messages to. With user tokens, the represented user must be a member of the channel.

If you don't already have these scopes, you must request users to re-authorize your application and approve them.

Apps in the directory will need to add the scopes to their app and request approval from our review team before requesting the additional scopes.

You may want to begin the process of asking for these new scopes before you need them in June 2018 and beyond.

Discontinued events

These events are being phased out because file comments won't be created any more.

Mutating Web API methods

The shape of a file object changes slightly.

We're phasing out the channels, groups, and ims fields in favor of a more unified shares node instead.

Changes to files.info & files.list

Here's an abbreviated file object in the new model, highlighting shares:

    "ok": true,
    "files": [
            "id": "F0PHJN941",
            "created": 1524085964,
            "name": "ping.png",
            "mimetype": "image/png",
            "user": "U061F7AUR",
            "shares": {
                "public": {
                    "C061FA5PB": [
                            "reply_users": [],
                            "reply_users_count": 0,
                            "reply_count": 0,
                            "ts": "1524086081.000029"
                    "C061EG9SL": [
                            "reply_users": [
                            "reply_users_count": 1,
                            "reply_count": 1,
                            "latest_reply": "1524085983.000010",
                            "ts": "1524085969.000036"
                "private": {
                    "D0PNCRP9N": [
                            "reply_users": [],
                            "reply_users_count": 0,
                            "reply_count": 0,
                            "ts": "1524086053.000018"
            "channels": [
            "groups": [],
            "ims": [
            "comments_count": 0

Each share instance comes with:

  • reply_users - an array of up to 5 user IDs corresponding to the first users having replied to the file thread parent
  • reply_users_count - an integer value counting the number of replying users
  • reply_count - the raw integer number of replies to the file thread parent
  • latest_reply - if the file thread parent has 1 or more replies, points to the most recent message's ts value; it is otherwise omitted
  • thread_ts - if the file was shared into a thread directly, this is the original parent message's ts value; it is otherwise omitted
  • ts - the file thread parent message identifier. Use this as the thread_ts value when posting threaded comments, or as the target when adding reactions with reactions.add

The above example notes two public channel shares (one with a reply), and a single private channel share.

Up to 50 of the most recent shares are returned in files.list and files.info.

Changes coming to files.upload

Any provided initial_comment value will automatically be used as part of the file thread parent message instead of as a file comment.

You can provide a thread_ts to upload and share a file directly to an existing thread and broadcast to share that reply with a channel, just like using chat.postMessage in typical message threads.

Responses to files.upload will include the shares attribute, detailing the channel(s) and file thread parent ts value. Log the ts value to track replies to the newly uploaded file.

Reactions to files become reactions to file thread parents

You'll find changes to reactions.get and reactions.list, all the consequence of reactions applying to file thread parents instead of globally to a file itself.

Discontinued Web API methods

During a transition period, these methods will remain quasi-functional with adapted behavior. We encourage you to use chat.postMessage and chat.update to work with messages instead.

For a limited time, we'll automatically pipe comments added through this method into messages in reply to the most recently shared file message.

What isn't changing?

We're making some best-effort, short-term accommodations to help ease the transition — we'll eventually retire them as well.

  • files.comments.add and files.comments.edit will continue to function. Instead of working against file comments, they'll adapt to working against the most recently shared file thread message.
  • files.upload's initial_comment will automatically convert the file comment into a file thread instead, tied to the file thread parent.

How do I prepare?

If you work with files and/or file comments, here's how to get ready:

Do you write file comments? You'll need a chat:write, chat:write:user, or chat:write:bot scope to create messages in reply to file thread parents. files:write

If you work with file comments, adapt your code to work with threaded messages instead.

When is this happening?

We expect to release file threads sometime after June 20, 2018. Within a few months, we'd like to remove the legacy accordances we've made to preserve the illusion of file comments.

Something amiss? Let us know.

Review other recent updates