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 for individual queries, or as part of a more complex tapestry of platform features in a Slack app.

Want to just get a token and get started? This tutorial teaches you how to quickly get and use a Slack API bot token.

Basic overview

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 with application/json attributes.
Some methods, such as chat.postMessage and dialog.open, feature arguments that accept an associative JSON array. However, these methods can be difficult to properly construct when using a application/x-www-form-urlencoded Content-type, so 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 you may 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 the conversations.create method 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 write methods that support JSON, 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 the conversations.create method with a JSON POST body, send something like this:

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":"C123ABC456","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"}]}]}

The attachments argument is sent a straightforward 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":"C123ABC456","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. Ensure 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 a 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 that indicates 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). See the following examples:

{
    "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 or bot user 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 or above. The platform and the Web API are governed by the same rules. Learn more about our deprecation of early TLS versions. Stay safe and secure.

All TLS connections must use the SNI extension. Lastly, TLS connections must support at least one of the following cipher suites:

TLS 1.2:

ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-CHACHA20-POLY1305
ECDHE-RSA-AES256-GCM-SHA384

TLS 1.3:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256

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 & 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.config.lookup Look up the app config for connectors by their IDs	Look up the app config for connectors by their IDs
admin.apps.config.set Set the app config for a connector	Set the app config for a connector
admin.apps.requests.cancel Cancel app request for team	Cancel app request for team
admin.apps.restrict Restrict an app for installation on a workspace.	Restrict an app for installation on a workspace.
admin.apps.uninstall Uninstall an app from one or many workspaces, or an entire enterprise organization.	Uninstall an app from one or many workspaces, or an entire enterprise organization.
admin.audit.anomaly.allow.getItem API to allow enterprise grid admins to read the allow list of IP blocks and ASNs from the enterprise configuration.	API to allow enterprise grid admins to read the allow list of IP blocks and ASNs from the enterprise configuration.
admin.audit.anomaly.allow.updateItem API to allow enterprise grid admins to write/overwrite the allow list of IP blocks and ASNs from the enterprise configuration.	API to allow enterprise grid admins to write/overwrite the allow list of IP blocks and ASNs from the enterprise configuration.
admin.auth.policy.assignEntities Assign entities to a particular authentication policy.	Assign entities to a particular authentication policy.
admin.auth.policy.getEntities Fetch all the entities assigned to a particular authentication policy by name.	Fetch all the entities assigned to a particular authentication policy by name.
admin.auth.policy.removeEntities Remove specified entities from a specified authentication policy.	Remove specified entities from a specified authentication policy.
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.convertToPublic Convert a private channel to a public channel.	Convert a private channel to a public 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 conversation's retention policy.	This API endpoint can be used by any admin to get a conversation'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.linkObjects Link a Salesforce record to a channel	Link a Salesforce record to a channel
admin.conversations.removeCustomRetention This API endpoint can be used by any admin to remove a conversation's retention policy.	This API endpoint can be used by any admin to remove a conversation'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 conversation's retention policy.	This API endpoint can be used by any admin to set a conversation'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.conversations.unlinkObjects Unlink a Salesforce record from a channel	Unlink a Salesforce record from a channel
admin.functions.list Look up functions by a set of apps	Look up functions by a set of apps
admin.functions.permissions.lookup Lookup the visibility of multiple Slack functions and include the users if it is limited to particular named entities.	Lookup the visibility of multiple Slack functions and include the users if it is limited to particular named entities.
admin.functions.permissions.set Set the visibility of a Slack function and define the users or workspaces if it is set to named_entities	Set the visibility of a Slack function and define the users or workspaces if it is set to named_entities
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.roles.addAssignments Adds members to the specified role with the specified scopes	Adds members to the specified role with the specified scopes