from typing import Optional, ClassVar
from pydantic import Field, field_validator
from .common import PersonSettingsApiChild
from ..base import ApiModel, to_camel, plus1
from ..base import SafeEnum as Enum
__all__ = ['CallerIdApi', 'CallerId', 'ExternalCallerIdNamePolicy', 'CallerIdSelectedType']
[docs]
class CallerIdSelectedType(str, Enum):
"""
Allowed types for the selected field.
"""
#: Outgoing caller ID will show the caller's direct line number and/or extension.
direct_line = 'DIRECT_LINE'
#: Outgoing caller ID will show the main number for the location.
location_number = 'LOCATION_NUMBER'
#: Outgoing caller ID will show the mobile number for this person.
mobile_number = 'MOBILE_NUMBER'
#: Outgoing caller ID will show the value from the customNumber field.
custom = 'CUSTOM'
[docs]
class ExternalCallerIdNamePolicy(str, Enum):
"""
Designates which type of External Caller ID Name policy is used. Default is DIRECT_LINE.
"""
#: Outgoing caller ID will show the caller's direct line name
direct_line = 'DIRECT_LINE'
#: Outgoing caller ID will show the Site Name for the location.
location = 'LOCATION'
#: Outgoing caller ID will show the value from the custom_external_caller_id_name field.
other = 'OTHER'
[docs]
class CallerId(ApiModel):
"""
Caller id settings of a user
"""
@field_validator('direct_number', 'location_number', 'mobile_number', 'custom_number', mode='before')
def e164(cls, v):
"""
:meta private:
"""
return plus1(v)
#: Allowed types for the `selected` field. This field is read-only and cannot be modified.
caller_id_types: Optional[list[CallerIdSelectedType]] = Field(alias='types', default=None)
#: Which type of outgoing Caller ID will be used. This setting is for the number portion.
#: example: DIRECT_LINE
selected: Optional[CallerIdSelectedType] = None
#: Direct number which will be shown if `DIRECT_LINE` is selected.
#: example: 2025551212
direct_number: Optional[str] = None
#: Extension number which will be shown if `DIRECT_LINE` is selected.
#: example: 3456
extension_number: Optional[str] = None
#: Location number which will be shown if `LOCATION_NUMBER` is selected.
#: example: 2025551212
location_number: Optional[str] = None
#: Mobile number which will be shown if `MOBILE_NUMBER` is selected.
#: example: 2025552121
mobile_number: Optional[str] = None
#: Flag to indicate if the location number is toll-free number.
toll_free_location_number: Optional[bool] = None
#: This value must be an assigned number from the virtual line's location.
#: example: 2025551212
custom_number: Optional[str] = None
#: Person's Caller ID first name. The characters `%`, `+`, ``, `"` and Unicode characters are not allowed.
#: example: Hakim
first_name: Optional[str] = None
#: Person's Caller ID last name. The characters `%`, `+`, ``, `"` and Unicode characters are not allowed.
#: example: Gonzales
last_name: Optional[str] = None
#: `true` if the virtual line's identity is blocked when receiving a transferred or forwarded call.
#: example: True
block_in_forward_calls_enabled: Optional[bool] = None
#: Designates which type of External Caller Id Name policy is used. Default is `DIRECT_LINE`.
#: example: DIRECT_LINE
external_caller_id_name_policy: Optional[ExternalCallerIdNamePolicy] = None
#: Custom External Caller Name, which will be shown if External Caller Id Name is `OTHER`.
#: example: Hakim custom
custom_external_caller_id_name: Optional[str] = None
#: Location's caller ID. This field is read-only and cannot be modified.
#: example: Hakim location
location_external_caller_id_name: Optional[str] = None
#: To set the user's main number as additional external caller ID.
additional_external_caller_id_direct_line_enabled: Optional[bool] = None
#: To set the Location main number as additional external caller ID for the user.
additional_external_caller_id_location_number_enabled: Optional[bool] = None
#: To set any phone number across location as additional external caller ID for the user.
additional_external_caller_id_custom_number: Optional[str] = None
fields_for_update: ClassVar[set[str]] = {
'selected',
'custom_number',
'first_name',
'last_name',
'external_caller_id_name_policy',
'block_in_forward_calls_enabled',
'custom_external_caller_id_name',
'location_external_caller_id_name',
'additional_external_caller_id_direct_line_enabled',
'additional_external_caller_id_custom_number'
}
def update(self) -> dict:
"""
data for update
:meta private:
"""
return self.model_dump(mode='json', exclude_none=True, by_alias=True, include=self.fields_for_update)
[docs]
class CallerIdApi(PersonSettingsApiChild):
"""
API for caller id settings
Also used for: virtual lines, workspaces
"""
feature = 'callerId'
[docs]
def read(self, entity_id: str, org_id: str = None) -> CallerId:
"""
Retrieve Caller ID Settings
Caller ID settings control how a entity’s information is displayed when making outgoing calls.
This API requires a full, user, or read-only administrator auth token with a scope of spark-admin:people_read
or a user auth token with spark:people_read scope can be used by a entity to read their settings.
:param entity_id: Unique identifier for the entity.
:type entity_id: str
:param org_id: entity 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.
:type org_id: str
"""
ep = self.f_ep(person_id=entity_id)
params = org_id and {'orgId': org_id} or None
return CallerId.model_validate(self.get(ep, params=params))