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.

Permalinks

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
`auto`	Auto Detect Type
`text`	Plain Text
`ai`	Illustrator File
`apk`	APK
`applescript`	AppleScript
`binary`	Binary
`bmp`	Bitmap
`boxnote`	BoxNote
`c`	C
`csharp`	C#
`cpp`	C++
`css`	CSS
`csv`	CSV
`clojure`	Clojure
`coffeescript`	CoffeeScript
`cfm`	ColdFusion
`d`	D
`dart`	Dart
`diff`	Diff
`doc`	Word Document
`docx`	Word document
`dockerfile`	Docker
`dotx`	Word template
`email`	Email
`eps`	EPS
`epub`	EPUB
`erlang`	Erlang
`fla`	Flash FLA
`flv`	Flash video
`fsharp`	F#
`fortran`	Fortran
`gdoc`	GDocs Document
`gdraw`	GDocs Drawing
`gif`	GIF
`go`	Go
`gpres`	GDocs Presentation
`groovy`	Groovy
`gsheet`	GDocs Spreadsheet
`gzip`	Gzip
`html`	HTML
`handlebars`	Handlebars
`haskell`	Haskell
`haxe`	Haxe
`indd`	InDesign Document
`java`	Java
`javascript`	JavaScript
`jpg`	JPEG
`json`	JSON
`keynote`	Keynote Document
`kotlin`	Kotlin
`latex`	LaTeX/sTeX
`lisp`	Lisp
`lua`	Lua
`m4a`	MPEG 4 audio
`markdown`	Markdown (raw)
`matlab`	MATLAB
`mhtml`	MHTML
`mkv`	Matroska video
`mov`	QuickTime video
`mp3`	mp4
`mp4`	MPEG 4 video
`mpg`	MPEG video
`mumps`	MUMPS
`numbers`	Numbers Document
`nzb`	NZB
`objc`	Objective-C
`ocaml`	OCaml
`odg`	OpenDocument Drawing
`odi`	OpenDocument Image
`odp`	OpenDocument Presentation
`ods`	OpenDocument Spreadsheet
`odt`	OpenDocument Text
`ogg`	Ogg Vorbis
`ogv`	Ogg video
`pages`	Pages Document
`pascal`	Pascal
`pdf`	PDF
`perl`	Perl
`php`	PHP
`pig`	Pig
`png`	PNG
`post`	Slack Post
`powershell`	PowerShell
`ppt`	PowerPoint presentation
`pptx`	PowerPoint presentation
`psd`	Photoshop Document
`puppet`	Puppet
`python`	Python
`qtz`	Quartz Composer Composition
`r`	R
`rtf`	Rich Text File
`ruby`	Ruby
`rust`	Rust
`sql`	SQL
`sass`	Sass
`scala`	Scala
`scheme`	Scheme
`sketch`	Sketch File
`shell`	Shell
`smalltalk`	Smalltalk
`svg`	SVG
`swf`	Flash SWF
`swift`	Swift
`tar`	Tarball
`tiff`	TIFF
`tsv`	TSV
`vb`	VB.NET
`vbscript`	VBScript
`vcard`	vCard
`velocity`	Velocity
`verilog`	Verilog
`wav`	Waveform audio
`webm`	WebM
`wmv`	Windows Media Video
`xls`	Excel spreadsheet
`xlsx`	Excel spreadsheet
`xlsb`	Excel Spreadsheet (Binary, Macro Enabled)
`xlsm`	Excel Spreadsheet (Macro Enabled)
`xltx`	Excel template
`xml`	XML
`yaml`	YAML
`zip`	Zip