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 ✓.
| Scope | Allows |
|---|---|
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:read | Accepted 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.email | See members’ emails, and use users.lookupByEmail |
im:write | Open a DM with someone (conversations.open) |
im:history ✓ | Read DMs it is in |
files:write | Upload files and attach them to its messages |
files:read | Download files posted where it is |
commands ✓ | Have slash commands and shortcuts |
app_mentions:read ✓ | Get app_mention events |
pins:write | Pin, unpin and list pins |
channels:join | Join public channels by itself (conversations.join) |
channels:manage | Make channels, invite people, set topics, and rename, archive and leave channels it made |
links:read | Get link_shared events for its unfurl domains |
links:write | Show 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:writeit 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:
| Error | Means |
|---|---|
not_authed, invalid_auth | No token, or one that was revoked or never existed. |
missing_scope | Turn on the scope in needed. |
channel_not_found | No such channel, or the bot isn’t in it. Add the bot first. |
message_not_found, user_not_found | The id is wrong, or the bot can’t see it. |
is_archived | The channel is archived. |
not_allowed_token_type | Bots can’t use that part of Instant. |
team_access_not_granted | The workspace’s trial ended; its bots stop with it. |
invalid_arguments | Something in the call is missing or not allowed. |
ratelimited | Over 120 calls a minute. Wait for Retry-After. |
unknown_method | Instant 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.