Roles

You can use the API to create, get, or set role information.

Note: To assign an agent to a role, please see Agents.

JSON Format

Roles are represented as JSON objects with the following attributes.

Name	Type	Read-only	Description
id	integer	yes	The ID of the role
name	string	yes*	The name of the role. *The name cannot be changed for the Owner, Admin, and Agent roles. You can change it for custom roles
description	string	yes*	The description of the role. *The description cannot be changed for the Owner, Admin, and Agent roles. You can change it for custom roles
enabled	boolean	yes*	Describes whether the role is enabled. *Owner, Admin, and Agent roles cannot be disabled. You can disable custom roles
members_count	integer	yes	The number of members on this role
permissions	object	yes*	The permissions for the role (described below). *The permissions cannot be changed for Owner and Admin roles. You can change them for Agent and custom roles

JSON Format for Permissions

Visitor List and Visualization

Name	Type	Possible values	Description
visitors_seen	string	`account`, `department`, `own`	Permission to see visitors on your site
proactive_chatting	string	`listen-join`, `listen`, `own`	Permission to listen to chat and/or proactively join a chat

listen: Listen to any chat visible to the agent
listen-join: Listen to any chat and proactively join a chat with any visitor visible to the agent
own: Not able to listen to any chat or proactively chat with any visitor on the Visitor List

Visitor Information

Name	Type	Possible values	Description
edit_visitor_information	boolean	`true`, `false`	Can edit user name, email, and phone via the chat panel or history
edit_visitor_notes	boolean	`true`, `false`	Can edit notes via the chat panel or history

History

Name	Type	Possible values	Description
view_past_chats	string	`account`, `department`, `own`, `none`	Permission to view past chats
edit_chat_tags	boolean	`true`, `false`	Can add or remove chat tags for past chats in history

Visitor Banning

Name	Type	Possible values	Description
manage_bans	string	`account`, `none`	Can temporarily ban visitors via browser cookies while in a chat or manage more permanent bans by IP

Analytics

Name	Type	Possible values	Description
access_analytics	string	`account`, `none`	Can access Analytics and Email Reports (under Personal Settings)

Monitor

Name	Type	Possible values	Description
view_monitor	string	`account`, `none`	Can view real-time metrics on Monitor across the whole account

Agent Management

Name	Type	Possible values	Description
edit_department_agents	string	`account`, `none`	Can add or edit agents in departments
set_agent_chat_limit	string	`account`, `none`	Can set chat limits for agents if agent limits are enabled

Shortcuts

Name	Type	Possible values	Description
manage_shortcuts	string	`account`, `none`	Can add, edit, or delete shortcuts that can be used by anyone while chatting with visitors

Permission String Values

account: permission for the whole account
department: permission limited to user's department
own: permission limited to user's own information
none: no permission

Get All Roles

GET /api/v2/roles

Lists all the roles for your account.

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/roles \
  -v -u {email_address}:{password}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Owner",
    "description": "The person who set up the account. In addition to agent and administrator privileges, this role can adjust the account's plan, change billing information, and cancel the account. Permissions for Owner role cannot be modified.",
    "enabled": true,
    "members_count": 1,
    "permissions" : {
      "visitors_seen": "account",
      "proactive_chatting": "listen-join",
      "edit_visitor_information": true,
      "edit_visitor_notes": true,
      "view_past_chats": "account",
      "edit_chat_tags": true,
      "manage_bans": "account",
      "access_analytics": "account",
      "view_monitor": "account",
      "edit_department_agents": "account",
      "set_agent_chat_limit": "account",
      "manage_shortcuts": "account"
    }
  },
  {
    "id": 8,
    "name": "Team Lead",
    "description": "Team Lead",
    "enabled": true,
    "members_count": 10,
    "permissions": {
      "visitors_seen": "own",
      "proactive_chatting": "own",
      "edit_visitor_information": true,
      "edit_visitor_notes": true,
      "view_past_chats": "own",
      "edit_chat_tags": true,
      "manage_bans": "account",
      "access_analytics": "account",
      "view_monitor": "account",
      "edit_department_agents": "account",
      "set_agent_chat_limit": "account",
      "manage_shortcuts": "account"
    }
  }
]

Get Role

GET /api/v2/roles/{role_id}

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/roles/{role_id} \
  -v -u {email_address}:{password}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "Owner",
  "description": "The person who set up the account. In addition to agent and administrator privileges, this role can adjust the account's plan, change billing information, and cancel the account. Permissions for Owner role cannot be modified.",
  "enabled": true,
  "members_count": 1,
  "permissions": {
    "visitors_seen": "account",
    "proactive_chatting": "listen-join",
    "edit_visitor_information": true,
    "edit_visitor_notes": true,
    "view_past_chats": "account",
    "edit_chat_tags": true,
    "manage_bans": "account",
    "access_analytics": "account",
    "view_monitor": "account",
    "edit_department_agents": "account",
    "set_agent_chat_limit": "account",
    "manage_shortcuts": "account"
  }
}

Create Role

POST /api/v2/roles

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/roles \
  -d '{
        "name": "Team Lead"
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 10000,
  "name": "Team Lead",
  "description": "",
  "enabled": true,
  "members_count": 0,
  "permissions": {
    "visitors_seen": "account",
    "proactive_chatting": "listen-join",
    "edit_visitor_information": true,
    "edit_visitor_notes": true,
    "view_past_chats": "account",
    "edit_chat_tags": false,
    "manage_bans": "account",
    "access_analytics": "none",
    "view_monitor": "account",
    "edit_department_agents": "none",
    "set_agent_chat_limit": "none",
    "manage_shortcuts": "account"
  }
}

Update Role

PUT /api/v2/roles/{role_id}

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/roles/{role_id} \
  -d '{
        "enabled": true,
        "description": "Updated description",
        "permissions": {
          "edit_visitor_information": false
        }
      }' \
  -v -u {email_address}:{password}
  -X PUT -H "Content-Type: application/json"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10000,
  "name": "Team Lead",
  "description": "Updated description",
  "enabled": true,
  "members_count": 0,
  "permissions": {
    "visitors_seen": "account",
    "proactive_chatting": "listen-join",
    "edit_visitor_information": false,
    "edit_visitor_notes": true,
    "view_past_chats": "account",
    "edit_chat_tags": false,
    "manage_bans": "account",
    "access_analytics": "none",
    "view_monitor": "account",
    "edit_department_agents": "none",
    "set_agent_chat_limit": "none",
    "manage_shortcuts": "account"
  }
}

Delete Role

DELETE /api/v2/roles/{role_id}

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/roles/{role_id} \
  -v -u {email_address}:{password} -X DELETE

Response

Status: 204 No Content