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?

Find out!


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] expects multipart/form-data, which is a fancy way of asking you to send most parameters as application/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 to application/json. We won't interpret your POST body as such without it.
  • You must transmit your token as a bearer token in the Authorization 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 HTTP Content-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.

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:

Methods supporting JSON POSTs

These methods support sending application/json instead of application/x-www-form-urlencoded arguments.

Method & DescriptionDescription
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.disconnectShared
Disconnect a connected channel from one or more workspaces.
Disconnect a connected channel from one or more workspaces.
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.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.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.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.
About this page
Audience
Beginner