Remote files are files not hosted inside Slack. Think of a remote file as a pointer, a forwarding address, or a reference to a file that lives elsewhere.
For most apps, uploading files directly to Slack is preferred over adding remote files. Direct uploads are simpler.
However, there are a few benefits to adding and sharing remote files to Slack:
indexable content
. That way, you can ensure your file appears when users search for certain terms.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".
You can add, update, remove, share, and unfurl remote files in Slack.
Imagine an app that shares your personal travel writing to a Slack channel once a week. Your latest story is stored in a private file service as a document, containing both text and images.
Your app could simply write a message in channel containing a link to your latest story. You'd have no control over the unfurl, and the doc wouldn't appear in Slack searches. If you don't have an existing app installed that beautifies your link, you'll get no unfurl at all when sharing the link—which means all the lovely context and metadata from the story wouldn't be displayed.
Here's what a simple URL share would look like:
With remote files, we can tidy up the message, removing the long and unneeded URL, and choose a tempting preview image to encourage people to read on. To do this, we're going to share the story as a remote file.
In order to add a remote 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.
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.
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.
Once you've obtained the necessary scopes and subscribed to any desired events, you can add, update, remove, share, and unfurl remote files in Slack.
To add a remote file, use the files.remote.add
method from the Web API.
Remote files exist across the whole workspace (or organization, for Enterprise Grid).
Here's a sample call:
curl -F token=<token> \
-F external_id=ABCD1 \
-F external_url=https://mydocuments.com/document/d/1TA9fIaph4eSz2fC_1JGMuYaYUc4IvieIop0WqfCXw5Y/edit?usp=sharing \
-F title=LeadvilleAndBackAgain \
-F preview_image=@cycling.jpg \
-F indexable_file_contents=search_terms.txt
https://slack.com/api/files.remote.add
Pay particular attention to the preview_image
parameter. preview_image
should be a binary image file, and it will be stored in Slack. That's going to allow a more beautiful unfurl in the next step, when the app actually shares the remote file.
indexable_file_contents
also deserves a mention. Use this parameter to specify a file containing the search terms that correspond to this remote file. When a user searches in Slack, their query will be compared against the contents of this text file for matching.
Think of this text file like the alt
parameter on an HTML <img>
tag — a textual representation of a non-textual object. The text file can contain a description of the remote file, or it can contain search keywords, or anything else text-based.
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.
You'll see the external_id
returned to you on the file
object in the Slack response, as well as a file_id
. Either of these ids can be stored and used to query the files.remote.info
method to access other information about the file.
Adding is nice, but sharing is caring.
In other words, adding a remote file does not, by itself, share the file to a conversation. Without sharing the file, it remains an orphan inside Slack—you can view information on it via files.remote.info
method, but it won't actually be visible anywhere. Let's make it visible with a call to the files.remote.share
method.
curl -F token=<token> \
-F external_id=ABCD1 \
-F channels=C12345 \
https://slack.com/api/files.remote.share
Now we get a lovely message in channel that shows off the remote file (in this case, a story about cycling) as it should be seen.
Now we have a custom preview_image
, which we specified during the add
step, instead of the ugly raw URL and a small picture of text.
A word about tokens: the files.remote.share
method may be called with either a bot or a user token. The bot token shares the file from your app, while the user token shares the file from the user associated with your user token. Use the bot token to share to channels that the bot has access to; use the user token to share to channels that the user has access to.
We've already mentioned how to add a custom preview_image
that makes our remote files appear nicer when they're shared. But what about when someone else shares our remote file as a link?
The first step to providing lush unfurls is to be armed with the link_shared
event.
When that link_shared
event fires, we receive its payload, including the message_ts
of the message that triggered it, as well as the channel
of that message. Now we can make an HTTP request to chat.unfurl. First, let's set up our unfurls
object using a block:
unfurls: {
'https://mydocuments.com/document/d/1TA9fIaph4eSz2fC_1JGMuYaYUc4IvieIop0WqfCXw5Y/edit?usp=sharing': {
hide_color: true,
blocks: [{
type: 'file',
external_id: 'ABCD1',
source: 'remote',
}]
}
}
For use specifically with a file unfurl, you can set the hide_color
field to true
to remove the color bar from a message. This property works only with a file block; if this property is included along with other blocks (for example, a section block), the chat.unfurl
method will throw an error.
Next, we call chat.unfurl
with the channel
from the link_shared
event, and set the ts
equal to the message_ts
from the event:
curl -F token=<user_token> \
-F ts=123456789.9875 \
-F unfurls=<unfurls json from above> \
-F channel=C12345 \
-F user_auth_required=false \
https://slack.com/api/chat.unfurl
Check out the chat.unfurl
method documentation for more detail on how to use that method to its fullest potential.
Your remote file's contents may change. When that happens, call the files.remote.update
method to update your remote file:
curl -F token=<token> \
-F tile=ACyclistTale \
-F external_id=ABCD1 \
https://slack.com/api/files.remote.update
You cannot update the external_id
or file_id
of a remote file. If you need to change those fields, your best bet is to remove and then add the file.
One other piece of pleasant news: adding a remote file is actually an "upsert" operation, meaning that if you add a file that has been added before, the existing file will be updated.
Removing a remote file follows the same pattern as adding and updating. Use the files.remote.remove
method to remove a remote file from Slack.
This method does not delete the remote file from where it's externally hosted; it only removes the remote file from Slack.
curl -F token=<bot_token> \
-F external_id=ABCD1 \
https://slack.com/api/files.remote.remove
After removal, any place that used to display the file will show a tombstone message containing the text "This file was deleted." instead.
That about wraps up our guide to remote files. Hopefully, they now feel less like a free-for-all and more like a fun, functional way to add richer context to Slack. Although direct uploads are always preferred to remote files for their simplicity, remote files do allow for lush unfurls, custom searchable contents, and private hosting of files.