OAuth Scopes
OAuth scopes, or permissions, let you specify exactly how your application needs to access an Intercom user's account.
You should only specify the scopes you need to satisfy your use case and no more. Scopes are the most common reason that apps aren't approved when it comes to reviews.
Summary of all Oauth Scopes
The following scopes can be selected via checkboxes on your Authorization settings page in the developer hub:
People & conversation data
| Standard scopes | Description |
|---|---|
| Read and list users and companies | List and view all segments, users and companies |
| Read and write users | List all users and execute bulk actions |
| Write users and companies | Create and update users and companies |
| Read one user and one company | List and view a single user and company |
| Read tags | List all tags |
| Write tags | Create, update, use and delete tags |
| Read conversations | View conversations |
| Write conversations | Reply to, mark as read and close conversations |
| Read events | List all events belonging to a user |
| Write events | Ability to submit events (i.e. user activity) |
| Read counts | Count users and companies with specified criteria |
| Write data attributes | Create and update custom data attributes |
| Export message data | Export engagement data for messages |
| Export content data | Export engagement data for content |
| Read content data | Create and update custom data attributes |
| Read tickets | View tickets |
| Write tickets | Create tickets |
Workspace data
| Extended scopes | Description |
|---|---|
| Read admins | List and view all admins |
| Read one admin | View a single admin |
| Update admins | Update away mode for admins |
| Read admin activity logs | List and view all admins and their activity |
| Read data when entered into the app | Gather data via Intercom Apps |
| Read and List news items and newsfeeds | List and view all News items and Newsfeeds |
| Read and Write news items and newsfeeds | Read, Update and Create news items and newsfeeds |
| Read and List articles | List and view all articles |
| Read and Write Articles | Read, Update and Create articles |
| Create phone call redirects | Create phone call redirects |
🚧 Canvas Kit required scopes
If your app utilizes Canvas Kit, certain permissions are required by default due to the data your app will have access to. The following scopes will be automatically selected and cannot be deselected:
- Read and list users and companies
- Read conversations
- Read admins
- Gather App data
Webhook topics are related to corresponding permission scopes. For example, if you need to setup a webook to trigger when a user/lead is created then you will need to select the "Read and write users" permission scopes. You will then be able to setup the webhook topics for your app which will fire for each workspace it is installed on. Checkout our docs on setting up webhooks for more detailed information on how to enable webhooks for your app.