Legacy: Slack Button

The Slack button is an efficient way to offer your service to teams using Slack. A Slack button app gives you incoming webhooks, slash commands and bot users wrapped in OAuth. You write the commands and the webhook that your app needs, and configure the options for your users. With just a few clicks, your users can add your app to their Slack workspace and start receiving notifications, issuing commands and chatting with your bot.

The Slack button is also a key aspect of sharing your Slack app in the Slack Marketplace!

Add to Slack

When someone clicks on the Slack button in your website or app, the OAuth process begins by asking them to choose their Slack workspace and account. The app will then configure an incoming webhook, slash commands and/or a bot on their behalf. Users will no longer need to copy and paste HTML, webhook URLs, or API tokens!

Authorizing a new app

Using the Slack button

Here's how to build a Slack app that can be added to any workspace via the Slack button. It will let your app send messages to Slack (via incoming webhooks), install slash commands and/or add a bot user on their workspace. From a user experience standpoint, the flow is identical to a normal OAuth 2.0 flow.

Register your Slack app

Before you do anything else, you'll need to create your Slack app to get a client_id and client_secret to use with OAuth.

Create your Slack app

Attach a slash command to your app (optional)

After saving your app, you'll have the option to attach at least one slash command to your app so that workspaces installing your app will also be able to use your slash commands.

Note: Slash commands attached to apps must point to a URL on your servers with a valid secure certificate.

Attach a bot user to your app (optional)

After saving your app, you'll have the option to attach a bot user to your app so that workspaces installing your app will also be able to converse with your bot.

Now you can add the Slack button to your website, ideally in an area that makes sense for users to set up notifications and integrations with other services. Generate the code for your Slack button below:

Looks like you don't have any apps yet.

Create an App

At this time, the Slack button can request any combination of the incoming-webhook, app_home_opened, and commands scopes. The scopes are requested in the scope parameter of the Slack button's URL. In addition to these scopes, you may also request the specific object scopes you're interested in, like reactions.read or emoji.list. You can also specify the following three optional parameters:

redirect_uri -- The URL to redirect back to upon authorization
state -- The unique string to be passed back upon completion
team -- The Slack team ID of the authenticated user to the integration or app to that team

Note: the incoming-webhook scope is designed to allow you to request permission to post content into the user's Slack workspace. It intentionally does not include any read privileges, making it perfect for services that want to send posts or notifications into Slack workspaces that might not want to give read access to messages. For this reason, it cannot be added alongside the read, post, and client scopes.

Add to Slack flow

Negotiating tokens with Slack's OAuth 2.0 authorization flow

Request a token

After someone accepts or denies the OAuth request, Slack redirects them back to your site via the redirect URI (which you passed into the OAuth flow as the redirect_uri parameter, or set up when you created the app). If the OAuth request was accepted, the URL will contain a temporary code in a GET code parameter, as well as the state you provided in the previous step in a state parameter. If the states don't match, the request has been created by a third party and the process should be aborted.

You will need to exchange the code for an access token using the oauth.access method. The JSON response from this API call will contain the access token and incoming webhook URL:

{
	"access_token": "xoxp-XXXXXXXX-XXXXXXXX-XXXXX",
	"scope": "incoming-webhook,commands,bot",
	"team_name": "Team Installing Your Hook",
	"team_id": "XXXXXXXXXX",
	"incoming_webhook": {
		"url": "https://hooks.slack.com/TXXXXX/BXXXXX/XXXXXXXXXX",
		"channel": "#channel-it-will-post-to",
		"configuration_url": "https://teamname.slack.com/services/BXXXXX"
	},
	"bot":{
	    "bot_user_id":"UTTTTTTTTTTR",
	    "bot_access_token":"xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT"
	}
}

You can use the following fields to personalize the UI on your end to give users additional context:

team_name - The name of the workspace that installed your app
channel - The channel name that they have chosen to post to
configuration_url - The URL that you can point your user to if they’d like to edit or remove this integration in Slack.

If your button is used to install a bot user, then pay special attention to the bot node of the JSON response. It contains bot_user_id and bot_access_token values, which you will need to use whenever you are acting on behalf of that bot user for that workspace context. Use the top-level access_token value for other integration points.

Add to Slack configuration

You can now start sending messages via the incoming webhook, listening for and responding to slash commands and initiate or respond to conversations with your bot!

Logging users in with Sign in with Slack

Storing tokens and credentials

Store your application's credentials and user tokens with care. Read our article on safely storing credentials.

Handling edge cases and errors

Denying authorization: If the user denies your request during the OAuth flow, Slack redirects back to your redirect_uri URL with an error parameter.

http://yourapp.com/oauth?error=access_denied

Revoking authorization: Users can revoke the incoming webhook URL from within Slack. If a user does so, you'll receive an HTTP 404 response with a body of "No service" when you make requests to the incoming webhook URL. If this happens, you should stop posting messages to the that particular incoming webhook URL.

Bot naming error: Since your bot inherits the name of the app, and is beholden to the same limitations of real user names, your app name can't be over 35 characters if it has a bot user, and it also can't be called "Slackbot".

Email integrations@slack.com with any questions, feedback, or ideas that would help you get more use out of this, and we'll be more than happy to help.

Create a Slack app to package and distribute your incoming webhook and share it in the Slack Marketplace.