"""
Person settings
"""
import builtins
from dataclasses import dataclass
from typing import Any, Optional
from pydantic import Field
from ..api_child import ApiChild
from ..base import ApiModel
from ..base import SafeEnum as Enum
from ..common import DeviceType, IdAndName, PrimaryOrShared, UserType
from ..common.schedules import ScheduleApi, ScheduleApiBase
from ..rest import RestSession
from .agent_caller_id import AgentCallerIdApi
from .anon_calls import AnonCallsApi
from .app_shared_line import AppSharedLineApi
from .appservices import AppServicesApi
from .available_numbers import AvailableNumbersApi
from .barge import BargeApi
from .call_intercept import CallInterceptApi
from .call_recording import CallRecordingApi
from .call_waiting import CallWaitingApi
from .callbridge import CallBridgeApi
from .caller_id import CallerIdApi
from .calling_behavior import CallingBehaviorApi
from .common import ApiSelector
from .dnd import DndApi
from .ecbn import ECBNApi
from .exec_assistant import ExecAssistantApi
from .executive import ExecutiveSettingsApi
from .feature_access import FeatureAccessApi
from .forwarding import PersonForwardingApi
from .hotdesking import HotDeskingApi
from .hoteling import HotelingApi
from .mode_management import ModeManagementApi
from .moh import MusicOnHoldApi
from .monitoring import MonitoringApi
from .msteams import MSTeamsSettingApi
from .numbers import NumbersApi
from .permissions_in import IncomingPermissionsApi
from .permissions_out import OutgoingPermissionsApi
from .personal_assistant import PersonalAssistantApi
from .preferred_answer import PreferredAnswerApi
from .privacy import PrivacyApi
from .push_to_talk import PushToTalkApi
from .receptionist import ReceptionistApi
from .selective_accept import SelectiveAcceptApi
from .selective_forward import SelectiveForwardApi
from .selective_reject import SelectiveRejectApi
from .sim_ring import SimRingApi
from .single_number_reach import SingleNumberReachApi
from .voicemail import VoicemailApi
__all__ = [
'PersonSettingsApi',
'DeviceOwner',
'DeviceActivationState',
'Hoteling',
'TelephonyDevice',
'DeviceList',
'UserCallCaptions',
'PersonSettings',
]
# mypy: disable-error-code="assignment,type-arg,arg-type,override"
# TODO: UC profile
[docs]
class DeviceOwner(ApiModel):
#: unique identifier for user or workspace the device is owned by
owner_id: str = Field(alias='id', default=None)
#: last name of device owner.
last_name: Optional[str] = None
#: First name of device owner.
first_name: Optional[str] = None
#: user or workspace?
owner_type: UserType = Field(alias='type')
#: user location
location: Optional[IdAndName] = None
[docs]
class DeviceActivationState(str, Enum):
activating = 'ACTIVATING'
activated = 'ACTIVATED'
deactivated = 'DEACTIVATED'
[docs]
class Hoteling(ApiModel):
#: Enable/Disable hoteling Host. Enabling the device for hoteling means that a guest(end user) can log into this
#: host(workspace device) and use this device
#: as if it were their own. This is useful when traveling to a remote office but still needing to place/receive
#: calls with their telephone number and access features normally available to them on their office phone.
enabled: Optional[bool] = None
#: Enable limiting the time a guest can use the device. The time limit is configured via guestHoursLimit.
limit_guest_use: Optional[bool] = None
#: Time Limit in hours until hoteling is enabled. Mandatory if limitGuestUse is enabled.
guest_hours_limit: Optional[int] = None
[docs]
class TelephonyDevice(ApiModel):
#: Unique identifier for a device.
device_id: str = Field(alias='id')
#: Comma separated array of tags used to describe device.
description: list[str]
#: Identifier for device model.
model: str
#: Indicates if the line is acting as a primary line or a shared line for this device.
type: Optional[PrimaryOrShared] = None
#: Identifier for device model type.
mod_type: DeviceType = Field(alias='modelType', default=None)
#: MAC address of device.
mac: Optional[str] = None
#: IP address of device.
ip_address: Optional[str] = None
#: This field indicates whether the person or the workspace is the owner of the device, and points to a primary
#: Line/Port of the device.
primary_owner: bool
#: Hoteling login settings, which are available when the device is the owner's primary device and device type is
#: PRIMARY. Hoteling login settings are set at the owner level.
hoteling: Optional[Hoteling] = None
#: Indicates if the line is acting as a primary line or a shared line for this device.
device_type: PrimaryOrShared = Field(alias='type')
#: Owner of device.
owner: Optional[DeviceOwner] = None
#: Activation state of device.
activation_state: DeviceActivationState
# location details, only returned in context of virtual lines?
location: Optional[IdAndName] = None
[docs]
class DeviceList(ApiModel):
#: Array of devices available to person.
devices: list[TelephonyDevice]
#: Maximum number of devices a person can be assigned to.
max_device_count: int
#: Maximum number of devices a person can own.
max_owned_device_count: Optional[int] = None
[docs]
class UserCallCaptions(ApiModel):
#: User-level closed captions are enabled or disabled.
user_closed_captions_enabled: Optional[bool] = None
#: User-level transcripts are enabled or disabled.
user_transcripts_enabled: Optional[bool] = None
#: Location closed captions are enabled or disabled. If `useOrgSettingsEnabled` is `true`, these are
#: organization-level settings. Otherwise, location-level settings are used.
location_closed_captions_enabled: Optional[bool] = None
#: Location transcripts are enabled or disabled. If `useOrgSettingsEnabled` is `true`, these are organization-level
#: settings. Otherwise, location-level settings are used.
location_transcripts_enabled: Optional[bool] = None
#: If `useLocationSettingsEnabled` is `true`, location settings will control the user's closed captions and
#: transcripts. Otherwise, user-level settings are used.
use_location_settings_enabled: Optional[bool] = None
def update(self) -> dict:
"""
data for update
:meta private:
"""
return self.model_dump(
mode='json',
by_alias=True,
exclude_none=True,
exclude_unset=True,
exclude={'location_closed_captions_enabled', 'location_transcripts_enabled'},
)
[docs]
class PersonSettings(ApiModel):
#: Person's phone announcement language.
announcement_language: Optional[str] = None
#: Timezone associated with the person for calling package. Refer to the Get Country Configuration API to retrieve
#: the list of available timezones for a specific country.
time_zone: Optional[str] = None
[docs]
@dataclass(init=False, repr=False)
class PersonSettingsApi(ApiChild, base='people'):
"""
API for all user level settings
"""
#: agent caller id Api
agent_caller_id: AgentCallerIdApi
anon_calls: AnonCallsApi
app_shared_line: AppSharedLineApi
#: Person's Application Services Settings
appservices: AppServicesApi
#: Available numbers for a person
available_numbers: AvailableNumbersApi
#: Barge In Settings for a Person
barge: BargeApi
#: Call bridge settings for a person
call_bridge: CallBridgeApi
#: Call Intercept Settings for a Person
call_intercept: CallInterceptApi
#: Call Recording Settings for a Person
call_recording: CallRecordingApi
#: Call Waiting Settings for a Person
call_waiting: CallWaitingApi
#: Caller ID Settings for a Person
caller_id: CallerIdApi
#: Person's Calling Behavior
calling_behavior: CallingBehaviorApi
#: Do Not Disturb Settings for a Person
dnd: DndApi
#: ECBN settings
ecbn: ECBNApi
#: Executive Assistant settings for a Person
exec_assistant: ExecAssistantApi
#: Executive settings for a person
executive: ExecutiveSettingsApi
#: Feature access settings for a person
feature_access: FeatureAccessApi
#: Forwarding Settings for a Person
forwarding: PersonForwardingApi
hotdesking: HotDeskingApi
#: Hoteling Settings for a Person
hoteling: HotelingApi
#: Person's mode management settings
mode_management: ModeManagementApi
#: Person's Monitoring Settings
monitoring: MonitoringApi
# ; MS Teams settings
ms_teams: MSTeamsSettingApi
#: music on hold settings
music_on_hold: MusicOnHoldApi
#: Phone Numbers for a Person
numbers: NumbersApi
#: Incoming Permission Settings for a Person
permissions_in: IncomingPermissionsApi
#: Person's Outgoing Calling Permissions Settings
permissions_out: OutgoingPermissionsApi
#: Personal Assistant Settings
personal_assistant: PersonalAssistantApi
#: Preferred answer endpoint settings
preferred_answer: PreferredAnswerApi
#: Person's Privacy Settings
privacy: PrivacyApi
#: Push-to-Talk Settings for a Person
push_to_talk: PushToTalkApi
#: Receptionist Client Settings for a Person
receptionist: ReceptionistApi
#: Schedules for a Person
schedules: ScheduleApi
#: selective accept settings
selective_accept: SelectiveAcceptApi
#: selective forward settings
selective_forward: SelectiveForwardApi
#: selective reject settings
selective_reject: SelectiveRejectApi
sim_ring: SimRingApi
#: single nunber reach settings
single_number_reach: SingleNumberReachApi
#: Voicemail Settings for a Person
voicemail: VoicemailApi
[docs]
def __init__(self, session: RestSession):
"""
:meta private:
"""
super().__init__(session=session)
self.agent_caller_id = AgentCallerIdApi(session=session)
self.anon_calls = AnonCallsApi(session=session)
self.app_shared_line = AppSharedLineApi(session=session)
self.appservices = AppServicesApi(session=session)
self.available_numbers = AvailableNumbersApi(session=session)
self.barge = BargeApi(session=session)
self.call_bridge = CallBridgeApi(session=session)
self.call_intercept = CallInterceptApi(session=session)
self.call_recording = CallRecordingApi(session=session)
self.call_waiting = CallWaitingApi(session=session)
self.calling_behavior = CallingBehaviorApi(session=session)
self.caller_id = CallerIdApi(session=session)
self.dnd = DndApi(session=session)
self.ecbn = ECBNApi(session=session)
self.exec_assistant = ExecAssistantApi(session=session)
self.executive = ExecutiveSettingsApi(session=session)
self.feature_access = FeatureAccessApi(session=session)
self.forwarding = PersonForwardingApi(session=session)
self.hotdesking = HotDeskingApi(session=session)
self.hoteling = HotelingApi(session=session)
self.mode_management = ModeManagementApi(session=session)
self.monitoring = MonitoringApi(session=session)
self.ms_teams = MSTeamsSettingApi(session=session)
self.music_on_hold = MusicOnHoldApi(session=session)
self.numbers = NumbersApi(session=session)
self.permissions_in = IncomingPermissionsApi(session=session)
self.permissions_out = OutgoingPermissionsApi(session=session)
self.personal_assistant = PersonalAssistantApi(session=session)
self.preferred_answer = PreferredAnswerApi(session=session)
self.privacy = PrivacyApi(session=session)
self.push_to_talk = PushToTalkApi(session=session)
self.receptionist = ReceptionistApi(session=session)
self.schedules = ScheduleApi(session=session, base=ScheduleApiBase.people)
self.selective_accept = SelectiveAcceptApi(session=session, selector=ApiSelector.person)
self.selective_forward = SelectiveForwardApi(session=session, selector=ApiSelector.person)
self.selective_reject = SelectiveRejectApi(session=session, selector=ApiSelector.person)
self.sim_ring = SimRingApi(session=session, selector=ApiSelector.person)
self.single_number_reach = SingleNumberReachApi(session=session)
self.voicemail = VoicemailApi(session=session)
# This endpoint is also available in the voicemail API and is only kept here for backward compatibility.
[docs]
def reset_vm_pin(self, person_id: str, org_id: str = None):
"""
Reset Voicemail PIN
Reset a voicemail PIN for a person.
The voicemail feature transfers callers to voicemail based on your settings. You can then retrieve voice
messages via Voicemail. A voicemail PIN is used to retrieve your voicemail messages.
This API requires a full or user administrator auth token with the spark-admin:people_write scope.
This endpoint is also available in the voicemail API and is only kept here for backward compatibility.
:param person_id: Unique identifier for the person.
:param org_id: Person is in this organization. Only admin users of another organization (such as partners) may
use this parameter as the default is the same organization as the token used to access API.
"""
params = org_id and {'orgId': org_id} or None
url = self.ep(f'{person_id}/features/voicemail/actions/resetPin/invoke')
self.post(url, params=params)
[docs]
def devices(self, person_id: str, org_id: str = None) -> DeviceList:
"""
Get all devices for a person.
This requires a full or read-only administrator or location administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param person_id: Person to retrieve devices for
:type person_id: str
:param org_id: organization that person belongs to
:type org_id: str
:return: device info for user
:rtype: DeviceList
"""
params = org_id and {'orgId': org_id} or None
url = self.session.ep(f'telephony/config/people/{person_id}/devices')
data = super().get(url=url, params=params)
return DeviceList.model_validate(data)
# noinspection PyShadowingNames
[docs]
def modify_hoteling_settings_primary_devices(self, person_id: str, hoteling: Hoteling, org_id: str = None):
"""
Modify Hoteling Settings for a Person's Primary Devices
Modify hoteling login configuration on a person's Webex Calling Devices which are in effect when the device is
the user's primary device and device type is PRIMARY. To view the current hoteling login settings, see the
`hoteling` field in `Get Person Devices
<https://developer.webex.com/docs/api/v1/device-call-settings/get-person-devices>`_.
Modifying devices for a person requires a full administrator or location administrator auth token with a scope
of `spark-admin:telephony_config_write`.
:param person_id: ID of the person associated with the device.
:type person_id: str
:param hoteling: Modify person Device Hoteling Setting.
:type hoteling: Hoteling
:param org_id: Organization to which the person belongs.
:type org_id: str
:rtype: None
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
body = dict()
body['hoteling'] = hoteling.model_dump(mode='json', by_alias=True, exclude_none=True)
url = self.session.ep(f'telephony/config/people/{person_id}/devices/settings/hoteling')
super().put(url, params=params, json=body)
[docs]
def get_call_captions_settings(self, person_id: str, org_id: str = None) -> UserCallCaptions:
"""
Get the user call captions settings
Retrieve the user's call captions settings.
**NOTE**: The call captions feature is not supported for Webex Calling Standard users or users assigned to
locations in India.
The call caption feature allows the customer to enable and manage closed captions and transcript functionality
(rolling caption panel) in Webex Calling, without requiring the user to escalate the call to a meeting.
This API requires a full, user, read-only, or location administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param person_id: Unique identifier for the person.
:type person_id: str
:param org_id: Unique identifier for the organization.
:type org_id: str
:rtype: :class:`UserCallCaptions`
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
url = self.session.ep(f'telephony/config/people/{person_id}/callCaptions')
data = super().get(url, params=params)
r = UserCallCaptions.model_validate(data)
return r
[docs]
def update_call_captions_settings(self, person_id: str, settings: UserCallCaptions, org_id: str = None):
"""
Update the user call captions settings
Update the user's call captions settings.
**NOTE**: The call captions feature is not supported for Webex Calling Standard users or users assigned to
locations in India.
The call caption feature allows the customer to enable and manage closed captions and transcript functionality
(rolling caption panel) in Webex Calling, without requiring the user to escalate the call to a meeting.
This API requires a full, user or location administrator auth token with a scope of
`spark-admin:telephony_config_write`.
:param person_id: Unique identifier for the person.
:type person_id: str
:param settings: User call captions settings.
:type settings: UserCallCaptions
:param org_id: Unique identifier for the organization.
:type org_id: str
:rtype: None
"""
params = {}
if org_id is not None:
params['orgId'] = org_id
body = settings.update()
url = self.session.ep(f'telephony/config/people/{person_id}/callCaptions')
super().put(url, params=params, json=body)
[docs]
def get(self, person_id: str, org_id: str = None) -> PersonSettings:
"""
Get Timezone and Announcement Language Settings of a Person
Retrieve a person's timezone and announcement language settings.
Webex Calling supports configuring timezone and announcement language preferences, allowing personalized call
experience based on their location and language preferences.
This API requires a full or read-only administrator auth token with a scope of
`spark-admin:telephony_config_read`.
:param person_id: Retrieve timezone and announcement language settings of this person.
:type person_id: str
:param org_id: Organization ID. If not specified, uses the organization from the OAuth token.
:type org_id: str
:rtype: :class:`PersonSettings`
"""
params: dict[str, Any] = dict()
if org_id is not None:
params['orgId'] = org_id
url = self.session.ep(f'telephony/config/people/{person_id}')
data = super().get(url, params=params)
r = PersonSettings.model_validate(data)
return r
[docs]
def modify(
self, person_id: str, announcement_language: str = None, time_zone: str = None, org_id: str = None
) -> None:
"""
Update Timezone and Announcement Language Settings of a Person
Modify a person's timezone and announcement language settings.
Webex Calling supports configuring timezone and announcement language preferences, allowing personalized call
experience based on their location and language preferences.
This API requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
:param person_id: Modify timezone and announcement language settings of this person.
:type person_id: str
:param announcement_language: Person's phone announcement language.
:type announcement_language: str
:param time_zone: Timezone associated with the person for calling configuration. Refer to the Get Country
Configuration API to retrieve the list of available timezones for a specific country.
:type time_zone: str
:param org_id: Organization ID. If not specified, uses the organization from the OAuth token.
:type org_id: str
:rtype: None
"""
params: dict[str, Any] = dict()
if org_id is not None:
params['orgId'] = org_id
body: dict[str, Any] = dict()
if announcement_language is not None:
body['announcementLanguage'] = announcement_language
if time_zone is not None:
body['timeZone'] = time_zone
url = self.session.ep(f'telephony/config/people/{person_id}')
super().put(url, params=params, json=body)
[docs]
def get_calling_services(self, person_id: str, org_id: str = None) -> builtins.list[str]:
"""
List Enabled Calling Services for a Person
Retrieves the list of enabled calling services for a person.
Calling services are designed to improve call handling and ensure that people can manage their communications
effectively.
Viewing requires a full, read-only, user, or location administrator auth token with a scope of
`spark-admin:people_read`.
:param person_id: Unique identifier for the person.
:type person_id: str
:param org_id: Organization ID. If not specified, uses the organization from the OAuth token.
:type org_id: str
:rtype: list[str]
"""
params: dict[str, Any] = dict()
if org_id is not None:
params['orgId'] = org_id
url = self.session.ep(f'telephony/config/people/{person_id}/services')
data = super().get(url, params=params)
r = data['services']
return r # type: ignore[return-value]