import builtins
from collections.abc import Generator
from typing import Optional
from pydantic import TypeAdapter
from wxc_sdk.api_child import ApiChild
from wxc_sdk.base import ApiModel
from wxc_sdk.common import PatternAction, UserType
__all__ = ['SupervisorApi', 'IdAndAction', 'SupervisorAgentStatus', 'AgentOrSupervisor']
# mypy: disable-error-code="assignment"
[docs]
class AgentOrSupervisor(ApiModel):
#: A unique identifier for the supervisor.
id: Optional[str] = None
#: First name of the supervisor.
first_name: Optional[str] = None
#: Last name of the supervisor.
last_name: Optional[str] = None
display_name: Optional[str] = None
#: Primary phone number of the supervisor.
phone_number: Optional[str] = None
#: Primary phone extension of the supervisor.
extension: Optional[str] = None
#: Routing prefix of location.
routing_prefix: Optional[str] = None
#: Routing prefix + extension of a person.
esn: Optional[str] = None
#: Type of the person, workspace or virtual line.
type: Optional[UserType] = None
#: Denotes if the agent or supervisor has Customer Experience Essentials license.
has_cx_essentials: Optional[bool] = None
#: Number of agents managed by supervisor. A supervisor must manage at least one agent.
agent_count: Optional[int] = None
[docs]
class SupervisorAgentStatus(ApiModel):
#: ID of person, workspace or virtual line.
id: Optional[str] = None
#: status of the agent.
status: Optional[str] = None
#: Detailed message for the status.
message: Optional[str] = None
#: TODO: undocumented, issue 202
type: Optional[UserType] = None
[docs]
class IdAndAction(ApiModel):
#: ID of person, workspace or virtual line.
id: Optional[str]
#: Enumeration that indicates whether an agent needs to be added (`ADD`) or deleted (`DELETE`) from a supervisor.
action: PatternAction
[docs]
class SupervisorApi(ApiChild, base='telephony/config/supervisors'):
"""
Supervisors
Supervisors are users who manage agents and who perform functions including monitoring, coaching, and more.
Viewing these read-only device settings requires a full, device or
read-only administrator auth token with a scope of `spark-admin:telephony_config_read`.
Modifying these device settings requires a full or device
administrator auth token with a scope of `spark-admin:telephony_config_write`.
"""
[docs]
def list(
self,
name: str = None,
phone_number: str = None,
order: str = None,
has_cx_essentials: bool = None,
org_id: str = None,
**params,
) -> Generator[AgentOrSupervisor, None, None]:
"""
Get List of Supervisors with Customer Assist
Get list of supervisors for an organization.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
Requires a full, location, user or read-only administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param name: Only return the supervisors that match the given name.
:type name: str
:param phone_number: Only return the supervisors that match the given phone number, extension, or ESN.
:type phone_number: str
:param order: Sort results alphabetically by supervisor name, in ascending or descending order.
:type order: str
:param has_cx_essentials: Returns only the list of supervisors with Customer Assist license, when `true`.
Otherwise returns the list of supervisors with Customer Experience Basic license.
:type has_cx_essentials: bool
:param org_id: List the supervisors in this organization.
:type org_id: str
:return: Generator yielding :class:`AgentOrSupervisor` instances
"""
if org_id is not None:
params['orgId'] = org_id
if name is not None:
params['name'] = name
if phone_number is not None:
params['phoneNumber'] = phone_number
if order is not None:
params['order'] = order
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
url = self.ep()
return self.session.follow_pagination(url=url, model=AgentOrSupervisor, item_key='supervisors', params=params)
[docs]
def create(self, id: str, agents: builtins.list[str], has_cx_essentials: bool = None, org_id: str = None):
"""
Create a Supervisor with Customer Assist
Create a new supervisor. The supervisor must be created with at least one agent.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
This operation requires a full or location administrator auth token with a scope of
`spark-admin:telephony_config_write`.
:param id: A unique identifier for the supervisor.
:type id: str
:param agents: People, workspaces and virtual lines that are eligible to receive calls.
:type agents: list[str]
:param has_cx_essentials: Creates a Customer Assist queue supervisor, when `true`. Customer Assist queue
supervisors must have a Customer Assist license.
:type has_cx_essentials: bool
:param org_id: The organization ID where the supervisor needs to be created.
:type org_id: str
:rtype: None
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
body = dict()
body['id'] = id
body['agents'] = [{'id': agent_id} for agent_id in agents]
url = self.ep()
super().post(url, params=params, json=body)
[docs]
def delete(self, supervisor_id: str, org_id: str = None):
"""
Delete a Supervisor
Deletes the supervisor from an organization.
Supervisors are users who manage agents and who perform functions including monitoring, coaching, and more.
Requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
:param supervisor_id: Delete the specified supervisor.
:type supervisor_id: str
:param org_id: Delete the supervisor in the specified organization.
:type org_id: str
:rtype: None
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
url = self.ep(supervisor_id)
super().delete(url, params=params)
[docs]
def delete_bulk(
self,
supervisor_ids: builtins.list[str],
has_cx_essentials: bool = None,
delete_all: bool = None,
org_id: str = None,
) -> None:
"""
Delete the Call Queue or Customer Assist Supervisors
Delete the Call Queue or Customer Assist supervisors for an organization. Once you remove the supervisor,
assigned agents will lose their supervisor assignments.
Supervisors are users who manage agents and who perform functions including monitoring, coaching, and more.
Requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
:param supervisor_ids: Array of supervisors IDs to be deleted.
:type supervisor_ids: list[str]
:param has_cx_essentials: Delete the Customer Assist supervisors, when `true`. Otherwise delete the Call Queue
supervisors. The default value is `false`.
:type has_cx_essentials: bool
:param delete_all: If present the `supervisorIds` array is ignored, and all supervisors in the context are
deleted. **WARNING**: This will remove all supervisors from the organization.
:type delete_all: bool
:param org_id: Delete supervisors in bulk for this organization.
:type org_id: str
:rtype: None
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
body = dict()
body['supervisorIds'] = supervisor_ids
if delete_all is not None:
body['deleteAll'] = delete_all
url = self.ep()
super().delete(url, params=params, json=body)
[docs]
def available_supervisors(
self,
name: str = None,
phone_number: str = None,
order: str = None,
has_cx_essentials: bool = None,
org_id: str = None,
**params,
) -> Generator[AgentOrSupervisor, None, None]:
"""
List Available Supervisors with Customer Assist
Get list of available supervisors for an organization.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
This operation requires a full, user or read-only administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param name: Only return the supervisors that match the given name.
:type name: str
:param phone_number: Only return the supervisors that match the given phone number, extension, or ESN.
:type phone_number: str
:param order: Sort results alphabetically by supervisor name, in ascending or descending order.
:type order: str
:param has_cx_essentials: Returns only the list of available supervisors with Customer Assist license, when
`true`. When ommited or set to 'false', will return the list of available supervisors with Customer
Experience Basic license.
:type has_cx_essentials: bool
:param org_id: List the available supervisors in this organization.
:type org_id: str
:return: Generator yielding :class:`AgentOrSupervisor` instances
"""
if org_id is not None:
params['orgId'] = org_id
if name is not None:
params['name'] = name
if phone_number is not None:
params['phoneNumber'] = phone_number
if order is not None:
params['order'] = order
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
url = self.ep('availableSupervisors')
return self.session.follow_pagination(url=url, model=AgentOrSupervisor, item_key='supervisors', params=params)
[docs]
def details(
self,
supervisor_id: str,
name: str = None,
phone_number: str = None,
order: str = None,
has_cx_essentials: bool = None,
org_id: str = None,
**additional_params,
) -> Generator[AgentOrSupervisor, None, None]:
"""
GET Supervisor Details
Get details of a specific supervisor, which includes the agents associated agents with the supervisor, in an
organization.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
This operation requires a full, user or read-only administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param supervisor_id: List the agents assigned to this supervisor.
:type supervisor_id: str
:param name: Only return the agents that match the given name.
:type name: str
:param phone_number: Only return agents that match the given phone number, extension, or ESN.
:type phone_number: str
:param order: Sort results alphabetically by supervisor name, in ascending or descending order.
:type order: str
:param has_cx_essentials: Must be set to `true`, to view the details of a supervisor with Customer Experience
Essentials license. This can otherwise be ommited or set to `false`.
:type has_cx_essentials: bool
:param org_id: List the agents assigned to a supervisor in this organization.
:type org_id: str
:return: Generator yieldig :class:`AgentOtSupervisor` instances
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
if name is not None:
params['name'] = name
if phone_number is not None:
params['phoneNumber'] = phone_number
if order is not None:
params['order'] = order
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
params.update(additional_params)
url = self.ep(supervisor_id)
return self.session.follow_pagination(url=url, model=AgentOrSupervisor, params=params, item_key='agents')
[docs]
def assign_unassign_agents(
self, supervisor_id: str, agents: builtins.list[IdAndAction], has_cx_essentials: bool = None, org_id: str = None
) -> Optional[builtins.list[SupervisorAgentStatus]]:
"""
Assign or Unassign Agents to Supervisor
Assign or unassign agents to the supervisor for an organization.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
Requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
:param supervisor_id: Identifier of the supervisor to be updated.
:type supervisor_id: str
:param agents: People, workspaces and virtual lines that are eligible to receive calls.
:type agents: list[PutPersonPlaceVirtualLineAgentObject]
:param has_cx_essentials: Must be set to `true` to modify a supervisor with Customer Experience Essentials
license. This can otherwise be omitted or set to `false`.
:type has_cx_essentials: bool
:param org_id: Assign or unassign agents to a supervisor in this organization.
:type org_id: str
:rtype: list[SupervisorAgentStatus]
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
body = dict()
body['agents'] = TypeAdapter(list[IdAndAction]).dump_python(agents, mode='json', by_alias=True)
url = self.ep(supervisor_id)
data = super().put(url, params=params, json=body)
if not data:
return None
r = TypeAdapter(list[SupervisorAgentStatus]).validate_python(data['supervisorAgentStatus'])
return r
[docs]
def available_agents(
self,
name: str = None,
phone_number: str = None,
order: str = None,
has_cx_essentials: bool = None,
org_id: str = None,
**params,
) -> Generator[AgentOrSupervisor, None, None]:
"""
List Available Agents with Customer Assist
Get list of available agents for an organization.
Agents in a call queue can be associated with a supervisor who can silently monitor, coach, barge in or to take
over calls that their assigned agents are currently handling.
This operation requires a full, user or read-only administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param name: Returns only the agents that match the given name.
:type name: str
:param phone_number: Returns only the agents that match the phone number, extension, or ESN.
:type phone_number: str
:param order: Sort results alphabetically by supervisor name, in ascending or descending order.
:type order: str
:param has_cx_essentials: Returns only the list of available agents with Customer Assist license, when `true`.
When ommited or set to `false`, will return the list of available agents with Customer Experience Basic
license.
:type has_cx_essentials: bool
:param org_id: List of available agents in a supervisor's list for this organization.
:type org_id: str
:return: Generator yielding :class:`AgentOrSupervisor` instances
"""
if org_id is not None:
params['orgId'] = org_id
if name is not None:
params['name'] = name
if phone_number is not None:
params['phoneNumber'] = phone_number
if order is not None:
params['order'] = order
if has_cx_essentials is not None:
params['hasCxEssentials'] = str(has_cx_essentials).lower()
url = self.ep('availableAgents')
return self.session.follow_pagination(url=url, model=AgentOrSupervisor, item_key='agents', params=params)