Scopes

1 minutes reading time

Scopes define access to certain resources. Your app will ask users for access to those resources during the installation. Depending on the functionality of the app you're building, you'll need to configure different scopes in Developer Console. To check which scopes your app needs, refer to method descriptions.

General rules

  • ro means read only
  • rw means read/write
  • rc means read/create
  • all rw scopes contain ro privileges
  • all access scopes contain my privileges
  • all all scopes contain access privileges and my privileges

Accounts scope types

Account scopes

ScopeProductRoleRole TypeDescription
accounts--my:roAccountsmemberprimaryRead permission for my account
accounts--my:rwAccountsmemberprimaryRead and modify permission for my account
accounts--all:roAccountsmemberprimaryRead permission for all accounts in an organization
accounts--all:rwAccountsadministratorprimaryRead and modify permission for all accounts
accounts--all:rcAccountsmemberprimaryCreate and read accounts (mofidication is denied)

Role scopes

ScopeProductRoleRole TypeDescription
accounts.roles--all:roAccountsmemberprimaryRead all accounts roles
accounts.roles--all:rwAccountsadministratorprimaryRead and modify all accounts roles

Session scopes

ScopeProductRoleRole TypeDescription
sessions--my:roAccountsmemberprimaryRead my sessions
sessions--my:rwAccountsmemberprimaryRead and modify my sessions

Organization scopes

ScopeProductRoleRole TypeDescription
organization--my:rwAccountsownerprimaryRead and modify organization settings

LiveChat scope types

Agent scopes

ScopeProductRoleRole TypeDescription
agents--my:rwLiveChatnormalsecondaryWrite permission for my profile configuration
agents--my:roLiveChatnormalsecondaryRead permission for my profile configuration
agents--all:rwLiveChatadministratorsecondaryWrite permission for all agents profiles configuration
agents--all:roLiveChatadministratorsecondaryRead permission for all agents profiles configuration
access_rules:roLiveChatadministratorsecondaryRead permission for auto chat scopes configuration
access_rules:rwLiveChatadministratorsecondaryRead/write permission for auto chat scopes configuration

Accounts scopes

ScopeProductRoleRole TypeDescription
accounts--all:rcAccountsmemberprimaryCreate and read accounts (mofidication is denied)

Bot scopes

ScopeProductRoleRole TypeDescription
agents-bot--my:roLiveChatadministratorsecondaryRead permission for bot agents configuration (only my bot agents)
agents-bot--my:rwLiveChatadministratorsecondaryRead/write permission for bot agents configuration (only my bot agents)
agents-bot--all:roLiveChatnormalsecondaryRead permission for bot agents configuration (all in license)
agents-bot--all:rwLiveChatadministratorsecondaryRead/write permission for bot agents configuration (all in license, delete only)

Group scopes

ScopeProductRoleRole TypeDescription
groups--my:rwLiveChatadministratorsecondaryWrite/read permission for groups I'm a member of
groups--my:roLiveChatnormalsecondaryRead permission for groups I'm a member of
groups--all:rwLiveChatadministratorsecondaryWrite/read permission for all groups within a license
groups--all:roLiveChatnormalsecondaryRead permission for all groups within a license

Chat scopes

ScopeProductRoleRole TypeDescription
chats--all:roLiveChatadministratorsecondaryRead permission for conversation and meta data of all license chats
chats--access:roLiveChatnormalsecondaryRead permission for conversation and meta data of chats with requester access
chats--my:roLiveChatnormalsecondaryRead permission for conversation and meta data of the chats with requester presence
chats.conversation--all:rwLiveChatadministratorsecondaryWrite permission for conversation data of all license chats and Read permission for conversation and meta data of all license chats (chats--all:ro)
chats.conversation--access:rwLiveChatnormalsecondaryWrite permission for conversation data of chats with requester access and Read permission for conversation and meta data of chats with requester access (chats--access:ro)
chats.conversation--my:rwLiveChatnormalsecondaryRead/write permission for conversation data of chats with requester presence and Read permission for conversation and meta data of the chats with requester presence (chats--my:ro)
chats--all:rwLiveChatadministratorsecondaryRead/write permission for conversation and meta data of all license chats
chats--access:rwLiveChatnormalsecondaryRead/write permission for conversation and meta data of chats with requester access
chats--my:rwLiveChatnormalsecondaryRead/write permission for conversation and meta data of chats with requester presence
  • chats conversation data applies to:
    • chat events
    • chat properties
    • thread properties
  • chats meta data applies to:
    • chat users

NOTICE: currently chats.conversation--all:rw allows joining chats too because you have to join the chat to be able to write to it

Customer scopes

ScopeProductRoleRole TypeDescription
customers.ban:rwLiveChatnormalsecondaryPermission for banning customers
customers:ownLiveChatadministratorsecondaryPermission for owning and managing customer identities. It allows for acquiring a customer token (for both existing and new customers) and using it to call the Customer Chat API as a customer.
customers:roLiveChatnormalsecondaryRead permission for customers
customers:rwLiveChatnormalsecondaryRead/write permission for existing customers. It also allows for creating new customers via the Agent Chat API.

Multicast scopes

ScopeProductRoleRole TypeDescription
multicast:rwLiveChatnormalsecondaryPermission for multicast data to agents or customers

Properties scopes

ScopeProductRoleRole TypeDescription
properties--my:roLiveChatadministratorsecondaryRead permission for chat/thread/events properties configuration (only in my namespace)
properties--my:rwLiveChatadministratorsecondaryRead/write permission for chat/thread/events properties configuration (only in my namespace)
properties--all:roLiveChatadministratorsecondaryRead permission for chat/thread/events properties configuration (all in license)
properties--configuration:rwLiveChatadministratorsecondaryRead/write permission for license/group/chat/thread/event properties configuration (for all integrations owned by my license)

Webhook scopes

ScopeProductRoleRole TypeDescription
webhooks--my:roLiveChatadministratorsecondaryRead permission for webhooks configuration (only my webhooks)
webhooks--my:rwLiveChatadministratorsecondaryRead/write permission for webhooks configuration (only my webhooks)
webhooks--all:roLiveChatadministratorsecondaryRead permission for webhooks configuration (all in license)
webhooks--all:rwLiveChatadministratorsecondaryRead/write permission for webhooks configuration (all in license, delete only)
webhooks.state:roLiveChatadministratorsecondaryRead permission for the webhook state (only my webhooks)
webhooks.state:rwLiveChatadministratorsecondaryRead/write permission for enabling/disabling webhooks (only my webhooks)
webhooks.configuration:rwLiveChatadministratorsecondaryRead/write permission for adding and updating the webhook configuration

Accessing chat

This chart shows every possible chats scenarios:

  • chats without my access and without my presence (chats -A -P)
  • chats with my access but without my presence (chats +A -P)
  • chats with my presence but without my access (chats -A +P)
  • chats with my access and with my presence (chats +A +P)

Scopes diagram

The table shows scopes dependency of accessing chat:

chats -A -Pchats +A -Pchats -A +Pchats +A +P
all
access-
my--

Accessing parts of chat

The table shows scopes dependency of accessing chat parts:

meta dataconversation data
chats-*:rwrwrw
chats.conversation-*:rwrorw
chats-*:rororo