Docs / Integration API contract

Setting up an app

An administrator creates an app under Apps and integrations. Each app gets:

  • a bot user, which is who its messages are posted as;
  • a bot token (xoxb-…), shown once and stored only as a hash — New bot token replaces it;
  • a signing secret, used to sign every request this server makes to the app — Replace beside it issues a new one;
  • any number of incoming webhooks, one per channel, each with a secret URL — New URL replaces one.

There is no OAuth installation flow. Instead, the administrator chooses the app's scopes when they create it, and can change them on its card at any time. They use Slack's names, so the scopes an app's own instructions ask for carry over. Its bot token holds them from its next call. On top of them, the bot user's reach still applies: private channels and group conversations only once the bot has been added to them.

  • An app made in Apps and integrations starts able to post and is sent no events, until more is ticked.
  • An app made through the API without a scopes list, and every app made before scopes existed, has all of them, as every app did then.
  • Every Web API answer carries the token's scopes in X-OAuth-Scopes, as Slack's do, and a method the scopes do not reach answers missing_scope with needed and provided.
  • The methods for forms (views.*) and auth.test need no scope, as on Slack.
  • There are no methods that read, so the reading scopes decide which events reach the app's subscriptions (see Events).

The scopes — checked:

ScopeLets the app
chat:writePost with chat.postMessage where its bot has been added
chat:write.publicAlso post in public channels its bot has not been added to
channels:historyBe sent messages from public channels its bot is in
groups:historyBe sent messages from private channels its bot is in
im:historyBe sent messages from direct messages with its bot
mpim:historyBe sent messages from group conversations its bot is in
channels:readBe sent channels made or changed, and members joining or leaving, if public
groups:readThe same for private channels its bot is in
reactions:readBe sent reactions added and removed
pins:readBe sent pins added and removed
users:readBe sent people joining the workspace and changing their profiles

This page is made from docs/INTEGRATIONS.md.