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.
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.
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.
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.
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.
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.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.