API object type

file

A file object contains information about a file shared with a workspace.

{
    "id": "F0S43PZDF",
    "created": 1531763342,
    "timestamp": 1531763342,
    "name": "tedair.gif",
    "title": "tedair.gif",
    "mimetype": "image/gif",
    "filetype": "gif",
    "pretty_type": "GIF",
    "user": "U061F7AUR",
    "editable": false,
    "size": 137531,
    "mode": "hosted",
    "is_external": false,
    "external_type": "",
    "is_public": true,
    "public_url_shared": false,
    "display_as_bot": false,
    "username": "",
    "url_private": "https://.../tedair.gif",
    "url_private_download": "https://.../tedair.gif",
    "thumb_64": "https://.../tedair_64.png",
    "thumb_80": "https://.../tedair_80.png",
    "thumb_360": "https://.../tedair_360.png",
    "thumb_360_w": 176,
    "thumb_360_h": 226,
    "thumb_160": "https://.../tedair_=_160.png",
    "thumb_360_gif": "https://.../tedair_360.gif",
    "image_exif_rotation": 1,
    "original_w": 176,
    "original_h": 226,
    "deanimate_gif": "https://.../tedair_deanimate_gif.png",
    "pjpeg": "https://.../tedair_pjpeg.jpg",
    "permalink": "https://.../tedair.gif",
    "permalink_public": "https://.../...",
    "comments_count": 0,
    "is_starred": false,
    "shares": {
        "public": {
            "C0T8SE4AU": [
                {
                    "reply_users": [
                        "U061F7AUR"
                    ],
                    "reply_users_count": 1,
                    "reply_count": 1,
                    "ts": "1531763348.000001",
                    "thread_ts": "1531763273.000015",
                    "latest_reply": "1531763348.000001",
                    "channel_name": "file-under",
                    "team_id": "T061EG9R6"
                }
            ]
        }
    },
    "channels": [
        "C0T8SE4AU"
    ],
    "groups": [],
    "ims": [],
    "has_rich_preview": false
}

Basic fields

The name parameter may be null for unnamed files.

The created property is a Unix timestamp representing when the file was created. The timestamp property is deprecated and is provided only for backwards compatibility with older clients. The updated property (for Post filetypes only) is a Unix timestamp of when the Post was last edited.

The mimetype and filetype props do not have a 1-to-1 mapping, as multiple different files types ('html', 'js', etc.) share the same mime type. The pretty_type property contains a human-readable version of the type.

The mode property contains one of hosted, external, snippet or post.

The editable property indicates that files are stored in editable mode. The is_external property indicates whether the master copy of a file is stored within the system or not. If the file is_external, then the url property will point to the externally-hosted master file. Further, the external_type property will indicate what kind of external file it is, e.g. dropbox or gdoc.

The size parameter is the filesize in bytes. Snippets are limited to a maximum file size of 1 megabyte.

Depending on the file's type, you may encounter different fields relevant to that type. For instance, you may encounter fields such as image_exif_rotation, original_w, and original_h for images but not find those fields for HTML documents.

Authentication

Authentication is required to retrieve file URLs.

The url_private property points to a URL to the file contents. Editable-mode files will also have a url_private_download parameter, which includes headers to force a browser download. Both url_private and url_private_download require an authorization header of the form:

Authorization: Bearer A_VALID_TOKEN

In this case, A_VALID_TOKEN is representative of a real OAuth token, bearing at least the files:read scope. Learn more about OAuth Scopes.

Fields providing URLs that require this form of authentication include:

  • url_private
  • url_private_download
  • thumb_64
  • thumb_80
  • thumb_160
  • thumb_360
  • thumb_480
  • thumb_720
  • thumb_960
  • thumb_1024

Please note that the url and url_download parameters have been deprecated. Please use url_private and url_private_download instead.

Thumbnails

If a thumbnail is available for the file, the URL to a 64x64 pixel will be returned as the thumb_64 prop.

The thumb_80 prop (when present) contains the URL of an 80x80 thumb. Unlike the 64px thumb, this size is guaranteed to be 80x80, even when the source image was smaller (it's padded with transparent pixels).

A variable sized thumb will be returned as thumb_360, with its longest size no bigger than 360 (although it might be smaller depending on the source size). Dimensions for this thumb are returned in thumb_360_w and thumb_360_h.

In the case where the original image was an animated gif with dimensions greater than 360 pixels, we also created an animated thumbnail and pass it as thumb_360_gif.

Depending on the original file's size, you may even find a thumb_480, thumb_720, thumb_960, or thumb_1024 property.

All thumbnails require an authorization header as described above.

The permalink URL points to a single page for the file containing details, comments and a download link. If the file is available to the public, a permalink_public URL points to the public file itself.

The edit_link is only present for posts and snippets and is the page at which the file can be edited.

Previews

For posts, we also include a short plain-text preview than can be shown in place of a thumbnail.

For snippets, we include a simple preview of the contents (a few truncated lines of plaintext), as well as a more complex syntax-highlighted preview (preview_highlight) in HTML. The total count of lines in the snippet if returned in lines, while lines_more contains a count of lines not shown in the preview.

Other fields

If a file is public, the is_public flag will be set.

If a file's public URL has been shared, the public_url_shared flag will be set.

The channels array contains the IDs of any channels into which the file is currently shared. The groups array is the same but for private groups. Groups are only returned if the caller is a member of that group. Finally, the ims array is the same but for IM channels. IMs are only returned if the caller is a member of that IM channel.

The num_stars property contains the number of users who have starred this file. It is not present if no users have starred it. The is_starred property is present and true if the calling user has starred the file, else it is omitted.

The pinned_to array contains the IDs of any channels to which the file is currently pinned.

The reactions property contains any reactions that have been added to the file and gives information about the type of reaction, the total number of users who added that reaction and a (possibly incomplete) list of users who have added that reaction to the file. The users array in the reactions property might not always contain all users that have reacted (we limit it to X users, and X might change), however count will always represent the count of all users who made that reaction (i.e. it may be greater than users.length).

If the authenticated user has a given reaction then they are guaranteed to appear in the users array, regardless of whether count is greater than users.length or not.

The initial_comment will be a comment from the file uploader, and will only be set when the uploader commented on the file at the time of upload. Clients can use this to display the comment with the file when announcing new file uploads. Use comments_count to determine how many comments are attached to a file.

Slack Connect files

When a file is uploaded into a Slack Connect channel, file object properties are not immediately accessible to apps listening via the Events API or RTM API. Instead, the payload will contain a file object with the key-value pair "file_access": "check_file_info" meaning that further action is required from your app in order to view an uploaded file's metadata.

    "files": [
        {
          "id": "F12345678",
          "mode": "file_access",
          "file_access": "check_file_info",
          "created": 0,
          "timestamp": 0,
          "user": ""
        }
      ]

See Slack Connect: working with channels between organizations for more details on how to handle this scenario.

File types

Possible filetype values include, but are not limited to the following:

Type Description
autoAuto Detect Type
textPlain Text
aiIllustrator File
apkAPK
applescriptAppleScript
binaryBinary
bmpBitmap
boxnoteBoxNote
cC
csharpC#
cppC++
cssCSS
csvCSV
clojureClojure
coffeescriptCoffeeScript
cfmColdFusion
dD
dartDart
diffDiff
docWord Document
docxWord document
dockerfileDocker
dotxWord template
emailEmail
epsEPS
epubEPUB
erlangErlang
flaFlash FLA
flvFlash video
fsharpF#
fortranFortran
gdocGDocs Document
gdrawGDocs Drawing
gifGIF
goGo
gpresGDocs Presentation
groovyGroovy
gsheetGDocs Spreadsheet
gzipGzip
htmlHTML
handlebarsHandlebars
haskellHaskell
haxeHaxe
inddInDesign Document
javaJava
javascriptJavaScript
jpgJPEG
jsonJSON
keynoteKeynote Document
kotlinKotlin
latexLaTeX/sTeX
lispLisp
luaLua
m4aMPEG 4 audio
markdownMarkdown (raw)
matlabMATLAB
mhtmlMHTML
mkvMatroska video
movQuickTime video
mp3mp4
mp4MPEG 4 video
mpgMPEG video
mumpsMUMPS
numbersNumbers Document
nzbNZB
objcObjective-C
ocamlOCaml
odgOpenDocument Drawing
odiOpenDocument Image
odpOpenDocument Presentation
odsOpenDocument Spreadsheet
odtOpenDocument Text
oggOgg Vorbis
ogvOgg video
pagesPages Document
pascalPascal
pdfPDF
perlPerl
phpPHP
pigPig
pngPNG
postSlack Post
powershellPowerShell
pptPowerPoint presentation
pptxPowerPoint presentation
psdPhotoshop Document
puppetPuppet
pythonPython
qtzQuartz Composer Composition
rR
rtfRich Text File
rubyRuby
rustRust
sqlSQL
sassSass
scalaScala
schemeScheme
sketchSketch File
shellShell
smalltalkSmalltalk
svgSVG
swfFlash SWF
swiftSwift
tarTarball
tiffTIFF
tsvTSV
vbVB.NET
vbscriptVBScript
vcardvCard
velocityVelocity
verilogVerilog
wavWaveform audio
webmWebM
wmvWindows Media Video
xlsExcel spreadsheet
xlsxExcel spreadsheet
xlsbExcel Spreadsheet (Binary, Macro Enabled)
xlsmExcel Spreadsheet (Macro Enabled)
xltxExcel template
xmlXML
yamlYAML
zipZip