You must enable javascript in order to use the Slack API Documentation. You can do this in your browser settings.
Go to Slack

JSON now accepted for Web API write methods

Updated: 2017-10-30 APIs

Incoming webhooks can do it. Slash commands and interactive messages speak it fluently. The message builder knows no other format. But, until now, chat.postMessage stubbornly refused to understand your messages composed in impeccable JSON.

Finally, Slack allows you to send JSON to a wide selection of write-based Web API methods. Additionally, now you can better separate concerns when presenting your credentials to Slack.

What's changing?

A large selection of Web API write methods now support properly formatted JSON POST bodies. This is most useful for methods supporting complex JSON parameters like chat.postMessage, chat.postEphemeral, chat.update, chat.unfurl, and dialog.open.

Mostly things should "just work." If you run into a situation where a method doesn't understand what seems like valid JSON — especially methods that take arrays or objects — please let us know!

Additionally, we now support and prefer passing tokens in HTTP Authorization headers.

How do I use it?

First we'll review how to use an Authorization header to transmit your OAuth credentials. You may already be familiar with this process if you've used other APIs or even our Files API.

Then we'll cover submitting JSON in the Web API, which depends on this authorization knowledge.

Using Authorization headers to signal your tokens

We now strongly encourage using the Authorization HTTP header to convey your app or integration's tokens.

To make use of sending JSON on write operations, you must provide your token value using an Authorization HTTP header.

Tokens used in the Slack API are bearer tokens. To specify this type of token to Slack, you must pre-pend Bearer to your HTTP Authorization header's value.

If your authorization token was a bot user token like xoxb-1234-56789abcdefghjijklmnop, then your Authorization header value would be Bearer xoxb-1234-56789abcdefghjijklmnop.

Best practice:

GET /api/users.info?user=W123456
Authorization: Bearer xoxb-1234-56789abcdefghijklmnop

Still accepted, but discouraged:

GET /api/users.info?user=W123456&token=xoxb-1234-56789abcdefghijklmnop

You can send your token via Authorization header using all Web API methods. Just don't send it multiple ways at once!

Here's an example using the popular command line tool, cURL:

curl example
curl -X GET -H 'Authorization: Bearer xoxb-1234-56789abcdefghijklmnop' \
https://slack.com/api/users.info?user=W123456

Sending JSON when POSTing to Web API write methods

To send JSON to the Web API, use the authorization procedure above: present your bearer tokens, whatever their token type, in a HTTP Authorization header.

Additionally specify the Content-type header as application/json. Your POST body should contain nothing but your JSON body.

Methods supporting comma-separated value arguments should support presentation of arguments as a JSON array or as a string with comma-separated values.

Methods accepting JSON objects or arrays, like chat.postMessage and chat.unfurl, should support presenting those arguments natively in JSON.

The most common use case for sending JSON is preserving your message structure when using multiple platform tools together: incoming webhooks, slash commands, interactive messages, chat.postMessage, etc.

Don't send a mixture of query parameters, POST parameters, or JSON attributes. Choose one model per request.

Example JSON requests

Creating a public channel with conversations.create:

POST /api/conversations.create
Content-type: application/json
Authorization: Bearer xoxa-xxxxxxxxx-xxxx
{"name":"something-urgent"}

Posting a message with menus using chat.postMessage:

POST /api/chat.postMessage
Content-type: application/json
Authorization: Bearer xoxa-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 as 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

What isn't changing?

You can still send application/x-www-form-urlencoded data the way you're used to on a method URL's query string or POST body.

You can still use HTTP POST on read methods, though those methods do not understand attributes presented as JSON.

You don't have to send your access tokens via the Authorization HTTP header, but we'd prefer that you did.

Nothing changes with parts of the platform that aren't the Web API.

What happens if I do nothing?

We anticipate no issues. This is a backwards compatible, opt-in change that we're confident will make development against Slack easier for many.

There is a slim chance that if you've been sending application/x-www-form-urlencoded data to us but claiming its application/json or vice-versa, or if you have a habit of gratuitously including the same token field in a variety of different ways, you'll find us at a loss for how to consider your request.

When did this happen?

As of October 30, 2017 you can send application/json POSTs to the methods detailed above. Additionally, you may now use Authorization HTTP headers to transmit tokens throughout the Web API.

Please contact us if you have any questions or concerns at feedback@slack.com.


Methods supporting JSON POSTs

These write methods currently support sending a HTTP POST with application/json.

Method & Description Description
api.test
Checks API calling code.
Checks API calling code.
auth.test
Checks authentication & identity.
Checks authentication & identity.
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.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.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.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.add
Add a comment to an existing file.
Add a comment to an existing file.
files.comments.delete
Deletes an existing comment on a file.
Deletes an existing comment on a file.
files.comments.edit
Edit an existing file comment.
Edit an existing file comment.
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 the profile information for a user.
Set the profile information for a user.
users.setActive
Marks a user as active.
Marks a user as active.
users.setPresence
Manually sets user presence.
Manually sets user presence.

Is your favorite method missing? Let us know.

Tips when preparing your JSON

Having trouble properly formatting your JSON? Here are some quick tips:

  • JSON should never contain trailing commas; a stray comma will invalidate your JSON.
  • JSON may not include comments, either of the // or # variety.
  • For better readability, JSON may include additional whitespace and tabbing between keys and values. However, minify unmeaningful whitespace for best performance.
  • Verify that your keys and other strings are enclosed in double quote characters: "
  • Set your Content-type HTTP header to application/json
  • Send your application's token as an Authorization HTTP header beginning with "Bearer ": Authorization: Bearer xoxb-12345-abcdefghjk
Review other recent updates