wxc_sdk.telephony.announcements_repo package

Not supported for Webex for Government (FedRAMP) Features: Announcement Repository support reading and writing of Webex Calling Announcement Repository settings for a specific organization.

class wxc_sdk.telephony.announcements_repo.RepoAnnouncement(*, id: str, name: str | None = None, fileName: str | None = None, fileSize: int | None = None, mediaFileType: MediaFileType | None = None, lastUpdated: datetime | None = None, level: AnnouncementLevel | None = None, location: IdAndName | None = None, playlists: list[IdAndName] | None = None, isTextToSpeech: bool | None = None, voice: str | None = None, language: str | None = None, text: str | None = None, featureReferenceCount: int | None = None, featureReferences: list[FeatureReference] | None = None, **extra_data: Any)[source]

Bases: IdAndName

file_name: str | None

File name of the uploaded binary announcement greeting.

file_size: int | None

Size of the file in kilobytes.

media_file_type: MediaFileType | None

Media file type of the announcement file.

last_updated: datetime | None

LastUpdated timestamp (in UTC format) of the announcement.

level: AnnouncementLevel | None

The level at which this announcement exists.

location: IdAndName | None

The details of location at which this announcement exists.

playlists: list[IdAndName] | None

list of playlists this announcement is assigned to

is_text_to_speech: bool | None

Indicates whether the announcement is text-to-speech.

voice: str | None

Voice used for text-to-speech announcement.

language: str | None

Language code for the text-to-speech announcement.

text: str | None

Text content for text-to-speech announcement.

feature_reference_count: int | None

The below is not returned by list(), only by details() Reference count of the call features this announcement is assigned to.

feature_references: list[FeatureReference] | None

Call features referenced by this announcement.

class wxc_sdk.telephony.announcements_repo.AnnouncementsRepositoryApi(*, session: RestSession, base: str = None)[source]

Bases: ApiChild

Not supported for Webex for Government (FedRAMP)

Features: Announcement Repository support reading and writing of Webex Calling Announcement Repository settings for a specific organization.

Viewing these read-only organization settings requires a full or read-only administrator auth token with a scope of spark-admin:telephony_config_read. Modifying these organization settings requires a full administrator auth token with a scope of spark-admin:telephony_config_write.

A partner administrator can retrieve or change settings in a customer’s organization using the optional orgId query parameter.

list(location_id: str = None, order: str = None, file_name: str = None, file_type: str = None, media_file_type: str = None, name: str = None, org_id: str = None, **params) → Generator[RepoAnnouncement, None, None][source]

List Announcements

Fetch a list of binary announcement greetings at an organization as well as location level.

An admin can upload a file at an organization level. This file will be uploaded to the announcement repository.

This API requires a full or read-only administrator or location administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • location_id (str) – Return the list of enterprise or Location announcement files. Without this parameter, the Enterprise level announcements are returned. Possible values: all, locations, Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzMxMTYx

  • order (str) – Sort the list according to fileName or fileSize. The default sort will be in Ascending order.

  • file_name (str) – Return the list of announcements with the given fileName.

  • file_type (str) – Return the list of announcement files for this fileType.

  • media_file_type (str) – Return the list of announcement files for this mediaFileType.

  • name (str) – Return the list of announcement files for this announcement label.

  • org_id (str) – Create an announcement in this organization.

Returns:

yields RepoAnnouncement objects

upload_announcement(name: str, file_uri: str = None, file: BufferedReader | str | None = None, is_text_to_speech: bool = None, upload_as: str = None, location_id: str = None, org_id: str = None) → str[source]

Upload a binary announcement greeting at organization or location level

Upload a binary file to the announcement repository at organization or location level.

An admin can upload a file at an organization or location level. This file will be uploaded to the announcement repository.

This API requires a full administrator auth token with a scope of spark-admin:telephony_config_write .

Parameters:

  • name (str) – The announcement file name (e.g., “greeting.wav”). This is a required field.

  • file_uri (str) – URI of the announcement file.

  • file (Union[BufferedReader, str]) – the file to be uploaded, can be a path to a file or a buffered reader (opened file); if a reader referring to an open file is passed then make sure to open the file as binary b/c otherwise the content length might be calculated wrong. Must be in WAV format

  • upload_as (str) – filename for the content. Only required if content is a reader or if using file_uri; has to be a .wav file name.

  • is_text_to_speech (bool) – Indicates whether the announcement is text-to-speech. If omitted or set to null or false, the announcement is stored as non-text-to-speech and text-to-speech metadata, such as the text, voice, and language, is not retained.

  • location_id (str) – Unique identifier of a location where an announcement is being created.

  • org_id (str) – Create an announcement in this organization.

Returns:

id of announcement

Return type:

str

Examples

# upload a local file as announcement at the org level
r = api.telephony.announcements_repo.upload_announcement(name='Sample', file='sample.wav')

# upload an announcement from an open file
# any files-like object can be used as input.
# note: the upload_as parameter is required to set the file name for the upload
with open('sample.wav', mode='rb') as wav_file:
    r = api.telephony.announcements_repo.upload_announcement(name='Sample', file=wav_file,
                                                             upload_as='sample.wav')

# upload an announcement from content in a string
with open('sample.wav', mode='rb') as wav_file:
    data = wav_file.read()

# data now is a bytes object with the file content. As we can use files-like objects as input
# it's also possible to use a BytesIO as input for upload_announcement()
binary_file = io.BytesIO(data)
r = self.api.telephony.announcements_repo.upload_announcement(name='Sample', file=binary_file,
                                                              upload_as='from_string.wav')
generate_upload_url(org_id: str = None) → GenerateUploadUrlResponse[source]

Generate Upload URL

Generate a pre-signed S3 upload URL, KMS encryption key for uploading an announcement media file. And file URI to create announcement using the media file.

To encrypt and upload the announcement media file:

  1. Download the KMS key - Use the Webex Node.js SDK and provide kmsKeyUri to download the key from KMS.

  2. Encrypt media file - Use the jose library to encrypt the raw media file with the downloaded key.

3. Upload the encrypted media file - Send a PUT request with encrypted media file to the preSignedUrl. The request must include following headers:

  • x-amz-meta-contenttype: The media MIME type, for example: audio/wav

  • x-amz-meta-kmskeyuri: The returned kmsKeyUri, for example:

kms://kms-cisco.wbx2.com/keys/b56642f3-d597-420c-8a55-41aaa8c5b6e7

  • x-amz-tagging: tmp=true

This API is part of the Announcement Repository with Media URLs feature, which optimizes the media file upload process by enabling direct S3 uploads and adds the ability to preview existing announcement audio files.

This API requires a full administrator auth token with a scope of spark-admin:telephony_config_write.

Parameters:

org_id (str) – Generate the upload URL for this organization.

Return type:

GenerateUploadUrlResponse

usage(location_id: str = None, org_id: str = None) → RepositoryUsage[source]

Fetch repository usage for announcements for an organization or location

Retrieves repository usage for announcements for an organization or location

This API requires a full or read-only administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • location_id (str) – Unique identifier of a location

  • org_id (str) – Create an announcement in this organization.

details(announcement_id: str, location_id: str = None, org_id: str = None) → RepoAnnouncement[source]

Fetch details of a binary announcement greeting at the organization or location level

Fetch details of a binary announcement greeting by its ID at an organization level.

An admin can upload a file at an organization level. This file will be uploaded to the announcement repository. This API requires a full or read-only administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • location_id (str) – Unique identifier of a location

  • announcement_id (str) – Unique identifier of an announcement.

  • org_id (str) – Get details of an announcement in this organization.

delete(announcement_id: str, location_id: str = None, org_id: str = None)[source]

Delete an announcement greeting.

This API requires a full administrator auth token with a scope of spark-admin:telephony_config_write.

Parameters:

  • announcement_id (str) – Unique identifier of an announcement.

  • location_id (str) – Unique identifier of a location where announcement is being deleted.

  • org_id (str) – Delete an announcement in this organization.

modify(announcement_id: str, name: str, file_uri: str = None, file: BufferedReader | str | None = None, upload_as: str = None, is_text_to_speech: bool = None, location_id: str = None, org_id: str = None)[source]

Modify a binary announcement greeting at organization or location level

Modify an existing announcement greeting at a organization or location level.

An admin can upload a file or modify an existing file at a location level. This file will be uploaded to the announcement repository.

Your request will need to be a multipart/form-data request rather than JSON, using the audio/wav Content-Type.

This API requires a full administrator auth token with a scope of spark-admin:telephony_config_write.

Parameters:

  • announcement_id (str) – Unique identifier of an announcement.

  • name (str) – Announcement name

  • file_uri (str) – URI of the announcement file.

  • file (Union[BufferedReader, str]) – the file to be uploaded, can be a path to a file or a buffered reader (opened file); if a reader referring to an open file is passed then make sure to open the file as binary b/c otherwise the content length might be calculated wrong

  • upload_as (str) – filename for the content. Only required if content is a reader or if using file_uri; has to be a .wav file name.

  • is_text_to_speech (bool) – Indicates whether the announcement is text-to-speech. If omitted or set to null or false, the announcement is stored as non-text-to-speech and text-to-speech metadata, such as the text, voice, and language, is not retained.

  • location_id (str) – Unique identifier of a location where announcement is being deleted.

  • org_id (str) – Modify an announcement in this organization.

get_announcement_file_uri(announcement_id: str, org_id: str = None) → str[source]

Get Announcement File URI

Retrieve the fileUri for an existing binary announcement greeting at the organization level. Use the returned fileUri with the Get Media Download URL API to get URLs for downloading the announcement media file.

This API is part of the Announcement Repository with Media URLs feature, which optimizes the media file upload process by enabling direct S3 uploads and adds the ability to preview existing announcement audio files.

This API requires a full or read-only administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • announcement_id (str) – Unique identifier of an announcement.

  • org_id (str) – Get announcement fileUri in this organization.

Return type:

str

get_location_announcement_file_uri(location_id: str, announcement_id: str, org_id: str = None) → str[source]

Get Location Announcement File URI

Retrieve the fileUri for an existing binary announcement greeting at the location level. Use the returned fileUri with the Get Media Download URL API to get URLs for downloading the announcement media file.

This API is part of the Announcement Repository with Media URLs feature, which optimizes the media file upload process by enabling direct S3 uploads and adds the ability to preview existing announcement audio files.

This API requires a full or read-only administrator or location administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • location_id (str) – Unique identifier of a location where an announcement is stored.

  • announcement_id (str) – Unique identifier of an announcement.

  • org_id (str) – Get announcement fileUri for location in this organization.

Return type:

str

get_media_download_url(s3_path: str, org_id: str = None) → GetMediaUrlResponse[source]

Get Media Download URL

Retrieve a pre-signed S3 download URL and KMS encryption key for a previously uploaded announcement media file identified by its S3 path.

To preview the announcement media file:

  1. Download the KMS key - Use the Webex Node.js SDK and provide kmsKeyUri to download the key from KMS.

2. Download the encrypted media file - The encrypted media file content is stored in cloud and can be retrieved using preSignedUrl.

3. Decrypt the media content - Use the jose library to decrypt the content downloaded from preSignedUrl using the downloaded key.

This API is part of the Announcement Repository with Media URLs feature, which optimizes the media file upload process and adds the ability to preview existing announcement audio files by generating pre-signed S3 download URLs.

This API requires a full or read-only administrator auth token with a scope of spark-admin:telephony_config_read.

Parameters:

  • s3_path (str) – The storage path of the announcement media file. Use the value after /media/urls/ in the fileUri returned by the Get Announcement File URI or Get Location Announcement File URI API. For example, if fileUri is cmf://customers/bf01164f-ed87-44d9-bc41-f63f26fb9663/media/urls/tmp/af01164f-ed87-44d9-bc41-f63f26fb8663, then s3Path is tmp/af01164f-ed87-44d9-bc41-f63f26fb8663.

  • org_id (str) – Retrieve the media download URL for this organization.

Return type:

GetMediaUrlResponse

base = 'telephony/config'
class wxc_sdk.telephony.announcements_repo.RepositoryUsage(*, totalFileSizeUsedKB: int | None = None, maxAudioFileSizeAllowedKB: int | None = None, maxVideoFileSizeAllowedKB: int | None = None, totalFileSizeLimitMB: int | None = None, **extra_data: Any)[source]

Bases: ApiModel

total_file_size_used_kb: int | None

Total file size used by announcements in this repository in kilobytes.

max_audio_file_size_allowed_kb: int | None

Maximum audio file size allowed to upload in kilobytes.

max_video_file_size_allowed_kb: int | None

Maximum video file size allowed to upload in kilobytes.

total_file_size_limit_mb: int | None

Total file size limit for the repository in megabytes.

class wxc_sdk.telephony.announcements_repo.FeatureReference(*, id: str | None = None, name: str | None = None, type: str | None = None, locationId: str | None = None, locationName: str | None = None, **extra_data: Any)[source]

Bases: ApiModel

id: str | None

Unique identifier of the call feature referenced. The call Feature can be Auto Attendant, Call Queue or Music On hold.

name: str | None

Name of the call feature referenced.

type: str | None

Resource Type of the call feature.

location_id: str | None

Unique identifier of the location.

location_name: str | None

Location name of the announcement file.

class wxc_sdk.telephony.announcements_repo.GenerateUploadUrlResponse(*, preSignedUrl: str | None = None, kmsKeyUri: str | None = None, fileUri: str | None = None, **extra_data: Any)[source]

Bases: ApiModel

pre_signed_url: str | None

A pre-signed S3 URL for uploading the announcement media file. The URL is time-limited and should be used promptly.

kms_key_uri: str | None

The KMS key URI used to encrypt the media file before uploading to the pre-signed URL.

file_uri: str | None

A file URI that identifies the uploaded media. Use this URI when configuring announcements.

class wxc_sdk.telephony.announcements_repo.GetMediaUrlResponse(*, preSignedUrl: str | None = None, kmsKeyUri: str | None = None, **extra_data: Any)[source]

Bases: ApiModel

pre_signed_url: str | None

A pre-signed S3 URL for downloading the announcement media file. The URL is time-limited and should be used promptly.

kms_key_uri: str | None

The KMS key URI required to decrypt the media file downloaded from the pre-signed URL.