Uploading files to Slack

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

App setup

In order to upload a file to Slack, there are a couple of scopes your app should have. There are also some events you may want your app to subscribe to.

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.

With your app set up, read on to learn how to upload files.

Uploading files

Your app can upload files using the files.upload method. Check out the method documentation for a deep dive on the details of available parameters.

Here's a sample curl command that uploads a file:

curl -F file=@cycling.jpeg -F "initial_comment=Hello, Leadville" -F channels=C0R7MFNJD -H "Authorization: Bearer xoxp-123456789" https://slack.com/api/files.upload

As always, life is easier with a Slack SDK. Use your programming language of choice, and get methods like files.upload as primitive building blocks that you don't have to think about.

If you've got the necessary scopes, your file should appear in the channels specified.

Here's a potentially confusing bit when you use the channels parameter during your upload: the upload method actually combines "uploading" (creating a file hosted in Slack), and "sharing" the file to a channel.

If you don't use the channels parameter, the upload method only "uploads" the file, hosting the file in Slack, but doesn't "share" the file anywhere.

Either way, once your upload succeeds, you'll see an HTTP response from Slack containing an "ok": true field, plus a file object. For more detail on file objects and the fields contained inside, a look at the file object documentation is highly recommended.

Other methods for working with files

Slack provides some other methods for working with files:

• files.delete: Delete a file.
• files.info: Get information on a file.
• files.list: List visible files.
• files.revokePublicURL: Disable a file for public sharing.
• files.sharedPublicURL: Enable a file for public sharing.

Responding to files

Slack also sends events when files are uploaded or changed in your workspace. Here are some of the relevant 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.

The best thing about working with files is that they usually work the way you'd expect. Gone are the days of file comments (don't ask) and strange behavior.

If, however, you wish to flex your file skills by sharing files hosted outside of Slack, providing custom unfurls, or fine-tuning the way your files appear in Slack searches: continue onward to our guide on remote files.