Skip to content
Instant

Developers

Distribution Experimental

Let other workspaces install your bot with Slack’s OAuth flow, so one app serves them all. This is an experiment and isn’t on for every workspace yet.

How It Works

  1. You turn it on in the bot’s Distribution section: add your Redirect URLs, and list it in the App Directory if you like. The Client ID is the bot’s id; the Client Secret shows beside the signing secret.
  2. Someone installs it from your install link or the App Directory. They pick a workspace where they manage apps, see what it asks for, and choose Allow.
  3. Instant sends them back to your redirect URL with a code and your state.
  4. Your app swaps the code for that workspace’s bot token with oauth.v2.access, and stores it by team.id.

The Install Link

The same as Slack’s, on instant.im. The scopes are those your bot has; ask for fewer if you like.

https://instant.im/oauth/v2/authorize?client_id=bot_…&scope=chat:write,commands&redirect_uri=https%3A%2F%2Fexample.com%2Fslack%2Foauth_redirect&state=…

The redirect URI must be one of yours, or under one (https://example.com/slack/ covers https://example.com/slack/oauth_redirect). If they cancel, it gets error=access_denied and your state.

Swap the Code

curl https://api.instant.im/api/oauth.v2.access \
  -d client_id=bot_… -d client_secret=… -d code=… -d redirect_uri=https://example.com/slack/oauth_redirect
{
  "ok": true,
  "access_token": "ib_…",
  "token_type": "bot",
  "scope": "chat:write,commands",
  "bot_user_id": "usr_…",
  "app_id": "bot_…",
  "team": { "id": "ws_…", "name": "Northwind" },
  "enterprise": null,
  "is_enterprise_install": false,
  "authed_user": { "id": "usr_…" }
}

The code works once, for 10 minutes. The client id and secret can also come as HTTP Basic auth. With Bolt’s InstallProvider, set authorizationUrl to https://instant.im/oauth/v2/authorize and clientOptions.slackApiUrl to https://api.instant.im/api/, and it runs the whole flow.

What an Install Is

  • A bot of its own in that workspace: a member with a seat on their plan, marked Installed from your workspace.
  • It uses your Events URL, events, Interactivity URL, unfurl domains, name and picture, and follows your changes at once. Its slash commands and shortcuts are copied when it’s installed; installing again refreshes them.
  • Every request to your app is signed with your signing secret and carries that workspace’s team_id, so one app serves every workspace.
  • The workspace chooses its channels, can turn scopes off, and can remove it. They can’t see your secrets or change your URLs.
  • Deleting your bot removes it from every workspace that installed it.

Not Yet

Socket Mode for installs (they use your URLs), the app_uninstalled and tokens_revoked events, user tokens, refresh tokens, and review before listing.

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing