Scopes - Workchats Developer Docs

A company admin grants scopes on the OAuth consent screen. Your token can only do what its granted scopes allow; an endpoint that needs a scope you don’t have returns 403 missing_scope.

Available now

Scope	Grants
`users:read`	`GET /v1/users`, `GET /v1/users/{id}`: id, name, display name, avatar, title, timezone, `is_active`, `is_bot`, `is_admin`, `is_external`
`users:read.email`	Adds `email` to user objects (subject to each person’s visibility setting), and enables `GET /v1/users/lookup`
`conversations:read`	`GET /v1/conversations`, `GET /v1/conversations/{id}`: groups and named channels your bot is a member of
`conversations:history`	`GET /v1/conversations/{conversation_id}/messages`: message history your bot can see
`files:read`	`GET /v1/conversations/{conversation_id}/files/{id}`: file metadata and a download link, through a message your bot can read
`messages:write`	`POST /v1/messages`, and editing or deleting your bot’s own messages

Notes

email is never returned without users:read.email, and even then only when the person’s email visibility allows it. A withheld email is indistinguishable from no match on GET /v1/users/lookup — both return 404 user_not_found.
Phone numbers are never returned by any scope.
There’s no scope for reading a bot’s own messages back beyond what POST /v1/messages and PATCH /v1/messages/{id} already return — message history read is conversations:history, above.