Token Scopes

Updated on September 21, 2021

Privacy and security are gaining in importance as technology takes over the world. More systems get interconnected every day, exchanging streams of data between each other. It is important, in that regard, that integrations only have access to the data they require to operate.

Some integrations, for instance, may only need to send messages on your behalf: in this case, they should not even have the permission to read your messages. We would give them the scope website:conversation:messages with write permissions.

If any of those integration tokens were to leak and be re-used by hackers, no data would be put at risk, as the token scopes are not broad enough!

Scopes only apply to Production tokens. You would use a Production token when running your integration "in the real world". Note that Development tokens are not subject to scopes. Development tokens are heavily limited, therefore you should only use them for development purposes, ie. on your local computer.

Available Scopes

Multiple granular scopes are available, each one with associated read or write permissions.

Depending on the REST API route that you need to access, or the RTM API event that you want to receive, you will need to request certain scopes.

All available scopes are listed in this table:

Scope Description Example REST API Route
bucket:url Ability to generate file upload URLs Generate Bucket URL
website:availability Check if website is online/offline Get Website Availability Status
website:operators Interaction with website operators Send Email To Website Operators
website:settings Management of website settings Get Website Settings
website:verify Email verification options Get Verify Settings
website:visitors List website visitors List Visitors
website:conversation:initiate Create new conversations Create A New Conversation
website:conversation:sessions Read and update conversations Get Conversation Metas
website:conversation:suggest Suggest segments and more on conversations List Suggested Conversation Segments
website:conversation:messages View and send messages in conversations Send A Message In Conversation
website:conversation:states Management of conversation states (eg. resolved) Change Conversation State
website:conversation:participants Management of participants in conversations Save Conversation Participants
website:conversation:pages List browsed pages in conversations List Conversation Pages
website:conversation:events List pushed events in conversations List Conversation Events
website:conversation:actions Perform actions on conversations (eg. block) Block Incoming Messages For Conversation
website:conversation:browsing Access to MagicBrowse List Browsing Sessions For Conversation
website:conversation:calls Access to Crisp Calls Initiate New Call Session For Conversation
website:conversation:reminders Scheduling of reminders on conversations Schedule A Reminder For Conversation
website:conversation:routing Management of assigned operators on conversations Assign Conversation Routing
website:people:statistics Access to CRM statistics Get People Statistics
website:people:suggest Suggest segments and more in CRM List Suggested People Events
website:people:profiles List and create CRM profiles Add New People Profile
website:people:conversations List conversations attached to CRM profiles List People Conversations
website:people:events List and push events in CRM profiles Add A People Event
website:people:data List and push data in CRM profiles Save People Data
website:people:subscriptions Manage email subscriptions for CRM profiles Get People Subscription Status
💡 Tip: the REST API Reference shows the required scopes for each route. Note that if the route method is either POST, PUT, PATCH or DELETE, you will need to use write permissions. Otherwise, read permissions are sufficient. You may also check the RTM API Reference for required scopes per event.

Considerations

Submission review process

As we want to ensure each integration with Crisp uses subscribed website data in a fair and privacy-first way, you need to request scopes through our submission review process over the Marketplace.

Whenever requesting scopes, you are prompted to choose its permission level, from read-only, to both read and write, or even write-only (where this is relevant).

Then, we ask that you explain why do you need this scope (ie. to do what, what do you intend to build with this scope?).