Slack Bot Scopes: The Scope Each API Method Needs, Measured on 44 Methods

A Slack bot token can only call the methods its scopes allow. The fastest way to find the scope a method needs is to call it without the scope and read the needed field of the missing_scope error. On 7 October 2026 we did that for 44 common Web API methods: we made a test app in a free-plan workspace with one bot scope, emoji:read, called every method, and recorded each error. Then we added the scopes the errors asked for, reinstalled, and called every method again. The table below is the result.

Two things in the errors catch people out. Some needed values are old scope names you cannot add to a new app: chat:write:bot and channels:write were both refused by the app manifest with illegal_bot_scopes. And clearing the scope is often not the end: a bot with the right scope still gets not_in_channel until it is a member of the channel.

Scope per method, as Slack reported it

"Needed" is copied from the missing_scope error of the one-scope bot. "Scope we added" is the bot scope that made the scope error go away. "Second call" is what the same call returned after the reinstall; anything other than missing_scope means the scope was enough.

When needed lists several scopes, any one of them is enough for that kind of conversation: channels: for public channels, groups: for private channels, mpim: for group DMs and im: for DMs. We added only the public-channel scope each time, and the calls on our public test channel passed.

Methods that need no scope, or no bot token

Legacy names in the needed field

Three errors named a scope that a new Slack app cannot request:

• • chat.postMessage, chat.update, chat.delete, chat.postEphemeral and chat.scheduleMessage all said needed: chat:write:bot. Adding chat:write cleared all five.
• • conversations.create, conversations.open and conversations.mark said needed: channels:write, groups:write, mpim:write, im:write. For a bot, channels:manage cleared create, and im:write cleared open.

We tried putting chat:write:bot and channels:write in a manifest, and apps.manifest.validate answered illegal_bot_scopes. If you search for a needed value and find nothing in the app settings, look for the current name: chat:write for posting, channels:manage for creating and archiving channels, im:write for opening DMs. Our page on the missing_scope error covers reading the error itself.

Scope is not membership

After the reinstall, five methods still failed with not_in_channel: the four chat.* posting calls and conversations.history/replies. The bot had the scope but was not in the channel. Once conversations.join (scope channels:join) had run, chat.postMessage returned ok and conversations.history returned the messages. A post to a different public channel the bot had not joined still failed with not_in_channel; chat:write.public is the scope that lets a bot post to public channels without joining. More on that error in Slack not_in_channel.

A starting set for a common bot

From the table, a bot that posts in public channels it has joined, reads their history, reacts and DMs people needs these scopes:

Add the groups:, mpim: and im: variants only if the bot must work in private channels, group DMs or DMs. Every scope you add is listed on the install screen the person installing the app approves.

How we ran the scan

This is the loop from the script we ran for both passes. It sends each call with the bot token and saves the error fields; the method list is in the tables above.

import json, time, requests

def scan(token, methods):
    out = []
    for name, args in methods:
        r = requests.post(
            "https://slack.com/api/" + name,
            headers={"Authorization": "Bearer " + token},
            data=args, timeout=30,
        ).json()
        out.append({"method": name, "ok": r.get("ok"), "error": r.get("error"),
                    "needed": r.get("needed"), "provided": r.get("provided")})
        time.sleep(1.1)  # stay under the per-method rate limits
    return out

First-pass output for one method, as the script saved it:

{"method": "chat.postMessage", "ok": false, "error": "missing_scope",
 "needed": "chat:write:bot", "provided": "emoji:read"}

FAQ

Do I need to reinstall the app after adding a scope? Yes. We added groups:read to the manifest with apps.manifest.update and called conversations.list for private channels: still missing_scope, with needed: groups:read. After a reinstall it returned ok. The bot token string stayed the same through both reinstalls, so nothing that stores the token has to change.

Why does files.info say file_not_found with files:read? Our bot asked about a file that a different test app had uploaded and never shared in a channel. With files:read the scope check passed, but the bot could not see that file.