Skip to main content

files.remote.add method

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

Usage info​

This method adds a remote file to Slack. Adding a file does not share it to a channel. To make your remote file visible, use the files.remote.share API method. This method performs an upsert: if you add a file that has been added previously, the existing file will be updated.

Remote files exist across the entire 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. Dimension requirements for previews are a minimum of 800w x 400h.

preview_image is displayed when your remote file is shared. It's a binary image file.

external_id is the unique ID of the remote file, according to the external host of the file.

indexable_file_contents is a text file that represents the file for search. 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.

One tricky bit: in the response, the file object may indicate that "has_rich_preview" is false, even if you include the preview_image parameter. That's because it takes a few seconds for Slack to parse the preview_image you pass. If you call files.remote.add with the same external_id later, you'll see "has_preview_image": true.

Response​

{
    "ok": true,
    "file": {
        "id": "F08EAQ813FW",
        "created": 1740062388,
        "timestamp": 1740062388,
        "name": "Test",
        "title": "Test",
        "mimetype": "application/vnd.slack-remote",
        "filetype": "remote",
        "pretty_type": "Remote",
        "user": "U123A4BCDE5",
        "user_team": "T123A4BC5DE",
        "editable": false,
        "size": 0,
        "mode": "external",
        "is_external": true,
        "external_type": "app",
        "is_public": false,
        "public_url_shared": false,
        "display_as_bot": false,
        "username": "",
        "url_private": "https://docs.google.com/document/d/1e8LtkvCSe_NH0UU0RyLgssmUQLT8G_3RMCGzyPWcx58/edit?tab=t.0",
        "media_display_type": "unknown",
        "permalink": "https://thetestenv.slack.com/files/U123A4BCDE5/F08EAQ813FW/test",
        "comments_count": 0,
        "is_starred": false,
        "shares": {},
        "channels": [],
        "groups": [],
        "ims": [],
        "has_more_shares": false,
        "external_id": "1234",
        "external_url": "https://docs.google.com/document/d/1e8LtkvCSe_NH0UU0RyLgssmUQLT8G_3RMCGzyPWcx58/edit?tab=t.0",
        "has_rich_preview": false,
        "file_access": "visible"
    }
}