Slack Web API
This is not official version of Slack API Documentation.
Link to Official documentation
Authentication
Sends a message to a channel.
Request headers
Authentication token. Requires scope: chat:write
Request body
Set your bot’s user name. Must be used in conjunction with as_user set to false, otherwise ignored. See authorship below.
Provide another message’s ts value to make this message a reply. Avoid using a reply’s ts value; use its parent instead.
A JSON-based array of structured attachments, presented as a URL-encoded string.
Pass true to enable unfurling of primarily text-based content.
Text of the message to send. See below for an explanation of formatting. This field is usually required, unless you’re providing only attachments instead.
Pass false to disable unfurling of media content.
Change how messages are treated. Defaults to none. See below.
Pass true to post the message as the authed user, instead of as a bot. Defaults to false. See authorship below.
Emoji to use as the icon for this message. Overrides icon_url. Must be used in conjunction with as_user set to false, otherwise ignored. See authorship below.
Find and link channel names and usernames.
URL to an image to use as the icon for this message. Must be used in conjunction with as_user set to false, otherwise ignored. See authorship below.
Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name. See below for more details.
Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation. Defaults to false.
Responses
Typical error response if too many attachments are included
Body
Examples
{
"ok" : false,
"error" : "too_many_attachments"
}Typical success response
Body
Examples
{
"message" : {
"username" : "ecto1",
"attachments" : [
{
"text" : "This is an attachment",
"fallback" : "This is an attachment's fallback",
"id" : 1
}
],
"text" : "Here's a message for you",
"ts" : "1503435956.000247",
"subtype" : "bot_message",
"type" : "message",
"bot_id" : "B19LU7CSY"
},
"ok" : true,
"ts" : "1503435956.000247",
"channel" : "C1H9RESGL"
}Authentication
Share a me message into a channel.
Request headers
Authentication token. Requires scope: chat:write:user
Request body
Text of the message to send.
Channel to send message to. Can be a public channel, private group or IM channel. Can be an encoded ID, or a name.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"ts" : "1417671948.000006",
"channel" : "C024BE7LR"
}Authentication
Retrieve a permalink URL for a specific extant message
Request parameters
Authentication token. Requires scope: tokens.basic
A message’s ts value, uniquely identifying it within a channel
The ID of the conversation or channel containing the message
Responses
Error response when channel cannot be found
Body
Examples
Standard success response
Body
Examples
{
"permalink" : "https://ghostbusters.slack.com/archives/C1H9RESGA/p135854651500008",
"ok" : true,
"channel" : "C1H9RESGA"
}Authentication
Deletes a message.
Request headers
Authentication token. Requires scope: chat:write
Request body
Pass true to delete the message as the authed user with chat:write:user scope. Bot users in this context are considered authed users. If unused or false, the message will be deleted with chat:write:bot scope.
Timestamp of the message to be deleted.
Channel containing the message to be deleted.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "message_not_found"
}Typical success response
Body
Examples
{
"ok" : true,
"ts" : "1401383885.000061",
"channel" : "C024BE91L"
}Authentication
Provide custom unfurl behavior for user-posted URLs
Request headers
Authentication token. Requires scope: links:write
Request body
Provide a simply-formatted string to send as an ephemeral message to the user as invitation to authenticate further and enable full unfurling behavior
Set to true or 1 to indicate the user must install your Slack app to trigger unfurls for this domain
URL-encoded JSON map with keys set to URLs featured in the the message, pointing to their unfurl message attachments.
Timestamp of the message to add unfurl behavior to.
Send users to this custom URL where they will complete authentication in your app to fully trigger unfurling. Value should be properly URL-encoded.
Channel ID of the message
Responses
Typical error response
Body
Examples
Typical, minimal success response
Authentication
Sends an ephemeral message to a user in a channel.
Request headers
Authentication token. Requires scope: chat:write
Request body
A JSON-based array of structured attachments, presented as a URL-encoded string.
Text of the message to send. See below for an explanation of formatting. This field is usually required, unless you’re providing only attachments instead.
Find and link channel names and usernames.
Change how messages are treated. Defaults to none. See below.
id of the user who will receive the ephemeral message. The user should be in the channel specified by the channel argument.
Pass true to post the message as the authed bot. Defaults to false.
Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
Responses
Typical error response
Body
Examples
Typical success response
Body
Examples
{
"ok" : true,
"message_ts" : "1502210682.580145"
}Authentication
Updates a message.
Request headers
Authentication token. Requires scope: chat:write
Request body
A JSON-based array of structured attachments, presented as a URL-encoded string. This field is required when not presenting text.
New text for the message, using the default formatting rules. It’s not required when presenting attachments.
Timestamp of the message to be updated.
Change how messages are treated. Defaults to client, unlike chat.postMessage. See below.
Pass true to update the message as the authed user. Bot users in this context are considered authed users.
Find and link channel names and usernames. Defaults to none. This parameter should be used in conjunction with parse. To set link_names to 1, specify a parse mode of full.
Channel containing the message to be updated.
Responses
Typical error response
Body
Examples
Typical success response
Body
Examples
{
"text" : "Updated text you carefully authored",
"ok" : true,
"ts" : "1401383885.000061",
"channel" : "C024BE91L"
}Authentication
Edit an existing file comment.
Request headers
Authentication token. Requires scope: files:write:user
Request body
Text of the comment to edit.
The comment to edit.
File containing the comment to edit.
Responses
Standard failure response when used with an invalid token
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Standard success response when used with a user token
Body
Examples
{
"user_id" : "W12345678",
"url" : "https://subarachnoid.slack.com/",
"team_id" : "T12345678",
"user" : "grace",
"team" : "Subarachnoid Workspace",
"ok" : true
}Authentication
Deletes an existing comment on a file.
Request headers
Authentication token. Requires scope: files:write:user
Request body
The comment to delete.
File to delete a comment from.
Responses
Standard failure response when used with an invalid token
Body
Examples
{
"ok" : false,
"error" : "file_not_found"
}Standard success response is very simple
Authentication
Add a comment to an existing file.
Request headers
Authentication token. Requires scope: files:write:user
Request body
Text of the comment to add.
File to add a comment to.
Responses
Artificial error response
Body
Examples
{
"ok" : false,
"error" : "file_not_found"
}Standard success response
Body
Examples
{
"comment" : {
"comment" : "Everyone should take a moment to read this file.",
"created" : 1356032811,
"timestamp" : 1356032811,
"user" : "U1234567890",
"id" : "Fc1234567890",
"channel" : "C1234467890"
},
"ok" : true
}Authentication
Close a direct message channel.
Request headers
Authentication token. Requires scope: im:write
Request body
Direct message channel to close.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Opens a direct message channel.
Request headers
Authentication token. Requires scope: im:write
Request body
Boolean, indicates you want the full IM channel definition in the response.
User to open a direct message channel with.
Set this to true to receive the locale for this im. Defaults to false
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Sets the read cursor in a direct message channel.
Request headers
Authentication token. Requires scope: im:write
Request body
Timestamp of the most recently seen message.
Direct message channel to set reading cursor in.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Fetches history of messages and events from direct message channel.
Request parameters
Number of messages to return, between 1 and 1000.
Include unread_count_display in the output?
Include messages with latest or oldest timestamp in results.
Authentication token. Requires scope: im:history
Start of time range of messages to include in results.
Direct message channel to fetch history for.
End of time range of messages to include in results.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"has_more" : false,
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true,
"latest" : "1358547726.000003"
}Authentication
Retrieve a thread of messages posted to a direct message conversation
Request parameters
Unique identifier of a thread’s parent message
Authentication token. Requires scope: im:history
Direct message channel to fetch thread from
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true
}Authentication
Lists direct message channels for the calling user.
Request parameters
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: im:read
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ims" : [
{
"created" : 1449709280,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "USLACKBOT",
"is_im" : true,
"id" : "D0G9QPY56"
},
{
"created" : 1466692204,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "U0G9QF9C6",
"is_im" : true,
"id" : "D1KL59A72"
},
{
"created" : 1449722883,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "U0G9WFXNZ",
"is_im" : true,
"id" : "D0G9XPFH9"
},
{
"created" : 1452098023,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "W0HRJL7CK",
"is_im" : true,
"id" : "D0HRHJSF7"
},
{
"created" : 1465834222,
"is_user_deleted" : true,
"is_org_shared" : false,
"user" : "U1GDBDGR3",
"is_im" : true,
"id" : "D1GD7CHC0"
},
{
"created" : 1468274703,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "U1QNSQB9U",
"is_im" : true,
"id" : "D1QMF76M9"
},
{
"created" : 1502210225,
"is_user_deleted" : false,
"is_org_shared" : false,
"user" : "U6KR7BVFW",
"is_im" : true,
"id" : "D6K48KKRN"
}
],
"ok" : true,
"response_metadata" : {
"next_cursor" : "aW1faWQ6RDBCSDk1RExI="
}
}Authentication
Retrieve a thread of messages posted to a private channel
Request parameters
Unique identifier of a thread’s parent message
Authentication token. Requires scope: groups:history
Private channel to fetch thread from
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true
}Authentication
Renames a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Whether to return errors on invalid channel name instead of modifying it to meet the specified criteria.
New name for private channel.
Private channel to rename
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Lists private channels that the calling user has access to.
Request parameters
Exclude the members from each group
Authentication token. Requires scope: groups:read
Don’t return archived private channels.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Removes a user from a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
User to remove from private channel.
Private channel to remove user from.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Sets the read cursor in a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Timestamp of the most recently seen message.
Private channel to set reading cursor in.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about a private channel.
Request parameters
Authentication token. Requires scope: groups:read
Set this to true to receive the locale for this group. Defaults to false
Private channel to get info on
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Leaves a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Private channel to leave
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Clones and archives a private channel.
Request body
Authentication token. Requires scope: groups:write
Private channel to clone and archive.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Invites a user to a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
User to invite.
Private channel to invite user to.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Creates a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Whether to return errors on invalid channel name instead of modifying it to meet the specified criteria.
Name of private channel to create
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Opens a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Private channel to open.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Fetches history of messages and events from a private channel.
Request parameters
Number of messages to return, between 1 and 1000.
Include unread_count_display in the output?
Include messages with latest or oldest timestamp in results.
Authentication token. Requires scope: groups:history
Start of time range of messages to include in results.
Private channel to fetch history for.
End of time range of messages to include in results.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"has_more" : false,
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true,
"latest" : "1358547726.000003"
}Authentication
Sets the topic for a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
The new topic
Private channel to set the topic of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Sets the purpose for a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
The new purpose
Private channel to set the purpose of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Unarchives a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Private channel to unarchive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Archives a private channel.
Request headers
Authentication token. Requires scope: groups:write
Request body
Private channel to archive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about a bot user.
Request parameters
Authentication token. Requires scope: users:read
Bot user to get info on
Responses
When no bot can be found, it returns an error.
Body
Examples
{
"ok" : false,
"error" : "bot_not_found"
}When successful, returns bot info by bot ID.
Body
Examples
{
"bot" : {
"updated" : 1449272004,
"name" : "commandeer",
"icons" : {
"image_36" : "https://...",
"image_48" : "https://...",
"image_72" : "https://..."
},
"deleted" : false,
"app_id" : "A061BLERW",
"id" : "B061F7JQ1"
},
"ok" : true
}Authentication
Set the profile information for a user.
Request headers
Authentication token. Requires scope: users.profile:write
Request body
Collection of key:value pairs presented as a URL-encoded JSON hash.
ID of user to change. This argument may only be specified by team admins on paid teams.
Value to set a single key to. Usable only if profile is not passed.
Name of a single key to set. Usable only if profile is not passed.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_profile"
}Typical success response
Body
Examples
{
"profile" : {
"display_name" : "spengler",
"status_emoji" : ":books:",
"team" : "T012AB3C4",
"real_name" : "Egon Spengler",
"image_24" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"real_name_normalized" : "Egon Spengler",
"image_512" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"display_name_normalized" : "spengler",
"image_32" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_48" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_72" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"avatar_hash" : "ge3b51ca72de",
"status_text" : "Print is dead",
"email" : "spengler@ghostbusters.example.com",
"image_192" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg"
},
"ok" : true
}Authentication
Retrieves a user’s profile information.
Request parameters
Authentication token. Requires scope: users.profile:read
Include labels for each ID in custom profile fields
User to retrieve profile info for
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "user_not_found"
}Typical success response
Body
Examples
{
"profile" : {
"display_name" : "spengler",
"status_emoji" : ":books:",
"team" : "T012AB3C4",
"real_name" : "Egon Spengler",
"image_24" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"real_name_normalized" : "Egon Spengler",
"image_512" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"display_name_normalized" : "spengler",
"image_32" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_48" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_72" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"avatar_hash" : "ge3b51ca72de",
"status_text" : "Print is dead",
"email" : "spengler@ghostbusters.example.com",
"image_192" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg"
},
"ok" : true
}Authentication
Manually sets user presence.
Request headers
Authentication token. Requires scope: users:write
Request body
Either auto or away
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about a user.
Request parameters
Set this to true to receive the locale for this user. Defaults to false
Authentication token. Requires scope: users:read
User to get info on
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "user_not_found"
}Typical success response
Body
Examples
{
"ok" : true,
"user" : {
"profile" : {
"display_name" : "spengler",
"status_emoji" : ":books:",
"team" : "T012AB3C4",
"real_name" : "Egon Spengler",
"image_24" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"real_name_normalized" : "Egon Spengler",
"image_512" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"display_name_normalized" : "spengler",
"image_32" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_48" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_72" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"avatar_hash" : "ge3b51ca72de",
"status_text" : "Print is dead",
"email" : "spengler@ghostbusters.example.com",
"image_192" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg"
},
"updated" : 1502138686,
"tz" : "America/Los_Angeles",
"name" : "spengler",
"deleted" : false,
"is_app_user" : false,
"is_bot" : false,
"tz_label" : "Pacific Daylight Time",
"real_name" : "episod",
"color" : "9f69e7",
"team_id" : "T012AB3C4",
"is_admin" : true,
"is_ultra_restricted" : false,
"is_restricted" : false,
"is_owner" : false,
"tz_offset" : -25200,
"has_2fa" : false,
"id" : "W012A3CDE",
"is_primary_owner" : false
}
}Authentication
Find a user with an email address.
Request parameters
Authentication token. Requires scope: users:read.email
An email address belonging to a user in the workspace
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "user_not_found"
}Typical success response
Body
Examples
{
"ok" : true,
"user" : {
"profile" : {
"display_name" : "spengler",
"status_emoji" : ":books:",
"team" : "T012AB3C4",
"real_name" : "Egon Spengler",
"image_24" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"real_name_normalized" : "Egon Spengler",
"image_512" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"display_name_normalized" : "spengler",
"image_32" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_48" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_72" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"avatar_hash" : "ge3b51ca72de",
"status_text" : "Print is dead",
"email" : "spengler@ghostbusters.example.com",
"image_192" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg"
},
"updated" : 1502138686,
"tz" : "America/Los_Angeles",
"name" : "spengler",
"deleted" : false,
"is_app_user" : false,
"is_bot" : false,
"tz_label" : "Pacific Daylight Time",
"real_name" : "episod",
"color" : "9f69e7",
"team_id" : "T012AB3C4",
"is_admin" : true,
"is_ultra_restricted" : false,
"is_restricted" : false,
"is_owner" : false,
"tz_offset" : -25200,
"has_2fa" : false,
"id" : "W012A3CDE",
"is_primary_owner" : false
}
}Authentication
Gets user presence information.
Request parameters
Authentication token. Requires scope: users:read
User to get presence info on. Defaults to the authed user.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}When requesting information for a different user, this method just returns the current presence (either active or away).
Body
Examples
{
"ok" : true,
"presence" : "active"
}Authentication
Delete the user profile photo
Request body
Authentication token. Requires scope: users.profile:write
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Set the user profile photo
Request body
File contents via multipart/form-data.
Width/height of crop box (always square)
Authentication token. Requires scope: users.profile:write
Y coordinate of top-left corner of crop box
X coordinate of top-left corner of crop box
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Get a user’s identity.
Request parameters
Authentication token. Requires scope: identity.basic
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "account_inactive"
}You will receive at a minimum the following information:
Body
Examples
{
"ok" : true,
"user" : {
"name" : "Sonny Whether",
"id" : "U0G9QF9C6"
},
"team" : {
"id" : "T0G9PQBBK"
}
}Authentication
Lists all users in a Slack team.
Request parameters
Whether to include presence data in the output. Setting this to false improves performance, especially with large teams.
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: users:read
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
Set this to true to receive the locale for users. Defaults to false
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_cursor"
}Typical success response
Body
Examples
{
"cache_ts" : 1498777272,
"ok" : true,
"response_metadata" : {
"next_cursor" : "dXNlcjpVMEc5V0ZYTlo="
},
"members" : [
{
"profile" : {
"display_name" : "spengler",
"status_emoji" : ":books:",
"team" : "T012AB3C4",
"real_name" : "Egon Spengler",
"image_24" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"real_name_normalized" : "Egon Spengler",
"image_512" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"display_name_normalized" : "spengler",
"image_32" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_48" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"image_72" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg",
"avatar_hash" : "ge3b51ca72de",
"status_text" : "Print is dead",
"email" : "spengler@ghostbusters.example.com",
"image_192" : "https://.../avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg"
},
"updated" : 1502138686,
"tz" : "America/Los_Angeles",
"name" : "spengler",
"deleted" : false,
"is_app_user" : false,
"is_bot" : false,
"tz_label" : "Pacific Daylight Time",
"real_name" : "spengler",
"color" : "9f69e7",
"team_id" : "T012AB3C4",
"is_admin" : true,
"is_ultra_restricted" : false,
"is_restricted" : false,
"is_owner" : false,
"tz_offset" : -25200,
"has_2fa" : false,
"id" : "W012A3CDE",
"is_primary_owner" : false
},
{
"profile" : {
"first_name" : "Glinda",
"last_name" : "Southgood",
"display_name" : "Glinda the Fairly Good",
"title" : "Glinda the Good",
"image_1024" : "https://a.slack-edge.com...png",
"skype" : "",
"phone" : "",
"real_name" : "Glinda Southgood",
"image_24" : "https://a.slack-edge.com...png",
"image_original" : "https://a.slack-edge.com...png",
"real_name_normalized" : "Glinda Southgood",
"image_512" : "https://a.slack-edge.com...png",
"image_32" : "https://a.slack-edge.com...png",
"image_48" : "https://a.slack-edge.com...png",
"image_72" : "https://a.slack-edge.com...png",
"avatar_hash" : "8fbdd10b41c6",
"display_name_normalized" : "Glinda the Fairly Good",
"email" : "glenda@south.oz.coven",
"image_192" : "https://a.slack-edge.com...png"
},
"updated" : 1480527098,
"tz" : "America/Los_Angeles",
"name" : "glinda",
"deleted" : false,
"is_bot" : false,
"tz_label" : "Pacific Daylight Time",
"real_name" : "Glinda Southgood",
"color" : "9f69e7",
"team_id" : "T0G9PQBBK",
"is_admin" : true,
"is_ultra_restricted" : false,
"is_restricted" : false,
"is_owner" : false,
"tz_offset" : -25200,
"has_2fa" : false,
"id" : "W07QCRPA4",
"is_primary_owner" : false
}
]
}Authentication
Marks a user as active.
Request headers
Authentication token. Requires scope: users:write
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Closes a direct message or multi-person direct message.
Request headers
Authentication token. Requires scope: conversations:write
Request body
Conversation to close.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Joins an existing conversation.
Request headers
Authentication token. Requires scope: channels:write
Request body
ID of conversation to join
Responses
Typical error response if the conversation is archived and cannot be joined
Body
Examples
{
"ok" : false,
"error" : "is_archived"
}Typical success response
Body
Examples
{
"warning" : "already_in_channel",
"ok" : true,
"response_metadata" : {
"warnings" : [
"already_in_channel"
]
},
"channel" : {
"is_general" : true,
"name_normalized" : "general",
"is_channel" : true,
"creator" : "U061F7AUR",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 0,
"value" : "Which widget do you worry about?",
"creator" : ""
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [ ],
"id" : "C061EG9SL",
"is_org_shared" : false,
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"purpose" : {
"last_set" : 0,
"value" : "For widget discussion",
"creator" : ""
},
"is_private" : false,
"is_shared" : false,
"name" : "general",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
}
}Authentication
Initiates a public or private channel-based conversation
Request headers
Authentication token. Requires scope: conversations:write
Request body
Name of the public or private channel to create
Create a private channel instead of a public one
Responses
Typical error response when name already in use
Body
Examples
{
"ok" : false,
"error" : "name_taken"
}If successful, the command returns a rather stark conversation object
Body
Examples
{
"ok" : true,
"channel" : {
"is_general" : false,
"name_normalized" : "endeavor",
"is_channel" : true,
"creator" : "U0123456",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 0,
"value" : "",
"creator" : ""
},
"unread_count_display" : 0,
"priority" : 0,
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [ ],
"last_read" : "0000000000.000000",
"id" : "C0EAQDV4Z",
"is_org_shared" : false,
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"purpose" : {
"last_set" : 0,
"value" : "",
"creator" : ""
},
"is_private" : false,
"is_shared" : false,
"name" : "endeavor",
"created" : 1504554479,
"pending_shared" : [ ],
"unread_count" : 0,
"unlinked" : 0,
"latest" : null
}
}Authentication
Reverses conversation archival.
Request headers
Authentication token. Requires scope: conversations:write
Request body
ID of conversation to unarchive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Authentication
Lists all channels in a Slack team.
Request parameters
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: conversations:read
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the list hasn’t been reached. Must be an integer no larger than 1000.
Set to true to exclude archived channels from the list
Mix and match channel types by providing a comma-separated list of any combination of public_channel, private_channel, mpim, im
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response with only public channels
Body
Examples
{
"channels" : [
{
"is_general" : true,
"name_normalized" : "general",
"is_channel" : true,
"creator" : "U012A3CDE",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 0,
"value" : "Company-wide announcements and work-based matters",
"creator" : ""
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [ ],
"id" : "C012AB3CD",
"is_org_shared" : false,
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"purpose" : {
"last_set" : 0,
"value" : "This channel is for team-wide communication and announcements. All team members are in this channel.",
"creator" : ""
},
"is_private" : false,
"is_shared" : false,
"num_members" : 4,
"name" : "general",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
},
{
"is_general" : false,
"name_normalized" : "random",
"is_channel" : true,
"creator" : "U061F7AUR",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 0,
"value" : "Non-work banter and water cooler conversation",
"creator" : ""
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [ ],
"id" : "C061EG9T2",
"is_org_shared" : false,
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"purpose" : {
"last_set" : 0,
"value" : "A place for non-work-related flimflam, faffing, hodge-podge or jibber-jabber you'd prefer to keep out of more focused work-related channels.",
"creator" : ""
},
"is_private" : false,
"is_shared" : false,
"num_members" : 4,
"name" : "random",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
}
],
"ok" : true,
"response_metadata" : {
"next_cursor" : "dGVhbTpDMDYxRkE1UEI="
}
}Authentication
Sets the topic for a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
The new topic string. Does not support formatting or linkification.
Conversation to set the topic of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Retrieve members of a conversation.
Request parameters
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: conversations:read
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
ID of the conversation to retrieve members for
Responses
Typical error response when an invalid cursor is provided
Body
Examples
{
"ok" : false,
"error" : "invalid_cursor"
}Typical paginated success response
Body
Examples
{
"ok" : true,
"response_metadata" : {
"next_cursor" : "e3VzZXJfaWQ6IFcxMjM0NTY3fQ=="
},
"members" : [
"U023BECGF",
"U061F7AUR",
"W012A3CDE"
]
}Authentication
Opens or resumes a direct message or multi-person direct message.
Request headers
Authentication token. Requires scope: conversations:write
Request body
Boolean, indicates you want the full IM channel definition in the response.
Comma separated lists of users. If only one user is included, this creates a 1:1 DM. The ordering of the users is preserved whenever a multi-person direct message is returned. Supply a channel when not supplying users.
Resume a conversation by supplying an im or mpim's ID. Or provide the users field instead.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"id" : "D069C7QFK"
}
}Authentication
Leaves a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
Conversation to leave
Responses
Typical error response when attempting to leave a workspace’s “general” channel
Body
Examples
{
"ok" : false,
"error" : "cant_leave_general"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Removes a user from a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
User ID to be removed.
ID of conversation to remove user from.
Responses
Typical error response when you attempt to kick yourself from a channel
Body
Examples
{
"ok" : false,
"error" : "cant_kick_self"
}Typical success response
Authentication
Renames a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
New name for conversation.
ID of conversation to rename
Responses
Typical error response when the calling user is not a member of the conversation
Body
Examples
{
"ok" : false,
"error" : "not_in_channel"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"is_general" : true,
"name_normalized" : "general",
"is_channel" : true,
"creator" : "W012A3BCD",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 1449709364,
"value" : "For public discussion of generalities",
"creator" : "W012A3BCD"
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [
"specifics",
"abstractions",
"etc"
],
"last_read" : "1502126650.228446",
"id" : "C012AB3CD",
"is_org_shared" : false,
"locale" : "en-US",
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"is_read_only" : false,
"purpose" : {
"last_set" : 1449709364,
"value" : "This part of the workspace is for fun. Make fun here.",
"creator" : "W012A3BCD"
},
"is_private" : false,
"is_shared" : false,
"num_members" : 23,
"name" : "general",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
}
}Authentication
Fetches a conversation’s history of messages and events.
Request parameters
Include messages with latest or oldest timestamp in results only when either timestamp is specified.
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: conversations:history
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
Start of time range of messages to include in results.
Conversation ID to fetch history for.
End of time range of messages to include in results.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response containing a channel’s messages
Body
Examples
{
"has_more" : true,
"messages" : [
{
"text" : "I find you punny and would like to smell your nose letter",
"type" : "message",
"user" : "U012AB3CDE",
"ts" : "1512085950.000216"
},
{
"text" : "What, you want to smell my shoes better?",
"type" : "message",
"user" : "U061F7AUR",
"ts" : "1512104434.000490"
}
],
"ok" : true,
"response_metadata" : {
"next_cursor" : "bmV4dF90czoxNTEyMDg1ODYxMDAwNTQz"
},
"pin_count" : 0
}Authentication
Sets the purpose for a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
A new, specialer purpose
Conversation to set the purpose of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Retrieve information about a conversation.
Request parameters
Authentication token. Requires scope: conversations:read
Conversation ID to learn more about
Set this to true to receive the locale for this conversation. Defaults to false
Responses
Typical error response when a channel cannot be found
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response for a public channel
Body
Examples
{
"ok" : true,
"channel" : {
"is_general" : true,
"name_normalized" : "general",
"is_channel" : true,
"creator" : "W012A3BCD",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 1449709364,
"value" : "For public discussion of generalities",
"creator" : "W012A3BCD"
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [
"specifics",
"abstractions",
"etc"
],
"last_read" : "1502126650.228446",
"id" : "C012AB3CD",
"is_org_shared" : false,
"locale" : "en-US",
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"is_read_only" : false,
"purpose" : {
"last_set" : 1449709364,
"value" : "This part of the workspace is for fun. Make fun here.",
"creator" : "W012A3BCD"
},
"is_private" : false,
"is_shared" : false,
"num_members" : 23,
"name" : "general",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
}
}Authentication
Invites users to a channel.
Request headers
Authentication token. Requires scope: conversations:write
Request body
A comma separated list of user IDs. Up to 30 users may be listed.
The ID of the public or private channel to invite user(s) to.
Responses
Typical error response when an invite is attempted on a conversation type that does not support it
Body
Examples
{
"ok" : false,
"error" : "method_not_supported_for_channel_type"
}Typical success response when an invitation is extended
Body
Examples
{
"ok" : true,
"channel" : {
"is_general" : true,
"name_normalized" : "general",
"is_channel" : true,
"creator" : "W012A3BCD",
"is_member" : true,
"is_archived" : false,
"topic" : {
"last_set" : 1449709364,
"value" : "For public discussion of generalities",
"creator" : "W012A3BCD"
},
"is_im" : false,
"is_ext_shared" : false,
"previous_names" : [
"specifics",
"abstractions",
"etc"
],
"last_read" : "1502126650.228446",
"id" : "C012AB3CD",
"is_org_shared" : false,
"locale" : "en-US",
"is_pending_ext_shared" : false,
"is_mpim" : false,
"is_group" : false,
"is_read_only" : false,
"purpose" : {
"last_set" : 1449709364,
"value" : "This part of the workspace is for fun. Make fun here.",
"creator" : "W012A3BCD"
},
"is_private" : false,
"is_shared" : false,
"num_members" : 23,
"name" : "general",
"created" : 1449252889,
"pending_shared" : [ ],
"unlinked" : 0
}
}Authentication
Archives a conversation.
Request headers
Authentication token. Requires scope: conversations:write
Request body
ID of conversation to archive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Authentication
Retrieve a thread of messages posted to a conversation
Request parameters
Include messages with latest or oldest timestamp in results only when either timestamp is specified.
Unique identifier of a thread’s parent message.
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: conversations:history
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
Start of time range of messages to include in results.
Conversation ID to fetch thread from.
End of time range of messages to include in results.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "thread_not_found"
}Typical success response
Body
Examples
{
"has_more" : true,
"ok" : true,
"messages" : [
{
"thread_ts" : "1482960137.003543",
"last_read" : "1484678597.521003",
"subscribed" : true,
"text" : "island",
"ts" : "1482960137.003543",
"unread_count" : 0,
"reply_count" : 3,
"user" : "U061F7AUR",
"replies" : [
{
"user" : "U061F7AUR",
"ts" : "1483037603.017503"
},
{
"user" : "U061F7AUR",
"ts" : "1483051909.018632"
},
{
"user" : "U061F7AUR",
"ts" : "1483125339.020269"
}
],
"type" : "message"
},
{
"thread_ts" : "1482960137.003543",
"text" : "one island",
"ts" : "1483037603.017503",
"user" : "U061F7AUR",
"parent_user_id" : "U061F7AUR",
"type" : "message"
},
{
"thread_ts" : "1482960137.003543",
"text" : "two island",
"ts" : "1483051909.018632",
"user" : "U061F7AUR",
"parent_user_id" : "U061F7AUR",
"type" : "message"
},
{
"thread_ts" : "1482960137.003543",
"text" : "three for the land",
"ts" : "1483125339.020269",
"user" : "U061F7AUR",
"parent_user_id" : "U061F7AUR",
"type" : "message"
}
],
"response_metadata" : {
"next_cursor" : "bmV4dF90czoxNDg0Njc4MjkwNTE3MDkx"
}
}Authentication
Gets the integration logs for the current team.
Request parameters
Filter logs with this change type. Defaults to all logs.
Filter logs to this Slack app. Defaults to all logs.
Authentication token. Requires scope: admin
Filter logs generated by this user’s actions. Defaults to all logs.
Filter logs to this service. Defaults to all logs.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets billable users information for the current team.
Request parameters
Authentication token. Requires scope: admin
A user to retrieve the billable information for. Defaults to all users.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets the access logs for the current team.
Request parameters
Authentication token. Requires scope: admin
End of time range of logs to include in results (inclusive).
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about the current team.
Request parameters
Authentication token. Requires scope: team:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Retrieves a user’s current Do Not Disturb status.
Request parameters
Authentication token. Requires scope: dnd:read
User to fetch status for (defaults to current user)
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Ends the current user’s Do Not Disturb session immediately.
Request headers
Authentication token. Requires scope: dnd:write
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Turns on Do Not Disturb mode for the current user, or changes its duration.
Request body
Number of minutes, from now, to snooze until.
Authentication token. Requires scope: dnd:write
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Ends the current user’s snooze mode immediately.
Request headers
Authentication token. Requires scope: dnd:write
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Retrieves the Do Not Disturb status for users on a team.
Request parameters
Authentication token. Requires scope: dnd:read
Comma-separated list of users to fetch Do Not Disturb status for
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"users" : {
"W058CJVAA" : {
"dnd_enabled" : false,
"next_dnd_end_ts" : 1,
"next_dnd_start_ts" : 1
},
"U023BECGF" : {
"dnd_enabled" : true,
"next_dnd_end_ts" : 1450423800,
"next_dnd_start_ts" : 1450387800
}
}
}Authentication
Archives a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Channel to archive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about a channel.
Request parameters
Authentication token. Requires scope: channels:read
Set this to true to receive the locale for this channel. Defaults to false
Channel to get info on
Responses
Error response when the specified channel cannot be found
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"topic" : {
"last_set" : 1503435128,
"value" : "Spiritual containment strategies",
"creator" : "U0G9QF9C6"
},
"is_general" : false,
"name_normalized" : "busting",
"name" : "busting",
"is_channel" : true,
"created" : 1466025154,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U0G9QF9C6",
"is_org_shared" : false,
"unread_count" : 1,
"previous_names" : [
"dusting"
],
"purpose" : {
"last_set" : 1503435128,
"value" : "Discuss busting ghosts",
"creator" : "U0G9QF9C6"
},
"unread_count_display" : 1,
"last_read" : "1503435939.000101",
"latest" : {
"username" : "ecto1138",
"attachments" : [
{
"text" : "Don't get too attached",
"fallback" : "This is an attachment fallback",
"id" : 1
}
],
"text" : "Containment unit is 98% full",
"ts" : "1503435956.000247",
"subtype" : "bot_message",
"type" : "message",
"bot_id" : "B19LU7CSY"
},
"members" : [
"U0G9QF9C6",
"U1QNSQB9U"
],
"id" : "C1H9RESGL",
"is_private" : false,
"is_shared" : false
}
}Authentication
Removes a user from a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
User to remove from channel.
Channel to remove user from.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "not_in_channel"
}Typical success response
Authentication
Fetches history of messages and events from a channel.
Request parameters
Number of messages to return, between 1 and 1000.
Include unread_count_display in the output?
Include messages with latest or oldest timestamp in results.
Authentication token. Requires scope: channels:history
Start of time range of messages to include in results.
Channel to fetch history for.
End of time range of messages to include in results.
Responses
Error response when the specified channel cannot be found
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response containing the channel’s history
Body
Examples
{
"has_more" : false,
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"reactions" : [
{
"count" : 3,
"name" : "space_invader",
"users" : [
"U1",
"U2",
"U3"
]
},
{
"count" : 5,
"name" : "sweet_potato",
"users" : [
"U1",
"U2",
"U3",
"U4",
"U5"
]
}
],
"text" : "World",
"ts" : "1358546515.000007",
"user" : "U2147483896",
"is_starred" : true,
"type" : "message"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
},
{
"username" : "ecto1138",
"attachments" : [
{
"text" : "Don't get too attached",
"fallback" : "This is an attachment fallback",
"id" : 1
}
],
"text" : "Containment unit is 98% full",
"ts" : "1503435956.000247",
"subtype" : "bot_message",
"type" : "message",
"bot_id" : "B19LU7CSY"
}
],
"ok" : true,
"latest" : "1358547726.000003"
}Authentication
Leaves a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Channel to leave
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Renames a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Whether to return errors on invalid channel name instead of modifying it to meet the specified criteria.
New name for channel.
Channel to rename
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"previous_names" : [
"humans"
],
"is_general" : false,
"name_normalized" : "humans-and-bots",
"is_shared" : false,
"is_channel" : true,
"creator" : "U2U85N1RZ",
"is_member" : false,
"is_mpim" : false,
"is_archived" : false,
"created" : 1477445146,
"is_org_shared" : false,
"topic" : {
"last_set" : 1509475775,
"value" : "here be robots",
"creator" : "U2U85N1RZ"
},
"purpose" : {
"last_set" : 1509475801,
"value" : "the purpose of this channel is to bring people and robots together in harmony",
"creator" : "U2U85N1RZ"
},
"members" : [ ],
"unlinked" : 0,
"id" : "C2U875RJN",
"is_private" : false,
"name" : "humans-and-bots"
}
}Authentication
Sets the read cursor in a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Timestamp of the most recently seen message.
Channel to set reading cursor in.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Unarchives a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Channel to unarchive
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Creates a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
Whether to return errors on invalid channel name instead of modifying it to meet the specified criteria.
Name of channel to create
Responses
Example error response when an invalid name is provided
Body
Examples
{
"ok" : false,
"detail" : "Value passed for `name` contained unallowed special characters.",
"error" : "invalid_name_specials"
}Typical success response resulting in a new channel
Body
Examples
{
"ok" : true,
"channel" : {
"topic" : {
"last_set" : 0,
"value" : "",
"creator" : ""
},
"is_general" : false,
"name_normalized" : "endeavor",
"name" : "endeavor",
"is_channel" : true,
"created" : 1502833204,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U061F7AUR",
"is_org_shared" : false,
"unread_count" : 0,
"previous_names" : [ ],
"purpose" : {
"last_set" : 0,
"value" : "",
"creator" : ""
},
"unread_count_display" : 0,
"last_read" : "0000000000.000000",
"latest" : null,
"members" : [
"U061F7AUR"
],
"id" : "C0DEL09A5",
"is_private" : false,
"is_shared" : false
}
}Authentication
Joins a channel, creating it if needed.
Request headers
Authentication token. Requires scope: channels:write
Request body
Whether to return errors on invalid channel name instead of modifying it to meet the specified criteria.
Name of channel to join
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"already_in_channel" : true,
"ok" : true,
"channel" : {
"topic" : {
"last_set" : 1503435128,
"value" : "My Topic",
"creator" : "U0G9QF9C6"
},
"is_general" : false,
"name_normalized" : "busting",
"name" : "busting",
"is_channel" : true,
"created" : 1466025154,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U0G9QF9C6",
"is_org_shared" : false,
"previous_names" : [ ],
"purpose" : {
"last_set" : 1503435128,
"value" : "My Purpose",
"creator" : "U0G9QF9C6"
},
"members" : [
"U0G9QF9C6",
"U1QNSQB9U"
],
"id" : "C1H9RESGL",
"is_private" : false,
"is_shared" : false
}
}Authentication
Sets the topic for a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
The new topic
Channel to set the topic of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"topic" : "To picture topicality",
"ok" : true
}Authentication
Sets the purpose for a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
The new purpose
Channel to set the purpose of
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"purpose" : "My special purpose"
}Authentication
Lists all channels in a Slack team.
Request parameters
Exclude the members collection from each channel
Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request’s response_metadata. Default value fetches the first “page” of the collection. See pagination for more detail.
Authentication token. Requires scope: channels:read
The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the users list hasn’t been reached.
Exclude archived channels from the list
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical cursored success response
Body
Examples
{
"channels" : [
{
"topic" : {
"last_set" : 1449709352,
"value" : "Other stuff",
"creator" : "U0G9QF9C6"
},
"is_general" : false,
"name_normalized" : "random",
"name" : "random",
"is_channel" : true,
"created" : 1449709280,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U0G9QF9C6",
"is_org_shared" : false,
"previous_names" : [ ],
"num_members" : 2,
"purpose" : {
"last_set" : 0,
"value" : "A place for non-work-related flimflam, faffing, hodge-podge or jibber-jabber you'd prefer to keep out of more focused work-related channels.",
"creator" : ""
},
"members" : [
"U0G9QF9C6",
"U0G9WFXNZ"
],
"id" : "C0G9QF9GW",
"is_private" : false,
"is_shared" : false
},
{
"topic" : {
"last_set" : 1449709364,
"value" : "Talk about anything!",
"creator" : "U0G9QF9C6"
},
"is_general" : true,
"name_normalized" : "general",
"name" : "general",
"is_channel" : true,
"created" : 1449709280,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U0G9QF9C6",
"is_org_shared" : false,
"previous_names" : [ ],
"num_members" : 2,
"purpose" : {
"last_set" : 1449709334,
"value" : "To talk about anything!",
"creator" : "U0G9QF9C6"
},
"members" : [
"U0G9QF9C6",
"U0G9WFXNZ"
],
"id" : "C0G9QKBBL",
"is_private" : false,
"is_shared" : false
}
],
"ok" : true,
"response_metadata" : {
"next_cursor" : "dGVhbTpDMUg5UkVTR0w="
}
}Authentication
Invites a user to a channel.
Request headers
Authentication token. Requires scope: channels:write
Request body
User to invite to channel.
Channel to invite user to.
Responses
A somewhat typical error response
Body
Examples
{
"ok" : false,
"error" : "cant_invite"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"topic" : {
"last_set" : 1503435128,
"value" : "My Topic",
"creator" : "U0G9QF9C6"
},
"is_general" : false,
"name_normalized" : "busting",
"name" : "busting",
"is_channel" : true,
"created" : 1466025154,
"is_member" : true,
"is_mpim" : false,
"is_archived" : false,
"creator" : "U0G9QF9C6",
"is_org_shared" : false,
"unread_count" : 0,
"previous_names" : [ ],
"purpose" : {
"last_set" : 1503435128,
"value" : "My Purpose",
"creator" : "U0G9QF9C6"
},
"unread_count_display" : 0,
"last_read" : "1503435963.000307",
"latest" : {
"text" : "<@U1QNSQB9U|protobot> has left the channel",
"type" : "message",
"user" : "U1QNSQB9U",
"ts" : "1503435963.000307",
"subtype" : "channel_leave"
},
"members" : [
"U0G9QF9C6",
"U1QNSQB9U"
],
"id" : "C1H9RESGL",
"is_private" : false,
"is_shared" : false
}
}Authentication
Retrieve a thread of messages posted to a channel
Request parameters
Unique identifier of a thread’s parent message
Authentication token. Requires scope: channels:history
Channel to fetch thread from
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "thread_not_found"
}Typical success response
Body
Examples
{
"has_more" : false,
"ok" : true,
"messages" : [
{
"thread_ts" : "1485913694.000025",
"last_read" : "1509484885.000082",
"subscribed" : true,
"text" : "This is a channel message",
"ts" : "1485913694.000025",
"unread_count" : 0,
"reply_count" : 2,
"user" : "U2X9P5FEL",
"replies" : [
{
"ts" : "1509484424.000601",
"user" : "U2U85N1RZ"
},
{
"ts" : "1509484885.000082",
"user" : "U2U85N1RZ"
}
],
"type" : "message"
},
{
"thread_ts" : "1485913694.000025",
"text" : "This is a thread reply",
"ts" : "1509484424.000601",
"user" : "U2U85N1RZ",
"parent_user_id" : "U2X9P5FEL",
"type" : "message"
},
{
"thread_ts" : "1485913694.000025",
"text" : "This is another thread reply",
"ts" : "1509484885.000082",
"user" : "U2U85N1RZ",
"parent_user_id" : "U2X9P5FEL",
"type" : "message"
}
]
}Authentication
Gets information about a reminder.
Request parameters
Authentication token. Requires scope: reminders:read
The ID of the reminder
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Marks a reminder as complete.
Request headers
Authentication token. Requires scope: reminders:write
Request body
The ID of the reminder to be marked as complete
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Lists all reminders created by or for a given user.
Request parameters
Authentication token. Requires scope: reminders:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Creates a reminder.
Request headers
Authentication token. Requires scope: reminders:write
Request body
The content of the reminder
The user who will receive the reminder. If no user is specified, the reminder will go to user who created it.
When this reminder should happen: the Unix timestamp (up to five years from now), the number of seconds until the reminder (if within 24 hours), or a natural language description (Ex. “in 15 minutes,” or “every Thursday”)
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Deletes a reminder.
Request headers
Authentication token. Requires scope: reminders:write
Request body
The ID of the reminder
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Closes a multiparty direct message channel.
Request headers
Authentication token. Requires scope: mpim:write
Request body
MPIM to close.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Sets the read cursor in a multiparty direct message channel.
Request headers
Authentication token. Requires scope: mpim:write
Request body
Timestamp of the most recently seen message.
multiparty direct message channel to set reading cursor in.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Fetches history of messages and events from a multiparty direct message.
Request parameters
Number of messages to return, between 1 and 1000.
Include unread_count_display in the output?
Include messages with latest or oldest timestamp in results.
Authentication token. Requires scope: mpim:history
Start of time range of messages to include in results.
Multiparty direct message to fetch history for.
End of time range of messages to include in results.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"has_more" : false,
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true,
"latest" : "1358547726.000003"
}Authentication
This method opens a multiparty direct message.
Request headers
Authentication token. Requires scope: mpim:write
Request body
Comma separated lists of users. The ordering of the users is preserved whenever a MPIM group is returned.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"channel" : {
"id" : "D024BFF1M"
}
}Authentication
Retrieve a thread of messages posted to a direct message conversation from a multiparty direct message.
Request parameters
Unique identifier of a thread’s parent message.
Authentication token. Requires scope: mpim:history
Multiparty direct message channel to fetch thread from.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Body
Examples
{
"messages" : [
{
"text" : "Hello",
"type" : "message",
"ts" : "1358546515.000008",
"user" : "U2147483896"
},
{
"text" : "World",
"is_starred" : true,
"type" : "message",
"ts" : "1358546515.000007",
"user" : "U2147483896"
},
{
"type" : "something_else",
"ts" : "1358546515.000007"
}
],
"ok" : true
}Authentication
Lists multiparty direct message channels for the calling user.
Request parameters
Authentication token. Requires scope: mpim:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Exchanges a temporary OAuth verifier code for a workspace token.
Request parameters
Issued when you created your application.
The code param returned via the OAuth callback.
Request the user to add your app only to a single channel.
Issued when you created your application.
This must match the originally submitted URI (if one was sent).
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Exchanges a temporary OAuth code for an API token.
Request parameters
Issued when you created your application.
The code param returned via the OAuth callback.
Issued when you created your application.
This must match the originally submitted URI (if one was sent).
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Uploads or creates a file.
Request body
Comma-separated list of channel names or IDs where the file will be shared.
Title of file.
Initial comment to add to file.
A file type identifier.
Filename of file.
File contents via a POST variable. If omitting this parameter, you must provide a file.
Authentication token. Requires scope: files:write:user
File contents via multipart/form-data. If omitting this parameter, you must submit content.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Revokes public/external sharing access for a file
Request headers
Authentication token. Requires scope: files:write:user
Request body
File to revoke
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Lists & filters team files.
Request parameters
Filter files appearing in a specific channel, indicated by its ID.
Filter files created before this timestamp (inclusive).
Filter files created after this timestamp (inclusive).
Authentication token. Requires scope: files:read
Filter files created by a single user.
Filter files by type:
all- All filesspaces- Postssnippets- Snippetsimages- Image filesgdocs- Google docszips- Zip filespdfs- PDF files
You can pass multiple values in the types argument, like types=spaces,snippets.The default value is all, which does not filter the list.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Deletes a file.
Request headers
Authentication token. Requires scope: files:write:user
Request body
ID of file to delete.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Gets information about a team file.
Request parameters
Authentication token. Requires scope: files:read
Specify a file by providing its ID.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true
}Authentication
Enables a file for public/external sharing.
Request headers
Authentication token. Requires scope: files:write:user
Request body
File to share
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
List all users in a User Group
Request parameters
Authentication token. Requires scope: usergroups:read
Allow results that involve disabled User Groups.
The encoded ID of the User Group to update.
Responses
Standard failure response when used with an invalid token
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Standard success response when used with a user token
Body
Examples
{
"ok" : true,
"users" : [
"U060R4BJ4",
"W123A4BC5"
]
}Authentication
Update the list of users for a User Group
Request headers
Authentication token. Requires scope: usergroups:write
Request body
Include the number of users in the User Group.
A comma separated string of encoded user IDs that represent the entire list of users for the User Group.
The encoded ID of the User Group to update.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"usergroup" : {
"is_external" : false,
"handle" : "marketing-team",
"description" : "Marketing gurus, PR experts and product advocates.",
"date_delete" : 0,
"date_update" : 1447102109,
"created_by" : "U060R4BJ4",
"deleted_by" : null,
"date_create" : 1447096577,
"team_id" : "T060R4BHN",
"updated_by" : "U060R4BJ4",
"user_count" : 1,
"auto_type" : null,
"prefs" : {
"channels" : [ ],
"groups" : [ ]
},
"users" : [
"U060R4BJ4",
"U060RNRCZ"
],
"is_usergroup" : true,
"id" : "S0616NG6M",
"name" : "Marketing Team"
}
}Authentication
Lists reactions made by a user.
Request parameters
Authentication token. Requires scope: reactions:read
If true always return the complete reaction list.
Show reactions made by this user. Defaults to the authed user.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"items" : [
{
"message" : {
"username" : "Shipit Notifications",
"reactions" : [
{
"count" : 1,
"name" : "robot_face",
"users" : [
"U2U85N1RV"
]
}
],
"text" : "Hello from Python! :tada:",
"ts" : "1507849573.000090",
"subtype" : "bot_message",
"bot_id" : "B4VLRLMKJ"
},
"type" : "message",
"channel" : "C3UKJTQAC"
},
{
"comment" : {
"comment" : "This is a file comment",
"reactions" : [
{
"count" : 1,
"name" : "white_check_mark",
"users" : [
"U2U85N1RV"
]
}
],
"created" : 1508286096,
"timestamp" : 1508286096,
"user" : "U2U85N1RV",
"type" : "file_comment",
"id" : "Fc7LP08P1U"
},
"file" : {
"username" : "",
"reactions" : [
{
"count" : 1,
"name" : "stuck_out_tongue_winking_eye",
"users" : [
"U2U85N1RV"
]
}
],
"title" : "computer.gif",
"created" : 1507850315,
"channels" : [
"C2U7V2YA2"
],
"comments_count" : 1,
"user" : "U2U85N1RV"
}
},
{
"type" : "file",
"file" : {
"username" : "",
"reactions" : [
{
"count" : 1,
"name" : "stuck_out_tongue_winking_eye",
"users" : [
"U2U85N1RV"
]
}
],
"name" : "computer.gif",
"created" : 1507850315,
"title" : "computer.gif",
"channels" : [
"C2U7V2YA2"
],
"comments_count" : 1,
"user" : "U2U85N1RV",
"id" : "F7H0D7ZA4",
"size" : 1639034
}
}
],
"paging" : {
"count" : 100,
"total" : 3,
"page" : 1,
"pages" : 1
},
"ok" : true
}Authentication
Adds a reaction to an item.
Request headers
Authentication token. Requires scope: reactions:write
Request body
Reaction (emoji) name.
File comment to add reaction to.
Timestamp of the message to add reaction to.
File to add reaction to.
Channel where the message to add reaction to was posted.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "already_reacted"
}Typical success response
Authentication
Gets reactions for an item.
Request parameters
If true always return the complete reaction list.
File comment to get reactions for.
Timestamp of the message to get reactions for.
Authentication token. Requires scope: reactions:read
File to get reactions for.
Channel where the message to get reactions for was posted.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"type" : "file",
"ok" : true,
"file" : {
"reactions" : [
{
"count" : 1,
"name" : "stuck_out_tongue_winking_eye",
"users" : [
"U2U85N1RV"
]
}
],
"name" : "computer.gif",
"created" : 1507850315,
"timestamp" : 1507850315,
"title" : "computer.gif",
"channels" : [
"C2U7V2YA2"
],
"ims" : [ ],
"comments_count" : 1,
"user" : "U2U85N1RV",
"groups" : [ ],
"id" : "F7H0D7ZA4"
}
}Authentication
Removes a reaction from an item.
Request headers
Authentication token. Requires scope: reactions:write
Request body
Reaction (emoji) name.
File comment to remove reaction from.
Timestamp of the message to remove reaction from.
File to remove reaction from.
Channel where the message to remove reaction from was posted.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "no_reaction"
}Typical success response
Authentication
Searches for messages and files matching a query.
Request parameters
Change sort direction to ascending (asc) or descending (desc).
Search query. May contains booleans, etc.
Return matches sorted by either score or timestamp.
Authentication token. Requires scope: search:read
Pass a value of true to enable query highlight markers (see below).
Responses
Typical error response
Body
Examples
{
"needed" : "search:read",
"provided" : "identify,bot:basic",
"ok" : false,
"error" : "missing_scope"
}Typical success response
Body
Examples
{
"files" : {
"matches" : [
{
"groups" : [ ],
"initial_comment" : {
"comment" : "Sure! Here's the workflow diagram!",
"created" : 1508804330,
"timestamp" : 1508804330,
"is_intro" : true,
"user" : "U2U85N1RZ",
"id" : "Fc7NLL52E7"
},
"filetype" : "png",
"channels" : [ ],
"display_as_bot" : false,
"id" : "F7PKF1NR7",
"size" : 35705,
"original_h" : 117,
"thumb_360_w" : 128,
"title" : "slack workflow diagram",
"url_private" : "https://files.slack.com/files-pri/T2U81E2FZ-F7PKF1NR7/slack_workflow_diagram.png",
"thumb_360" : "https://files.slack.com/files-tmb/T2U81E2FZ-F7PKF1NR7-19f33fc256/slack_workflow_diagram_360.png",
"thumb_64" : "https://files.slack.com/files-tmb/T2U81E2FZ-F7PKF1NR7-19f33fc256/slack_workflow_diagram_64.png",
"ims" : [ ],
"score" : "0.99982661240974",
"top_file" : false,
"thumb_80" : "https://files.slack.com/files-tmb/T2U81E2FZ-F7PKF1NR7-19f33fc256/slack_workflow_diagram_80.png",
"thumb_360_h" : 117,
"preview" : null,
"original_w" : 128,
"username" : "amy",
"timestamp" : 1508804330,
"public_url_shared" : false,
"editable" : false,
"thumb_160" : "https://files.slack.com/files-tmb/T2U81E2FZ-F7PKF1NR7-19f33fc256/slack_workflow_diagram_160.png",
"url_private_download" : "https://files.slack.com/files-pri/T2U81E2FZ-F7PKF1NR7/download/slack_workflow_diagram.png",
"user" : "U2U85N1RZ",
"image_exif_rotation" : 1,
"is_public" : true,
"pretty_type" : "PNG",
"is_external" : false,
"mimetype" : "image/png",
"permalink_public" : "https://slack-files.com/T2U81E2FZ-F7PKF1NR7-bea9143f18",
"permalink" : "https://example.slack.com/files/U2U85N1RZ/F7PKF1NR7/slack_workflow_diagram.png",
"name" : "slack workflow diagram.png",
"created" : 1508804330,
"external_type" : "",
"comments_count" : 1,
"mode" : "hosted"
}
],
"pagination" : {
"last" : 1,
"total_count" : 1,
"page_count" : 1,
"per_page" : 20,
"page" : 1,
"first" : 1
},
"total" : 1,
"paging" : {
"count" : 20,
"total" : 1,
"page" : 1,
"pages" : 1
}
},
"ok" : true,
"messages" : {
"matches" : [
{
"username" : "amy",
"permalink" : "https://example.slack.com/archives/C2U86NC6M/p1508804330000296",
"text" : "uploaded a file: <https://example.slack.com/files/U2U85N1RZ/F7PKF1NR7/slack_workflow_diagram.png|slack workflow diagram> and commented: Sure! Here's the workflow diagram!",
"ts" : "1508804330.000296",
"next" : {
"username" : "john",
"text" : "Thanks!",
"ts" : "1508804378.000219",
"iid" : "6f510ea1-e1d3-4f3f-bdb9-f9c6f6e9d609",
"user" : "U2U85HJ7R",
"type" : "message"
},
"iid" : "35692677-e60e-43d9-ac45-1987cea88975",
"user" : "U2U85N1RZ",
"team" : "T2U81E2FZ",
"type" : "message",
"channel" : {
"is_pending_ext_shared" : false,
"is_shared" : false,
"is_mpim" : false,
"pending_shared" : [ ],
"is_ext_shared" : false,
"is_org_shared" : false,
"id" : "C2U86NC6M",
"is_private" : false,
"name" : "general"
},
"previous" : {
"username" : "john",
"text" : "Can you send me the Slack workflow diagram?",
"ts" : "1508804301.000026",
"iid" : "aba8603c-0543-4fb2-9118-a5ac85f3d138",
"user" : "U2U85HJ7R",
"type" : "message"
}
}
],
"pagination" : {
"last" : 1,
"total_count" : 1,
"page_count" : 1,
"per_page" : 20,
"page" : 1,
"first" : 1
},
"total" : 1,
"paging" : {
"count" : 20,
"total" : 1,
"page" : 1,
"pages" : 1
}
},
"posts" : {
"matches" : [ ],
"total" : 0
},
"query" : "diagram"
}Authentication
Searches for files matching a query.
Request parameters
Change sort direction to ascending (asc) or descending (desc).
Search query. May contain booleans, etc.
Return matches sorted by either score or timestamp.
Pass a value of true to enable query highlight markers (see below).
Authentication token. Requires scope: search:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "No query passed"
}Typical success response
Body
Examples
{
"files" : {
"matches" : [
{
"thumb_480_w" : 480,
"reactions" : [
{
"count" : 1,
"name" : "stuck_out_tongue_winking_eye",
"users" : [
"U2U85N1RZ"
]
}
],
"thumb_480_gif" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_480.gif",
"groups" : [ ],
"filetype" : "gif",
"channels" : [ ],
"display_as_bot" : false,
"id" : "F7H0D7ZBB",
"size" : 1639034,
"original_h" : 313,
"thumb_360_w" : 360,
"title" : "computer.gif",
"url_private" : "https://files.slack.com/files-pri/T2U81E2BB-F7H0D7ZBB/computer.gif",
"thumb_360" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_360.png",
"thumb_480" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_480.png",
"thumb_64" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_64.png",
"ims" : [ ],
"score" : "0.38899223746309",
"top_file" : false,
"thumb_80" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_80.png",
"thumb_360_h" : 225,
"preview" : null,
"original_w" : 500,
"username" : "",
"timestamp" : 1507850315,
"public_url_shared" : false,
"editable" : false,
"thumb_160" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_160.png",
"thumb_480_h" : 300,
"thumb_360_gif" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_360.gif",
"user" : "U2U85N1RZ",
"image_exif_rotation" : 1,
"is_public" : true,
"pretty_type" : "GIF",
"is_external" : false,
"mimetype" : "image/gif",
"permalink_public" : "https://slack-files.com/T2U81E2BB-F7H0D7ZBB-85b7f5557e",
"permalink" : "https://eventsdemo.slack.com/files/U2U85N1RZ/F7H0D7ZBB/computer.gif",
"name" : "computer.gif",
"created" : 1507850315,
"url_private_download" : "https://files.slack.com/files-pri/T2U81E2BB-F7H0D7ZBB/download/computer.gif",
"external_type" : "",
"comments_count" : 1,
"mode" : "hosted",
"deanimate_gif" : "https://files.slack.com/files-tmb/T2U81E2BB-F7H0D7ZBB-21624821e6/computer_deanimate_gif.png"
}
],
"pagination" : {
"last" : 3,
"total_count" : 3,
"page_count" : 1,
"per_page" : 20,
"page" : 1,
"first" : 1
},
"total" : 3,
"paging" : {
"count" : 20,
"total" : 3,
"page" : 1,
"pages" : 1
}
},
"query" : "computer.gif",
"ok" : true
}Authentication
Searches for messages matching a query.
Request parameters
Change sort direction to ascending (asc) or descending (desc).
Search query. May contains booleans, etc.
Return matches sorted by either score or timestamp.
Pass the number of results you want per “page”. Maximum of 100.
Authentication token. Requires scope: search:read
Pass a value of true to enable query highlight markers (see below).
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "No query passed"
}Typical success response
Body
Examples
{
"ok" : true,
"messages" : {
"matches" : [
{
"username" : "roach",
"permalink" : "https://hitchhikers.slack.com/archives/C12345678/p1508284197000015",
"text" : "The meaning of life the universe and everything is 42.",
"ts" : "1508284197.000015",
"iid" : "cb64bdaa-c1e8-4631-8a91-0f78080113e9",
"user" : "U2U85N1RV",
"team" : "T12345678",
"type" : "message",
"channel" : {
"is_pending_ext_shared" : false,
"is_shared" : false,
"is_mpim" : false,
"pending_shared" : [ ],
"is_ext_shared" : false,
"is_org_shared" : false,
"id" : "C12345678",
"is_private" : false,
"name" : "general"
}
},
{
"username" : "robot overlord",
"permalink" : "https://hitchhikers.slack.com/archives/C12345678/p1508795665000236",
"text" : "The meaning of life the universe and everything is 101010",
"ts" : "1508795665.000236",
"iid" : "9a00d3c9-bd2d-45b0-988b-6cff99ae2a90",
"user" : "",
"team" : "T12345678",
"type" : "message",
"channel" : {
"is_pending_ext_shared" : false,
"is_shared" : false,
"is_mpim" : false,
"pending_shared" : [ ],
"is_ext_shared" : false,
"is_org_shared" : false,
"id" : "C12345678",
"is_private" : false,
"name" : "random"
}
}
],
"pagination" : {
"last" : 2,
"total_count" : 2,
"page_count" : 1,
"per_page" : 20,
"page" : 1,
"first" : 1
},
"total" : 2,
"paging" : {
"count" : 20,
"total" : 2,
"page" : 1,
"pages" : 1
}
},
"query" : "The meaning of life the universe and everything"
}Authentication
Revokes a token.
Request parameters
Setting this parameter to 1 triggers a testing mode where the specified token will not actually be revoked.
Authentication token. Requires scope: none
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Checks authentication & identity.
Request headers
Authentication token. Requires scope: none
Responses
Standard failure response when used with an invalid token
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Standard success response when used with a user token
Body
Examples
{
"user_id" : "W12345678",
"url" : "https://subarachnoid.slack.com/",
"team_id" : "T12345678",
"user" : "grace",
"team" : "Subarachnoid Workspace",
"ok" : true
}Authentication
Adds a star to an item.
Request headers
Authentication token. Requires scope: stars:write
Request body
File comment to add star to.
Timestamp of the message to add star to.
Channel to add star to, or channel where the message to add star to was posted (used with timestamp).
File to add star to.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Lists stars for a user.
Request parameters
Authentication token. Requires scope: stars:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Removes a star from an item.
Request headers
Authentication token. Requires scope: stars:write
Request body
File comment to remove star from.
Timestamp of the message to remove star from.
Channel to remove star from, or channel where the message to remove star from was posted (used with timestamp).
File to remove star from.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Pins an item to a channel.
Request headers
Authentication token. Requires scope: pins:write
Request body
File comment to pin.
Timestamp of the message to pin.
File to pin.
Channel to pin the item in.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "channel_not_found"
}Typical success response
Authentication
Un-pins an item from a channel.
Request headers
Authentication token. Requires scope: pins:write
Request body
File comment to un-pin.
Timestamp of the message to un-pin.
File to un-pin.
Channel where the item is pinned to.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "no_pin"
}Typical success response
Authentication
Lists items pinned to a channel.
Request parameters
Authentication token. Requires scope: pins:read
Channel to get pinned items for.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"items" : [
{
"message" : {
"permalink" : "https://hitchhikers.slack.com/archives/C2U86NC6H/p1508197641000151",
"text" : "What is the meaning of life?",
"ts" : "1508197641.000151",
"pinned_to" : [
"C2U86NC6H"
],
"user" : "U2U85N1RZ",
"type" : "message"
},
"type" : "message",
"created_by" : "U2U85N1RZ",
"channel" : "C2U86NC6H",
"created" : 1508881078
},
{
"message" : {
"permalink" : "https://hitchhikers.slack.com/archives/C2U86NC6H/p1508284197000015",
"text" : "The meaning of life, the universe, and everything is 42.",
"ts" : "1503289197.000015",
"pinned_to" : [
"C2U86NC6H"
],
"user" : "U2U85N1RZ",
"type" : "message"
},
"type" : "message",
"created_by" : "U2U85N1RZ",
"channel" : "C2U86NC6H",
"created" : 1508880991
}
],
"ok" : true
}Authentication
Checks API calling code.
Request parameters
example property to return
Error response to return
Responses
Artificial error response
Body
Examples
{
"args" : {
"error" : "my_error"
},
"ok" : false,
"error" : "my_error"
}Standard success response
Authentication
Update an existing User Group
Request headers
Authentication token. Requires scope: usergroups:write
Request body
A mention handle. Must be unique among channels, users and User Groups.
A short description of the User Group.
A comma separated string of encoded channel IDs for which the User Group uses as a default.
Include the number of users in the User Group.
The encoded ID of the User Group to update.
A name for the User Group. Must be unique among User Groups.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"ok" : true,
"usergroup" : {
"is_external" : false,
"handle" : "marketing-team",
"description" : "Marketing gurus, PR experts and product advocates.",
"date_delete" : 0,
"date_update" : 1447102109,
"created_by" : "U060R4BJ4",
"deleted_by" : null,
"date_create" : 1447096577,
"team_id" : "T060R4BHN",
"updated_by" : "U060R4BJ4",
"user_count" : 1,
"auto_type" : null,
"prefs" : {
"channels" : [ ],
"groups" : [ ]
},
"users" : [
"U060R4BJ4",
"U060RNRCZ"
],
"is_usergroup" : true,
"id" : "S0616NG6M",
"name" : "Marketing Team"
}
}Authentication
Create a User Group
Request headers
Authentication token. Requires scope: usergroups:write
Request body
A mention handle. Must be unique among channels, users and User Groups.
A name for the User Group. Must be unique among User Groups.
A comma separated string of encoded channel IDs for which the User Group uses as a default.
Include the number of users in each User Group.
A short description of the User Group.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Enable a User Group
Request headers
Authentication token. Requires scope: usergroups:write
Request body
Include the number of users in the User Group.
The encoded ID of the User Group to enable.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
List all User Groups for a team
Request parameters
Include the list of users for each User Group.
Authentication token. Requires scope: usergroups:read
Include the number of users in each User Group.
Include disabled User Groups.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"usergroups" : [
{
"is_external" : false,
"handle" : "admins",
"description" : "A group of all Administrators on your team.",
"date_delete" : 0,
"date_update" : 1446670362,
"created_by" : "USLACKBOT",
"deleted_by" : null,
"date_create" : 1446598059,
"team_id" : "T060RNRCH",
"updated_by" : "U060RNRCZ",
"user_count" : "2",
"auto_type" : "admin",
"prefs" : {
"channels" : [ ],
"groups" : [ ]
},
"is_usergroup" : true,
"id" : "S0614TZR7",
"name" : "Team Admins"
},
{
"is_external" : false,
"handle" : "owners",
"description" : "A group of all Owners on your team.",
"date_delete" : 0,
"date_update" : 1446678371,
"created_by" : "USLACKBOT",
"deleted_by" : null,
"date_create" : 1446678371,
"team_id" : "T060RNRCH",
"updated_by" : "USLACKBOT",
"user_count" : "1",
"auto_type" : "owner",
"prefs" : {
"channels" : [ ],
"groups" : [ ]
},
"is_usergroup" : true,
"id" : "S06158AV7",
"name" : "Team Owners"
},
{
"is_external" : false,
"handle" : "marketing-team",
"description" : "Marketing gurus, PR experts and product advocates.",
"date_delete" : 1446748865,
"date_update" : 1446747767,
"created_by" : "U060RNRCZ",
"deleted_by" : null,
"date_create" : 1446746793,
"team_id" : "T060RNRCH",
"updated_by" : "U060RNRCZ",
"user_count" : "0",
"auto_type" : null,
"prefs" : {
"channels" : [ ],
"groups" : [ ]
},
"is_usergroup" : true,
"id" : "S0615G0KT",
"name" : "Marketing Team"
}
],
"ok" : true
}Authentication
Disable an existing User Group
Request headers
Authentication token. Requires scope: usergroups:write
Request body
Include the number of users in the User Group.
The encoded ID of the User Group to disable.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Returns list of permissions this app has on a team.
Request parameters
Authentication token. Requires scope: none
Responses
Standard failure response when used with an invalid token
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Standard success response when used with a user token
Body
Examples
{
"info" : {
"app_home" : {
"scopes" : [
"chat:write:user",
"im:history",
"im:read"
],
"resources" : {
"ids" : [
"D0C0NU1Q8",
"D0BH95DLH"
]
}
},
"group" : {
"scopes" : [ ],
"resources" : {
"ids" : [ ]
}
},
"mpim" : {
"scopes" : [ ],
"resources" : {
"ids" : [ ]
}
},
"im" : {
"scopes" : [ ],
"resources" : {
"ids" : [ ]
}
},
"team" : {
"scopes" : [ ],
"resources" : {
"ids" : [ ]
}
},
"channel" : {
"scopes" : [
"channels:read"
],
"resources" : {
"ids" : [
"C061FA5PB"
],
"wildcard" : false,
"excluded_ids" : [ ]
}
}
},
"ok" : true
}Authentication
Allows an app to request additional scopes
Request parameters
A comma separated list of scopes to request for
Authentication token. Requires scope: none
Token used to trigger the permissions API
Responses
Standard failure response when trigger_id is invalid
Body
Examples
{
"ok" : false,
"error" : "invalid_trigger_id"
}Standard success response when used with a user token
Authentication
For Enterprise Grid workspaces, map local user IDs to global user IDs
Request parameters
Authentication token. Requires scope: tokens.basic
Specify true to convert W global user IDs to workspace-specific U IDs. Defaults to false.
A comma-separated list of user ids, up to 400 per request
Responses
Typical error response when there are no mappings to provide
Body
Examples
Typical success response when mappings exist for the specified user IDs
Body
Examples
{
"team_id" : "T1KR7PE1W",
"ok" : true,
"enterprise_id" : "E1KQTNXE1",
"invalid_user_ids" : [
"U21ABZZXX"
],
"user_id_map" : {
"U06UBSUN5" : "W06M56XJM",
"U06UBSVDX" : "W06PUUDMW",
"U06UEB62U" : "W06PTT6GH",
"W06UAZ65Q" : "W06UAZ65Q",
"U06UBSVB3" : "W06PUUDLY"
}
}Authentication
Starts a Real Time Messaging session.
Request parameters
Authentication token. Requires scope: rtm:stream
Only deliver presence events when requested by subscription. See presence subscriptions.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"url" : "wss://...",
"self" : {
"id" : "U4X318ZMZ",
"name" : "robotoverlord"
},
"ok" : true,
"team" : {
"domain" : "slackdemo",
"id" : "T2U81E2FP",
"name" : "SlackDemo"
}
}Authentication
Starts a Real Time Messaging session.
Request parameters
Exclude latest timestamps for channels, groups, mpims, and ims. Automatically sets no_unreads to 1
Return timestamp only for latest message object of each channel (improves performance).
Set this to true to receive the locale for users and channels. Defaults to false
Skip unread counts for each channel (improves performance).
Only deliver presence events when requested by subscription. See presence subscriptions.
Returns MPIMs to the client in the API response.
Authentication token. Requires scope: rtm:stream
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Lists custom emoji for a team.
Request parameters
Authentication token. Requires scope: emoji:read
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Authentication
Open a dialog with a user
Request parameters
The dialog definition. This must be a JSON-encoded string.
Exchange a trigger to post to the user.
Request headers
Authentication token. Requires scope: none
Responses
Typical error response, before getting to any possible validation errors.
Body
Examples
{
"ok" : false,
"error" : "missing_trigger"
}Typical success response is quite minimal.
Authentication
Retrieve a team’s profile.
Request parameters
Authentication token. Requires scope: users.profile:read
Filter by visibility.
Responses
Typical error response
Body
Examples
{
"ok" : false,
"error" : "invalid_auth"
}Typical success response
Body
Examples
{
"profile" : {
"fields" : [
{
"hint" : "Enter the extension to reach your desk",
"ordering" : 0,
"possible_values" : null,
"label" : "Phone extension",
"options" : null,
"is_hidden" : 1,
"type" : "text",
"id" : "Xf06054AAA"
},
{
"hint" : "When you were born",
"ordering" : 1,
"possible_values" : null,
"label" : "Date of birth",
"options" : null,
"type" : "date",
"id" : "Xf06054BBB"
},
{
"hint" : "Enter a link to your Facebook profile",
"ordering" : 2,
"possible_values" : null,
"label" : "Facebook",
"options" : null,
"type" : "link",
"id" : "Xf06054CCC"
},
{
"hint" : "Hogwarts, obviously",
"ordering" : 3,
"possible_values" : [
"Gryffindor",
"Hufflepuff",
"Ravenclaw",
"Slytherin"
],
"label" : "House",
"options" : null,
"type" : "options_list",
"id" : "Xf06054DDD"
},
{
"hint" : "Office location (LDAP)",
"ordering" : 4,
"possible_values" : null,
"label" : "Location",
"options" : {
"is_protected" : 1
},
"type" : "text",
"id" : "Xf06054EEE"
},
{
"hint" : "The boss",
"ordering" : 5,
"possible_values" : null,
"label" : "Manager",
"options" : null,
"type" : "user",
"id" : "Xf06054FFF"
}
]
},
"ok" : true
}IM Object
file object with ID only
file object
User profile object
Channel Object
Group object
Team Object
Message object