Remote Files

Learn to use Slack's API calls to manipulate remote files in the workspace.

Similar to the local file API, Slack also offers a remote file API. We use this API to add and manipulate remote files.

Let’s look at the following endpoints in this lesson:

  1. files.remote.add: This endpoint adds a file from a remote service.
  2. files.remote.share: This endpoint shares a remote file into a channel.
  3. files.remote.update: This endpoint updates an existing remote file.
  4. files.remote.info: This endpoint retrieves information about a remote file added to Slack.
  5. files.remote.list: This endpoint retrieves information about a remote file added to Slack.
  6. files.remote.remove: This endpoint removes a remote file.

Add a remote file

To add a remote file, we access the https://slack.com/api/files.remote.add endpoint. With this endpoint, we’ll add a remote document. We must first add a remote file before sharing it in a chat. You can make a new Google document by going to this link: doc.new. Copy the shareable link of the Google document, and paste it into the coding widget below.

Note: If you are not a Google user, you can use any other remote file URL.

Request parameters

Some important query parameters for the files.remote.add endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

external_id

string

required

This is the creator-defined globally unique identifier (GUID) for the file.

external_url

string

required

This is the URL of the remote file.

title

string

required

This is the title of the file being shared.

Let’s call the files.remote.add endpoint. Click the “Run” button to add a remote file to Slack. Since there’s a separate call to share the file, this endpoint is limited to uploading it to Slack.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.add");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const queryParameters = new URLSearchParams({
external_id: generateId(),
external_url: "{{DOC_1}}",
title: "My first remote file",
});
const options = {
method: "GET",
headers: headerParameters,
};
async function addRemoteFile() {
try {
url.search = queryParameters;
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
addRemoteFile();

Let’s look at the highlighted lines in the code widget shown above:

  • Line 3: We specify the files.remote.add endpoint.
  • Lines 10–14: We specify the parameters for the request, including specifying the external_url for the file, generating a random ID, and providing the file title.
  • Lines 23–24: We provide the query parameters and make a call to the files.remote.add endpoint.

Response fields

The response object contains the details of the remote file that we added.

Note: Visit this lesson to view the details of the file object.

Share a remote file

To share a remote file, we access the https://slack.com/api/files.remote.share endpoint. Once a file has been uploaded, we can share this file using this endpoint.

Request parameters

Following are some important query parameters for the files.remote.share endpoint:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

channels

string

required

This is a comma-separated list of channel IDs where the file will be shared.

external_id

string

optional

This is the GUID for the file, as set by the application registering the file with Slack. We require this field or file, or both.

file

string

optional

This specifies a file registered with Slack by providing its ID. This field, external_id, or both are required.

Let’s call the files.remote.share endpoint. Click the “Run” button to share the uploaded file to a conversation.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.share");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const queryParameters = new URLSearchParams({
channels: "{{CHANNEL_ID}}",
file: "{{FILE_ID}}",
});
const options = {
method: "GET",
headers: headerParameters,
};
async function shareRemoteFile() {
try {
url.search = queryParameters;
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
shareRemoteFile();

On lines 10–13, we specify the channels where we have to share the file and set the file ID using the file query parameter.

Response fields

The response object contains the details of the remote file that was shared.

Note: Visit this lesson to view the details of the file object.

Update a remote file

To update a remote file, we access the https://slack.com/api/files.remote.update endpoint, which allows us to update a shared file.

Request parameters

Here are some important query parameters for the files.remote.update endpoint:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

file

string

optional

This specifies a file by providing its ID.

filetype

string

optional

This is the message text that introduces the file in specified channels.

title

string

optional

This is the title of the file.

Let’s call the files.remote.update endpoint. Click the “Run” button to update the title of the uploaded file.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.update");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const queryParameters = new URLSearchParams({
file: "{{FILE_ID}}",
title: "Updated Title",
});
const options = {
method: "GET",
headers: headerParameters,
};
async function updateRemoteFile() {
try {
url.search = queryParameters;
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
updateRemoteFile();

Let’s look at the highlighted lines in the code widget shown above:

  • Lines 10–13: We set the file and the title parameters, specifying a new title for the file.
  • Lines 22–23: We provide the query parameters and call the files.remote.update endpoint.

Response fields

The response object includes the updated details of the remote file.

Note: Visit this lesson to view the details of the file object.

Get information about a remote file

To get information about a remote file, we access the https://slack.com/api/files.remote.info endpoint. This endpoint will respond with the details of the file we shared previously.

Request parameters

Some important query parameters for the files.remote.info endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

file

string

optional

This specifies a file by providing its ID.

external_id

string

optional

This is a creator-defined GUID for the file.

Let’s call the files.remote.info endpoint. Click the “Run” button to get the information on the specified file.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.info");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const queryParameters = new URLSearchParams({
file: "{{FILE_ID}}",
});
const options = {
method: "GET",
headers: headerParameters,
};
async function getRemoteFileInfo() {
try {
url.search = queryParameters;
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
getRemoteFileInfo();

On line 11, we provide the value of the file parameter and call the files.remote.info endpoint on line 22.

Response fields

The response object contains the complete details of the remote file within the file property.

Note: Visit this lesson to view the details of the file object.

List all remote files

To list the remote files, we access the https://slack.com/api/files.remote.list endpoint. This will list all the files that have been uploaded by the application.

Request parameters

Some important query parameters for the files.remote.list endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

channel

string

optional

This filters files appearing in a specific channel, indicated by its ID.

cursor

string

optional

This parameter is a string of characters used to "point" to the next "page" of data. We paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata.

limit

integer

optional

This is the maximum number of items to return.

Let’s call the files.remote.list endpoint. Click the “Run” button to get the list of files that had been uploaded by the application.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.list");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const options = {
method: "GET",
headers: headerParameters,
};
async function getAllRemoteFiles() {
try {
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
getAllRemoteFiles();

On line 17, we call the files.remote.list endpoint to list all the files sent by the bot.

Response fields

The response includes a list of all shared remote files within the files property.

Note: Visit this lesson to view the details of each element within the files object.

Remove a remote file

To remove a remote file, we access the https://slack.com/api/files.remote.remove endpoint. This endpoint will allow us to delete a file from the workspace.

Request parameters

Some important query parameters for the files.remote.remove endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

file

string

optional

This specifies a file by providing its ID.

external_id

string

optional

This is a creator-defined GUID for the file.

Let’s call the files.remote.remove endpoint. Click the “Run” button to remove the remote file we uploaded at the beginning of the lesson.

Press + to interact
import fetch from "node-fetch";
const url = new URL("https://slack.com/api/files.remote.remove");
const headerParameters = {
Authorization: "Bearer {{TOKEN}}",
"Content-Type": "application/x-www-form-urlencoded",
};
const queryParameters = new URLSearchParams({
file: "{{FILE_ID}}",
});
const options = {
method: "GET",
headers: headerParameters,
};
async function removeRemoteFile() {
try {
url.search = queryParameters;
const response = await fetch(url, options);
printResponse(response);
} catch (error) {
printError(error);
}
}
removeRemoteFile();

Let’s look at the highlighted lines in the code widget shown above:

  • Line 11: Similar to the files.remote.info endpoint, we set the file ID as the file parameter.
  • Lines 21–22: We provide the query parameters and call the files.remote.remove endpoint to remove it from the workspace.

Response fields

The response includes the ok parameter only, which indicates whether the request was successful.