Preparing your app to work with files

Files are boxes of information shared in Slack.

They usually contain complex data, above and beyond message text: a spreadsheet, a PDF, an error log, a document, a song, a jealousy-inducing photo of mountain vistas.

Since files can represent complex information, an app that uses files well can communicate more succinctly and precisely.

Read on to set up an app that's effortlessly adept in the art of files.

• App setup: uploading files to Slack
  • Scopes
  • Events
• App setup: adding remote files
  • Scopes
  • Events

App setup: uploading files to Slack

By far the easiest way to use files in Slack is to simply upload files to Slack. When you upload a file to Slack, Slack becomes the host for your file, taking care of its safe storage.

In order to upload a file to Slack, there's a couple of scopes your app should have.

Scopes

Under the Apps page of your app, choose the OAuth & Permissions sidebar to select scopes.

• files:read allows access to, well, methods that read files. That's files.info and files.list.
• files:write:user allows your app to upload files as the user associated with your user token. It also allows your app to remove the files that your user has control over.

If you'd like to do your work with a bot instead, one scope will do: request the bot scope to gain dominion over the file arts.

Events

A bevy of events inform your app about file happenings in your workspace. To subscribe to any file events, use the Event Subscriptions tab under your Apps page. Here's a laundry list of file events:

• file_change: A file was changed.
• file_created: A file was created.
• file_deleted: A file was deleted.
• file_public: A file was made public.
• file_shared: A file was shared.
• file_unshared: A file was unshared.

Read our festive file guide for more detail on working with files.

App setup: adding remote files

Remote files are files not hosted inside Slack. Think of a remote file as a pointer, a forwarding address, a reference to a file that lives elsewhere.

A few terminology gotchas: remote files are added to Slack, not "uploaded." Adding a remote file to Slack makes Slack aware of its existence. Once that's done, sharing a remote file, like sharing a direct upload file, brings the file into a conversation. So a remote file must be added before it is shared.

Let's be clear: for most apps, uploading files directly to Slack is preferred over adding remote files. Direct uploads are simpler, like an easy button for files.

However, there are a few benefits to adding and sharing Remote Files to Slack.

1. If your file can't be hosted in Slack for property rights reasons, Remote Files are here to save the day.
2. If you wish to provide a lush, custom unfurl experience for your files when their links are shared, Remote Files bring forth fantastical unfurls for the low low price of a JSON object.
3. If you want to control the way your file appears in Slack searches, so that others can find it later, Remote Files allow for customized indexable content. That way, you can make sure your file appears when users search for certain terms.

Scopes

Working with remote files requires a distinct set of scopes from those involved in direct upload. Again, under the Apps page of your app, choose the OAuth & Permissions sidebar to select scopes.

• remote_files:read allows your app to read information about remote files visible to the user associated with your user token.
• remote_files:share allows your app to share remote files visible to the user associated with your user token.
• chat:write allows your app to post messages in approved channels & conversations. This is especially useful for an app that provides a custom unfurl for remote files.
• links:read allows your app to view and subscribe to events about links that have been shared in conversation. Again, this is useful for knowing when a link to your remote file has been shared, so that you can unfurl it.
• links:write allows your app to unfurl links (like to remote files) using the chat.unfurl method.
• bot allows your app's bot user to add, share, delete, and generally manipulate remote files.

But wait a second. Where's the regular old remote_files:write scope? How does my app add a remote file to Slack so that it can be shared?

There is no write scope for remote files. Remote files exist across the whole workspace (or organization, for Enterprise Grid). Because of that, remote files must be added by bots with the bot scope, not by an individual user.

Once you've obtained the necessary scopes, you can add, update, remove, share, and unfurl remote files in Slack.

Events

To subscribe to any file events, use the Event Subscriptions tab under your Apps page. One event that can be especially useful to apps that work with remote files is the link_shared event, which notifies your app when a link has been shared so that you can unfurl it. Add any App Unfurl Domains that relate to your file service under that same tab in the Apps page.

While most apps will be well-served by directly uploading files to Slack, Remote Files do offer a fleet of fun features beyond direct uploads. Read our go-to guide on remote files for more details.