"""
Call recording API
"""
from typing import Any, Optional
from pydantic import Field
from ..base import ApiModel, to_camel
from ..base import SafeEnum as Enum
from .common import PersonSettingsApiChild
# mypy: disable-error-code="arg-type,call-arg"
__all__ = [
'Record',
'NotificationType',
'NotificationRepeat',
'Notification',
'CallRecordingSetting',
'StartStopAnnouncement',
'CallRecordingAccessSettings',
'PostCallRecordingSettings',
'CallRecordingAnnouncement',
'CallRecordingAnnouncements',
'CallRecordingApi',
]
from ..common import AnnAudioFile, Greeting
[docs]
class Record(str, Enum):
#: Call recording is always enabled.
always = 'Always'
#: Call recording is never enabled.
never = 'Never'
#: Call recording is started and stopped manually by the user.
on_demand = 'On Demand'
#: Call recording is always enabled with the ability to pause and resume.
always_with_pause_resume = 'Always with Pause/Resume'
#: Call recording is started manually by the user.
on_demand_with_user_initiated_start = 'On Demand with User Initiated Start'
[docs]
class NotificationType(str, Enum):
"""
Type of pause/resume notification.
"""
#: No notification sound played when call recording is paused or resumed.
none = 'None'
#: A beep sound is played when call recording is paused or resumed.
beep = 'Beep'
#: A verbal announcement is played when call recording is paused or resumed.
play_announcement = 'Play Announcement'
[docs]
class NotificationRepeat(ApiModel):
"""
Beep sound plays periodically.
"""
#: Interval at which warning tone "beep" will be played. This interval is an integer from 10 to 1800 seconds
interval: int
#: true when ongoing call recording tone will be played at the designated interval. false indicates no warning tone
# will be played
enabled: bool
[docs]
class Notification(ApiModel):
#: Type of pause/resume notification.
notification_type: Optional[NotificationType] = Field(alias='type', default=None)
#: true when the notification feature is in effect. false indicates notification is disabled.
enabled: bool
[docs]
class StartStopAnnouncement(ApiModel):
"""
Call Recording starts and stops announcement settings.
"""
#: When true, an announcement is played when call recording starts and an announcement is played when call
#: recording ends for internal calls.
internal_calls_enabled: Optional[bool] = None
#: When true, an announcement is played when call recording starts and an announcement is played when call
#: recording ends for PSTN calls.
pstn_calls_enabled: Optional[bool] = None
[docs]
class CallRecordingAccessSettings(ApiModel):
#: When `true`, the person can view and play call recordings.
view_and_play_recordings_enabled: Optional[bool] = None
#: When `true`, the person can download call recordings.
download_recordings_enabled: Optional[bool] = None
#: When `true`, the person can delete call recordings.
delete_recordings_enabled: Optional[bool] = None
#: When `true`, the person can share call recordings.
share_recordings_enabled: Optional[bool] = None
[docs]
class PostCallRecordingSettings(ApiModel):
summary_and_action_items_enabled: Optional[bool] = None
transcript_enabled: Optional[bool] = None
[docs]
class CallRecordingAnnouncement(ApiModel):
#: Type of announcement to play when call recording starts.
type: Optional[Greeting] = None
audio_announcement_file: Optional[AnnAudioFile] = None
def update(self) -> dict[str, Any]:
"""
dict for update()
:meta private:
"""
data = self.model_dump(mode='json', by_alias=True, exclude_unset=True)
# update only has announcement file ID
if self.audio_announcement_file:
data.pop('audioAnnouncementFile')
data['audioAnnouncementFileId'] = self.audio_announcement_file.id
return data
[docs]
class CallRecordingAnnouncements(ApiModel):
#: When `true`, the location level custom announcement settings are used. When `false`, queue custom announcement
#: settings are used.
use_location_level_enabled: Optional[bool] = None
#: The start announcement settings for this queue.
start: Optional[CallRecordingAnnouncement] = None
#: The stop announcement settings for this queue.
stop: Optional[CallRecordingAnnouncement] = None
#: The pause announcement settings for this queue.
pause: Optional[CallRecordingAnnouncement] = None
#: The resume announcement settings for this queue.
resume: Optional[CallRecordingAnnouncement] = None
#: The failure end with call announcement settings for this queue.
failure_end_with_call: Optional[CallRecordingAnnouncement] = None
#: The failure proceed with call announcement settings for this queue.
failure_proceed_with_call: Optional[CallRecordingAnnouncement] = None
def update(self) -> dict[str, Any]:
"""
dict for update()
:meta private:
"""
data = self.model_dump(mode='json', by_alias=True, exclude_unset=True)
for attr in ['start', 'stop', 'pause', 'resume', 'failure_end_with_call', 'failure_proceed_with_call']:
if v := getattr(self, attr):
data[to_camel(attr)] = v.update()
return data
[docs]
class CallRecordingSetting(ApiModel):
#: true if call recording is enabled.
enabled: Optional[bool] = None
#: Specified under which scenarios calls will be recorded.
record: Optional[Record] = None
#: When true, voicemail messages are also recorded.
record_voicemail_enabled: Optional[bool] = None
#: When enabled, an announcement is played when call recording starts and an announcement is played when call
#: recording ends.
start_stop_announcement_enabled: Optional[bool] = None
#: Pause/resume notification settings.
notification: Optional[Notification] = None
#: Beep sound plays periodically.
repeat: Optional[NotificationRepeat] = None
#: Name of the service provider providing call recording service.
service_provider: Optional[str] = None
#: Group utilized by the service provider providing call recording service
external_group: Optional[str] = None
#: Unique person identifier utilized by the service provider providing call recording service.
external_identifier: Optional[str] = None
#: Call Recording starts and stops announcement settings.
start_stop_announcement: Optional[StartStopAnnouncement] = None
#: Settings related to call recording access.
call_recording_access_settings: Optional[CallRecordingAccessSettings] = None
#: TODO: undocumented, issue 201
post_call_recording_settings: Optional[PostCallRecordingSettings] = None
#: Announcement settings
announcements: Optional[CallRecordingAnnouncements] = None
[docs]
@staticmethod
def default() -> 'CallRecordingSetting':
"""
Default settings for a user
"""
return CallRecordingSetting(
enabled=False,
record=Record.never,
record_voicemail_enabled=False,
start_stop_announcement_enabled=False,
notification=Notification(notification_type=NotificationType.none, enabled=False),
repeat=NotificationRepeat(interval=15, enabled=False),
start_stop_announcement=StartStopAnnouncement(internal_calls_enabled=False, pstn_calls_enabled=False),
)
def update(self) -> dict[str, Any]:
"""
date for update
:meta private:
"""
data = self.model_dump(
mode='json',
exclude_unset=True,
by_alias=True,
exclude={'service_provider', 'external_group', 'external_identifier'},
)
if self.notification and self.notification.notification_type == NotificationType.none:
# Read on API returns "None" but update has to be null
data['notification']['type'] = None
# special data for announcements update
if self.announcements:
data['announcements'] = self.announcements.update()
return data
[docs]
class CallRecordingApi(PersonSettingsApiChild):
"""
API for recording settings
Also used for virtual lines, workspaces
"""
feature = 'callRecording'
[docs]
def read(self, entity_id: str, org_id: str = None) -> CallRecordingSetting:
"""
Read Call Recording Settings
Retrieve Call Recording Settings
The Call Recording feature provides a hosted mechanism to record the calls placed and received on the Carrier
platform for replay and archival. This feature is helpful for quality assurance, security, training, and more.
This API requires a full or user administrator auth token with the spark-admin:people_write scope.
: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 CallRecordingSetting.model_validate(self.get(ep, params=params))