Skip to content
Instant

Developers

Tokens and scopes

A bot’s token says who it is; its scopes say what it may do. Both follow Slack’s names, so a Slack manifest reads the same here.

Tokens

Send the token as Authorization: Bearer ib_… (Slack’s SDKs do), or as a token form field. Instant stores only a hash of it, so it shows once, when made.

  • Two at a time. A bot keeps up to two live tokens. Make a new one, deploy it, then revoke the old one. Making a third retires the oldest.
  • Revoke on the bot’s page stops a token at once.
  • One kind. There are no user tokens or app-level tokens: the bot token does everything, including opening a Socket Mode connection.
curl -s https://api.instant.im/api/auth.test -H "Authorization: Bearer $INSTANT_BOT_TOKEN"
# {"ok":true,"url":"https://instant.im/w/acme","team":"Acme","user":"Deploy Bot",
#  "team_id":"ws_…","user_id":"usr_…","bot_id":"bot_…","is_enterprise_install":false}

Scopes

Turn scopes on and off on the bot’s page; a change takes effect on the next call. A call outside them answers Slack’s {"ok": false, "error": "missing_scope", "needed": "…"}. New bots start with the ones marked ✓.

ScopeAllows
chat:write ✓Post, edit and delete its own messages in channels and DMs it is in
channels:read ✓List the channels it is in, and read their info and members
channels:history ✓Read messages and threads in channels it is in
reactions:write ✓Add and remove its own reactions
reactions:readAccepted so Slack manifests read the same. Reactions come with messages, so channels:history is what reads them
users:read ✓List the workspace’s members and read their profiles
users:read.emailSee members’ emails, and use users.lookupByEmail
im:writeOpen a DM with someone (conversations.open)
im:history ✓Read DMs it is in
files:writeUpload files and attach them to its messages
files:readDownload files posted where it is
commands ✓Have slash commands and shortcuts
app_mentions:read ✓Get app_mention events
pins:writePin, unpin and list pins
channels:joinJoin public channels by itself (conversations.join)
channels:manageMake channels, invite people, set topics, and rename, archive and leave channels it made
links:readGet link_shared events for its unfurl domains
links:writeShow its own cards for those links (chat.unfurl)

Where a Bot Can Go

  • Channels it was added to, public or private, and nothing else. A public channel is closed to a bot until someone adds it, or it joins by itself with channels:join. That’s stricter than Slack, on purpose: people always know which bots can read a channel, because the bot is in its member list.
  • DMs it is in. Anyone can DM a bot. With im:write it can start a DM.
  • Not the office, calls, docs, room chats, settings or billing. Those answer not_allowed_token_type.
  • Shared channels with another company: the bot acts like a member of its own workspace there.

Rate Limits

Each bot can make 120 calls a minute across both APIs. Past that, Slack-compatible methods answer HTTP 429 with {"ok": false, "error": "ratelimited"} and a Retry-After header in seconds. Slack’s SDKs wait and retry by themselves.

Errors

Slack-compatible methods always answer HTTP 200 with "ok": false and Slack’s error code, except for rate limits. The ones you’ll meet:

ErrorMeans
not_authed, invalid_authNo token, or one that was revoked or never existed.
missing_scopeTurn on the scope in needed.
channel_not_foundNo such channel, or the bot isn’t in it. Add the bot first.
message_not_found, user_not_foundThe id is wrong, or the bot can’t see it.
is_archivedThe channel is archived.
not_allowed_token_typeBots can’t use that part of Instant.
team_access_not_grantedThe workspace’s trial ended; its bots stop with it.
invalid_argumentsSomething in the call is missing or not allowed.
ratelimitedOver 120 calls a minute. Wait for Retry-After.
unknown_methodInstant doesn’t have that method. See Porting from Slack.

Seats

A bot is a member, so it takes a seat at the same price as a person. Deleting it frees the seat on your next bill. If a workspace’s trial ends, its bots stop with it.

Build Your First Bot

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

Join NowSee Pricing