API docs by Redocly

Roles API (1.0.0)

Download OpenAPI specification:

API documentation for managing group roles, including custom feature settings and video configurations.

Roles

Returns list of roles

Get the list of roles for the group.

Required Permissions:

  • GROUP_OWNER role

Additional Authorization:

  • User must belong to the requested group (returns 403 if accessing a different group)
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ]
}

Create one or more roles

Create one or more roles for the group. Each role can have custom settings that override group-level settings.

Required Permissions:

  • GROUP_OWNER role
  • CAPABILITY permission for the group (including parent groups with subgroup permissions)

Validation Rules:

  • Role name is required and cannot exceed 70 characters
  • Role name cannot be empty, null, or contain only whitespace
  • Role description cannot exceed 255 characters
  • Role name must be unique within the group
  • Role settings cannot enable features that are disabled at the group level
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

Request Body schema: application/json
required
Array
name
required
string <= 70 characters

The name of the role (required, cannot be empty or whitespace only).

description
string <= 255 characters

A description of the role (optional).

object

Feature permissions and capabilities assigned to a role. Each boolean controls whether users with this role can access the corresponding feature. Role-specific settings (optional). All settings are nullable booleans.

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Update one or more roles

Update one or more roles in the group. You can update the name, description, and/or settings for each role.

Required Permissions:

  • GROUP_OWNER role
  • CAPABILITY permission for the group (including parent groups with subgroup permissions)

Validation Rules:

  • At least one field (name, description, or settings) must be provided for each role
  • Role name cannot exceed 70 characters if provided
  • Role description cannot exceed 255 characters if provided
  • Role must exist in the group
  • Role settings cannot enable features that are disabled at the group level
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

Request Body schema: application/json
required
Array
roleId
required
integer

The ID of the role to update (required).

name
string <= 70 characters

The new name for the role (optional).

description
string <= 255 characters

The new description for the role (optional).

object

Feature permissions and capabilities assigned to a role. Each boolean controls whether users with this role can access the corresponding feature. Updated role settings (optional). All settings are nullable booleans. Null values mean "don't change".

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status": "ok"
}

Return information for specific role

Get detailed information about a specific role, including all role settings.

Required Permissions:

  • GROUP_OWNER role

Additional Authorization:

  • User must belong to the requested group (returns 403 if accessing a different group)
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

role_id
required
integer

The ID of the role

Responses

Response samples

Content type
application/json
{
  • "name": "Agent",
  • "roleId": 1,
  • "description": "Standard agent role",
  • "inUse": true,
  • "settings": {
    }
}

Update a specific role

Update a specific role in the group. You can update the name, description, and/or settings for the role.

Required Permissions:

  • GROUP_OWNER role

Validation Rules:

  • At least one field (name, description, or settings) must be provided
  • Role name cannot exceed 70 characters if provided
  • Role name cannot be empty, null, or contain only whitespace if provided
  • Role description cannot exceed 255 characters if provided
  • Role must exist in the group
  • Role name must be unique within the group (cannot duplicate an existing role name)
  • Role settings cannot enable features that are disabled at the group level
  • All settings are optional and nullable booleans. Null values mean "don't change this setting"
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

role_id
required
integer

The ID of the role to update

Request Body schema: application/json
required
name
string

The new name for the role (optional, max 70 characters if provided)

description
string

The new description for the role (optional, max 255 characters if provided)

object

Feature permissions and capabilities assigned to a role. Each boolean controls whether users with this role can access the corresponding feature. Updated role settings (optional). All settings are nullable booleans. Null values mean "don't change".

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Updated Agent Role"
}

Response samples

Content type
application/json
{
  • "message": "Role updated."
}

Delete one or more roles

Delete one or more roles from the group.

Important: A role cannot be deleted if it has users assigned to it. Users must be disassociated from the role before deletion.

Required Permissions:

  • GROUP_OWNER role
  • CAPABILITY permission for the group (including parent groups with subgroup permissions)
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

Request Body schema: application/json
required

An array of role IDs to delete from the group.

Array
integer

The unique ID of a role to delete.

Responses

Request samples

Content type
application/json
Example
[
  • 1
]

Response samples

Content type
application/json
{
  • "status": "ok"
}

Update role video settings

Update video settings for one or more roles in the group. Video settings control background effects for agent video.

Required Permissions:

  • GROUP_OWNER role
  • CAPABILITY permission for the group (including parent groups with MEMBER_SUBGROUP_PERMISSION or CUSTOMER_SUBGROUP_PERMISSION)

Validation Rules:

  • Request body cannot be empty
  • Role must exist in the group
  • If backgroundSelectedEffect is "imagefill", backgroundImageSettings must be provided
  • If backgroundSelectedEffect is "colorfill", fillColor must be provided
Authorizations:
BearerAuth
path Parameters
group_id
required
integer

The group ID (Must be a positive unsigned integer)

Request Body schema: application/json
required
Array
roleId
required
integer

The ID of the role to update video settings for (required)

backgroundSelectedEffect
string or null

The background effect type. Must be "imagefill" or "colorfill" if provided. If "imagefill", backgroundImageSettings must be provided. If "colorfill", fillColor must be provided.

fillColor
string or null

The fill color for the video background. Required if backgroundSelectedEffect is "colorfill".

backgroundImageSettings
string or null

The background image settings. Required if backgroundSelectedEffect is "imagefill".

Responses

Request samples

Content type
application/json
Example
[]

Response samples

Content type
application/json
{
  • "message": "Role video settings updated successfully"
}