Several aspects of the Web API & Events API retired or changed on February 24, 2021.
Using the Slack Web API
The Slack Web API is an interface for querying information from and enacting change in a Slack workspace.
Use it on the fly for ad-hoc queries, or as part of a more complex tapestry of platform features in a Slack app.
What can you do with the Web API?
- Web API basics
- Evaluating responses
- Authentication
- HTTPS, SSL, and TLS
- OpenAPI specification
- Methods
Basics
The Web API is a collection of HTTP RPC-style methods, all with URLs in the form https://slack.com/api/METHOD_FAMILY.method
.
While it's not a REST API, those familiar with REST should be at home with its foundations in HTTP.
Use HTTPS, SSL, and TLS v1.2 or above when calling all methods. Learn more about our SSL and TLS requirements.
Each method has a series of arguments informing the execution of your intentions.
Pass arguments as:
- GET querystring parameters
- POST parameters presented as
application/x-www-form-urlencoded
- or a mix of both GET and POST parameters
- Most write methods allow arguments
application/json
attributes. - [
files.upload
] expectsmultipart/form-data
, which is a fancy way of asking you to send most parameters asapplication/x-www-form-urlencoded
key/value pairs but send files in their native content type.
Some methods, like chat.postMessage
and dialog.open
feature arguments that accept an associative JSON array. These methods can be difficult to properly construct when using a application/x-www-form-urlencoded
Content-type, and we strongly recommend using JSON-encoded bodies instead.
POST bodies
When sending a HTTP POST, you may present your arguments as either standard POST parameters or use JSON instead.
URL-encoded bodies
When sending URL-encoded data, set your HTTP Content-type
header to application/x-www-form-urlencoded
and present your key/value pairs according to RFC-3986.
For example, a POST request to conversations.create
might look something like this:
POST /api/conversations.create
Content-type: application/x-www-form-urlencoded
token=xoxp-xxxxxxxxx-xxxx&name=something-urgent
JSON-encoded bodies
For these write methods, you may alternatively send your HTTP POST data as Content-type: application/json
.
There are some ground rules:
- You must explicitly set the
Content-type
HTTP header toapplication/json
. We won't interpret your POST body as such without it. - You must transmit your
token
as a bearer token in theAuthorization
HTTP header. - You cannot send your token as part of the query string or as an attribute in your posted JSON.
- Do not mix arguments between query string, URL-encoded POST body, and JSON attributes. Choose one approach per request.
- Providing an explicitly
null
value for an attribute will result in whichever default behavior is assigned to it.
For example, to send the same request above to conversations.create
with a JSON POST body:
POST /api/conversations.create
Content-type: application/json
Authorization: Bearer xoxp-xxxxxxxxx-xxxx
{"name":"something-urgent"}
Note how we present the token with the string Bearer
pre-pended to it, indicating the OAuth 2.0 authentication scheme. Consult your favorite HTTP tool or library's manual for further detail on setting HTTP headers.
Here's a more complicated example: Posting a message with menus using chat.postMessage
.
POST /api/chat.postMessage
Content-type: application/json
Authorization: Bearer xoxp-xxxxxxxxx-xxxx
{"channel":"C061EG9SL","text":"I hope the tour went well, Mr. Wonka.","attachments":[{"text":"Who wins the lifetime supply of chocolate?","fallback":"You could be telling the computer exactly what it can do with a lifetime supply of chocolate.","color":"#3AA3E3","attachment_type":"default","callback_id":"select_simple_1234","actions":[{"name":"winners_list","text":"Who should win?","type":"select","data_source":"users"}]}]}
Note how the attachments
argument is sent a straight-forward JSON array.
Here's how to do that with cURL:
curl example
curl -X POST -H 'Authorization: Bearer xoxb-1234-56789abcdefghijklmnop' \
-H 'Content-type: application/json' \
--data '{"channel":"C061EG9SL","text":"I hope the tour went well, Mr. Wonka.","attachments": [{"text":"Who wins the lifetime supply of chocolate?","fallback":"You could be telling the computer exactly what it can do with a lifetime supply of chocolate.","color":"#3AA3E3","attachment_type":"default","callback_id":"select_simple_1234","actions":[{"name":"winners_list","text":"Who should win?","type":"select","data_source":"users"}]}]}' \
https://slack.com/api/chat.postMessage
Errors specific to passing JSON
If the posted JSON is invalid, you'll receive one of the following errors in response:
invalid_json
- The JSON you've included in your POST body cannot be parsed. This might be because it's actually not JSON, or perhaps you did not correctly set your HTTPContent-type
header. Make sure your JSON attribute keys are strings wrapped with double-quote ("
) characters.json_not_object
- We could understand that your code was JSON-like enough to parse it, but it's not actually a JSON hash of attribute key/value pairs. Perhaps you sent us an array, or just a string or number.
In both cases, you'll need to revise your JSON or how you're transmitting your data to resolve the error condition.
Evaluating responses
All Web API responses contain a JSON object, which will always
contain a top-level boolean property ok
, indicating success or failure.
For failure results, the error
property will contain a short machine-readable
error code. In the case of problematic calls that could still be completed
successfully, ok
will be true
and the warning
property will contain a
short machine-readable warning code (or comma-separated list of them, in the
case of multiple warnings).
{
"ok": true,
"stuff": "This is good"
}
{
"ok": false,
"error": "something_bad"
}
{
"ok": true,
"warning": "something_problematic",
"stuff": "Your requested information"
}
Other properties are defined in the documentation for each relevant method. There's a lot of "stuff" to unpack, including these types and other method or domain-specific curiosities.
Authentication
Authenticate your Web API requests by providing a bearer token, which identifies a single user, bot user, or workspace-application relationship.
Register your application with Slack to obtain credentials for use with our OAuth 2.0 implementation, which allows you to negotiate tokens on behalf of users and workspaces.
We prefer tokens to be sent in the Authorization
HTTP header of your outbound requests. However, you may also pass tokens in all Web API calls as a POST body parameter called token
. Tokens cannot be sent as a query parameter.
Treat tokens with care. Never share tokens with other users or applications. Do not publish tokens in public code repositories. Review token safety tips.
HTTPS, SSL, and TLS
Slack requires HTTPS, SSL, and TLS v1.2 and above. The platform and the Web API are governed by the same rules. Learn more about our deprecation of early TLS versions.
All TLS connections must use the SNI extension. Lastly, TLS connections must support at least one of the following supported cipher suites:
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
Stay safe and secure.
Open API specification
One way to understand all the magic behind the methods is to investigate our OpenAPI 2.0 specification, describing the requests and responses you'll find throughout our Web API.
- Download the spec from its canonical location on api.slack.com
- Browse the spec's history on github.
Methods
With over 100 methods, surely there's one right for you. Here is a list of the different method families available in our Web API:
- admin.analytics
- admin.apps
- admin.apps.approved
- admin.apps.requests
- admin.apps.restricted
- admin.barriers
- admin.conversations
- admin.conversations.ekm
- admin.conversations.restrictAccess
- admin.emoji
- admin.inviteRequests
- admin.inviteRequests.approved
- admin.inviteRequests.denied
- admin.teams.admins
- admin.teams
- admin.teams.owners
- admin.teams.settings
- admin.usergroups
- admin.users
- admin.users.session
- api
- apps.connections
- apps.event.authorizations
- apps.permissions
- apps.permissions.resources
- apps.permissions.scopes
- apps.permissions.users
- apps
- auth
- auth.teams
- bots
- calls
- calls.participants
- channels
- chat
- chat.scheduledMessages
- conversations
- dialog
- dnd
- emoji
- files.comments
- files
- files.remote
- groups
- im
- migration
- mpim
- oauth
- oauth.v2
- pins
- reactions
- reminders
- rtm
- search
- stars
- team
- team.profile
- usergroups
- usergroups.users
- users
- users.profile
- views
- workflows
Methods supporting JSON POSTs
These methods support sending application/json
instead of application/x-www-form-urlencoded
arguments.
Method & Description | Description |
---|---|
admin.apps.approve Approve an app for installation on a workspace. | Approve an app for installation on a workspace. |
admin.apps.clearResolution Clear an app resolution | Clear an app resolution |
admin.apps.restrict Restrict an app for installation on a workspace. | Restrict an app for installation on a workspace. |
admin.conversations.archive Archive a public or private channel. | Archive a public or private channel. |
admin.conversations.convertToPrivate Convert a public channel to a private channel. | Convert a public channel to a private channel. |
admin.conversations.create Create a public or private channel-based conversation. | Create a public or private channel-based conversation. |
admin.conversations.delete Delete a public or private channel. | Delete a public or private channel. |
admin.conversations.getConversationPrefs Get conversation preferences for a public or private channel. | Get conversation preferences for a public or private channel. |
admin.conversations.getCustomRetention This API endpoint can be used by any admin to get a channel's retention policy. | This API endpoint can be used by any admin to get a channel's retention policy. |
admin.conversations.getTeams Get all the workspaces a given public or private channel is connected to within this Enterprise org. | Get all the workspaces a given public or private channel is connected to within this Enterprise org. |
admin.conversations.invite Invite a user to a public or private channel. | Invite a user to a public or private channel. |
admin.conversations.removeCustomRetention This API endpoint can be used by any admin to remove a channel's retention policy. | This API endpoint can be used by any admin to remove a channel's retention policy. |
admin.conversations.rename Rename a public or private channel. | Rename a public or private channel. |
admin.conversations.search Search for public or private channels in an Enterprise organization. | Search for public or private channels in an Enterprise organization. |
admin.conversations.setConversationPrefs Set the posting permissions for a public or private channel. | Set the posting permissions for a public or private channel. |
admin.conversations.setCustomRetention This API endpoint can be used by any admin to set a channel's retention policy. | This API endpoint can be used by any admin to set a channel's retention policy. |
admin.conversations.setTeams Set the workspaces in an Enterprise grid org that connect to a public or private channel. | Set the workspaces in an Enterprise grid org that connect to a public or private channel. |
admin.conversations.unarchive Unarchive a public or private channel. | Unarchive a public or private channel. |
admin.inviteRequests.approve Approve a workspace invite request. | Approve a workspace invite request. |
admin.inviteRequests.approved.list List all approved workspace invite requests. | List all approved workspace invite requests. |
admin.inviteRequests.denied.list List all denied workspace invite requests. | List all denied workspace invite requests. |
admin.inviteRequests.deny Deny a workspace invite request. | Deny a workspace invite request. |
admin.inviteRequests.list List all pending workspace invite requests. | List all pending workspace invite requests. |
admin.teams.create Create an Enterprise team. | Create an Enterprise team. |
admin.teams.list List all teams on an Enterprise organization | List all teams on an Enterprise organization |
admin.teams.settings.info Fetch information about settings in a workspace | Fetch information about settings in a workspace |
admin.teams.settings.setDescription Set the description of a given workspace. | Set the description of a given workspace. |
admin.teams.settings.setDiscoverability An API method that allows admins to set the discoverability of a given workspace | An API method that allows admins to set the discoverability of a given workspace |
admin.teams.settings.setName Set the name of a given workspace. | Set the name of a given workspace. |
admin.usergroups.addChannels Add up to one hundred default channels to an IDP group. | Add up to one hundred default channels to an IDP group. |
admin.usergroups.addTeams Associate one or more default workspaces with an organization-wide IDP group. | Associate one or more default workspaces with an organization-wide IDP group. |
admin.usergroups.listChannels List the channels linked to an org-level IDP group (user group). | List the channels linked to an org-level IDP group (user group). |
admin.usergroups.removeChannels Remove one or more default channels from an org-level IDP group (user group). | Remove one or more default channels from an org-level IDP group (user group). |
admin.users.assign Add an Enterprise user to a workspace. | Add an Enterprise user to a workspace. |
admin.users.invite Invite a user to a workspace. | Invite a user to a workspace. |
admin.users.list List users on a workspace | List users on a workspace |
admin.users.remove Remove a user from a workspace. | Remove a user from a workspace. |
admin.users.session.clearSettings Clear user-specific session settings—the session duration and what happens when the client closes—for a list of users. | Clear user-specific session settings—the session duration and what happens when the client closes—for a list of users. |
admin.users.session.getSettings Get user-specific session settings—the session duration and what happens when the client closes—given a list of users. | Get user-specific session settings—the session duration and what happens when the client closes—given a list of users. |
admin.users.session.invalidate Revoke a single session for a user. The user will be forced to login to Slack. | Revoke a single session for a user. The user will be forced to login to Slack. |
admin.users.session.list List active user sessions for an organization | List active user sessions for an organization |
admin.users.session.reset Wipes all valid sessions on all devices for a given user | Wipes all valid sessions on all devices for a given user |
admin.users.session.setSettings Configure the user-level session settings—the session duration and what happens when the client closes—for one or more users. | Configure the user-level session settings—the session duration and what happens when the client closes—for one or more users. |
admin.users.setAdmin Set an existing guest, regular user, or owner to be an admin user. | Set an existing guest, regular user, or owner to be an admin user. |
admin.users.setExpiration Set an expiration for a guest user | Set an expiration for a guest user |
admin.users.setOwner Set an existing guest, regular user, or admin user to be a workspace owner. | Set an existing guest, regular user, or admin user to be a workspace owner. |
admin.users.setRegular Set an existing guest user, admin user, or owner to be a regular user. | Set an existing guest user, admin user, or owner to be a regular user. |
api.test Checks API calling code. | Checks API calling code. |
apps.connections.open Generate a temporary Socket Mode WebSocket URL that your app can connect to in order to receive events and interactive payloads over, | Generate a temporary Socket Mode WebSocket URL that your app can connect to in order to receive events and interactive payloads over, |
apps.event.authorizations.list Get a list of authorizations for the given event context. Each authorization represents an app installation that the event is visible to. | Get a list of authorizations for the given event context. Each authorization represents an app installation that the event is visible to. |
auth.test Checks authentication & identity. | Checks authentication & identity. |
calls.add Registers a new Call. | Registers a new Call. |
calls.end Ends a Call. | Ends a Call. |
calls.info Returns information about a Call. | Returns information about a Call. |
calls.participants.add Registers new participants added to a Call. | Registers new participants added to a Call. |
calls.participants.remove Registers participants removed from a Call. | Registers participants removed from a Call. |
calls.update Updates information about a Call. | Updates information about a Call. |
channels.archive Archives a channel. | Archives a channel. |
channels.create Creates a channel. | Creates a channel. |
channels.invite Invites a user to a channel. | Invites a user to a channel. |
channels.join Joins a channel, creating it if needed. | Joins a channel, creating it if needed. |
channels.kick Removes a user from a channel. | Removes a user from a channel. |
channels.leave Leaves a channel. | Leaves a channel. |
channels.mark Sets the read cursor in a channel. | Sets the read cursor in a channel. |
channels.rename Renames a channel. | Renames a channel. |
channels.setPurpose Sets the purpose for a channel. | Sets the purpose for a channel. |
channels.setTopic Sets the topic for a channel. | Sets the topic for a channel. |
channels.unarchive Unarchives a channel. | Unarchives a channel. |
chat.delete Deletes a message. | Deletes a message. |
chat.deleteScheduledMessage Deletes a pending scheduled message from the queue. | Deletes a pending scheduled message from the queue. |
chat.meMessage Share a me message into a channel. | Share a me message into a channel. |
chat.postEphemeral Sends an ephemeral message to a user in a channel. | Sends an ephemeral message to a user in a channel. |
chat.postMessage Sends a message to a channel. | Sends a message to a channel. |
chat.scheduleMessage Schedules a message to be sent to a channel. | Schedules a message to be sent to a channel. |
chat.scheduledMessages.list Returns a list of scheduled messages. | Returns a list of scheduled messages. |
chat.unfurl Provide custom unfurl behavior for user-posted URLs | Provide custom unfurl behavior for user-posted URLs |
chat.update Updates a message. | Updates a message. |
conversations.archive Archives a conversation. | Archives a conversation. |
conversations.close Closes a direct message or multi-person direct message. | Closes a direct message or multi-person direct message. |
conversations.create Initiates a public or private channel-based conversation | Initiates a public or private channel-based conversation |
conversations.invite Invites users to a channel. | Invites users to a channel. |
conversations.join Joins an existing conversation. | Joins an existing conversation. |
conversations.kick Removes a user from a conversation. | Removes a user from a conversation. |
conversations.leave Leaves a conversation. | Leaves a conversation. |
conversations.mark Sets the read cursor in a channel. | Sets the read cursor in a channel. |
conversations.open Opens or resumes a direct message or multi-person direct message. | Opens or resumes a direct message or multi-person direct message. |
conversations.rename Renames a conversation. | Renames a conversation. |
conversations.setPurpose Sets the purpose for a conversation. | Sets the purpose for a conversation. |
conversations.setTopic Sets the topic for a conversation. | Sets the topic for a conversation. |
conversations.unarchive Reverses conversation archival. | Reverses conversation archival. |
dialog.open Open a dialog with a user | Open a dialog with a user |
dnd.endDnd Ends the current user's Do Not Disturb session immediately. | Ends the current user's Do Not Disturb session immediately. |
dnd.endSnooze Ends the current user's snooze mode immediately. | Ends the current user's snooze mode immediately. |
files.comments.delete Deletes an existing comment on a file. | Deletes an existing comment on a file. |
files.delete Deletes a file. | Deletes a file. |
files.revokePublicURL Revokes public/external sharing access for a file | Revokes public/external sharing access for a file |
files.sharedPublicURL Enables a file for public/external sharing. | Enables a file for public/external sharing. |
groups.archive Archives a private channel. | Archives a private channel. |
groups.create Creates a private channel. | Creates a private channel. |
groups.invite Invites a user to a private channel. | Invites a user to a private channel. |
groups.kick Removes a user from a private channel. | Removes a user from a private channel. |
groups.leave Leaves a private channel. | Leaves a private channel. |
groups.mark Sets the read cursor in a private channel. | Sets the read cursor in a private channel. |
groups.open Opens a private channel. | Opens a private channel. |
groups.rename Renames a private channel. | Renames a private channel. |
groups.setPurpose Sets the purpose for a private channel. | Sets the purpose for a private channel. |
groups.setTopic Sets the topic for a private channel. | Sets the topic for a private channel. |
groups.unarchive Unarchives a private channel. | Unarchives a private channel. |
im.close Close a direct message channel. | Close a direct message channel. |
im.mark Sets the read cursor in a direct message channel. | Sets the read cursor in a direct message channel. |
im.open Opens a direct message channel. | Opens a direct message channel. |
mpim.close Closes a multiparty direct message channel. | Closes a multiparty direct message channel. |
mpim.mark Sets the read cursor in a multiparty direct message channel. | Sets the read cursor in a multiparty direct message channel. |
mpim.open This method opens a multiparty direct message. | This method opens a multiparty direct message. |
pins.add Pins an item to a channel. | Pins an item to a channel. |
pins.remove Un-pins an item from a channel. | Un-pins an item from a channel. |
reactions.add Adds a reaction to an item. | Adds a reaction to an item. |
reactions.remove Removes a reaction from an item. | Removes a reaction from an item. |
reminders.add Creates a reminder. | Creates a reminder. |
reminders.complete Marks a reminder as complete. | Marks a reminder as complete. |
reminders.delete Deletes a reminder. | Deletes a reminder. |
stars.add Adds a star to an item. | Adds a star to an item. |
stars.remove Removes a star from an item. | Removes a star from an item. |
usergroups.create Create a User Group | Create a User Group |
usergroups.disable Disable an existing User Group | Disable an existing User Group |
usergroups.enable Enable a User Group | Enable a User Group |
usergroups.update Update an existing User Group | Update an existing User Group |
usergroups.users.update Update the list of users for a User Group | Update the list of users for a User Group |
users.profile.set Set a user's profile information, including custom status. | Set a user's profile information, including custom status. |
users.setActive Marked a user as active. Deprecated and non-functional. | Marked a user as active. Deprecated and non-functional. |
users.setPresence Manually sets user presence. | Manually sets user presence. |
views.open Open a view for a user. | Open a view for a user. |
views.publish Publish a static view for a User. | Publish a static view for a User. |
views.push Push a view onto the stack of a root view. | Push a view onto the stack of a root view. |
views.update Update an existing view. | Update an existing view. |
workflows.stepCompleted Indicate that an app's step in a workflow completed execution. | Indicate that an app's step in a workflow completed execution. |
workflows.stepFailed Indicate that an app's step in a workflow failed to execute. | Indicate that an app's step in a workflow failed to execute. |
workflows.updateStep Update the configuration for a workflow step. | Update the configuration for a workflow step. |