How to use 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!

• Web API basics
• Evaluating responses
• Authentication
• 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 and SSL when calling all methods.

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
• Some 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 -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 parameter called token.

Treat tokens with care. Never share tokens with other users or applications. Do not publish tokens in public code repositories. Review token safety tips.

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.apps
• admin.apps.approved
• admin.apps.requests
• admin.apps.restricted
• admin.conversations
• admin.inviteRequests
• admin.inviteRequests.approved
• admin.inviteRequests.denied
• admin.teams.admins
• admin.teams
• admin.teams.owners
• admin.teams.settings
• admin.users
• admin.users.session
• api
• apps.permissions
• apps.permissions.resources
• apps.permissions.scopes
• apps.permissions.users
• apps
• auth
• bots
• 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

Methods supporting JSON POSTs

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