wxc_sdk.devices package

Devices represent cloud-registered Webex RoomOS devices and Webex Calling phones.

class wxc_sdk.devices.DevicesApi(*, session: RestSession)[source]

Bases: ApiChild

Devices

Devices represent cloud-registered Webex RoomOS devices and Webex Calling phones. Devices may be associated with Workspaces.

The following scopes are required for performing the specified actions:

  • Searching and viewing details for devices requires an auth token with the spark:devices_read scope.

  • Updating or deleting your devices requires an auth token with the spark:devices_write scope.

  • Viewing the list of all devices in an organization requires an administrator auth token with the spark-admin:devices_read scope.

  • Adding, updating, or deleting all devices in an organization requires an administrator auth token with the spark-admin:devices_write scope.

  • Generating an activation code requires an auth token with the spark-admin:devices_write scope, and one of the identity:placeonetimepassword_create or identity:one_time_password scopes.

These APIs cannot be used with Cisco 98xx devices that are not yet Webex Aware. Use Webex Control Hub to manage these devices.

__init__(*, session: RestSession)[source]
settings_jobs: DeviceSettingsJobsApi

device jobs Api

list(person_id: str = None, workspace_id: str = None, location_id: str = None, workspace_location_id: str = None, display_name: str = None, product: str = None, product_type: ProductType = None, tag: str = None, connection_status: ConnectionStatus = None, serial: str = None, software: str = None, upgrade_channel: str = None, error_code: str = None, capability: str = None, permission: str = None, mac: str = None, device_platform: DevicePlatform = None, planned_maintenance: MaintenanceMode = None, org_id: str = None, **params) → Generator[Device, None, None][source]

List Devices

Lists all active Webex devices associated with the authenticated user, such as devices activated in personal mode. Administrators can list all devices within an organization.

Parameters:

  • person_id (str) – List devices by person ID.

  • workspace_id (str) – List devices by workspace ID.

  • location_id (str) – List devices by location ID.

  • workspace_location_id (str) – List devices by workspace location ID. Deprecated, prefer location_id.

  • display_name (str) – List devices with this display name.

  • product (str) – List devices with this product name.

  • product_type (str) – List devices with this type. Possible values: roomdesk, phone, accessory, webexgo, unknown

  • tag (str separating the tag values or adding several tag parameters.) – List devices which have a tag. Searching for multiple tags (logical AND) can be done by comma

  • connection_status (str) – List devices with this connection statu

  • serial (str) – List devices with this serial number.

  • software (str) – List devices with this software version.

  • upgrade_channel (str) – List devices with this upgrade channel.

  • error_code (str) – List devices with this error code.

  • capability (str) – List devices with this capability. For example: xapi

  • permission (str) – List devices with this permission.

  • mac (str) – List devices with this MAC address.

  • device_platform (DevicePlatform) – List devices with this device platform.

  • org_id (str) – List devices in this organization. Only admin users of another organization (such as partners) may use this parameter.

  • planned_maintenance (MaintenanceMode) – List devices with this planned maintenance.

Returns:

Generator yielding Device instances

details(device_id: str, org_id: str = None) → Device[source]

Get Device Details Shows details for a device, by ID.

Specify the device ID in the deviceId parameter in the URI.

Parameters:

  • device_id (str) – A unique identifier for the device.

  • org_id (str)

Returns:

Device details

Return type:

Device

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

Delete a Device

Deletes a device, by ID.

Specify the device ID in the deviceId parameter in the URI.

Parameters:

  • device_id (str) – A unique identifier for the device.

  • org_id (str)

modify_device_tags(device_id: str, op: TagOp, value: list[str] = None, org_id: str = None) → Device[source]

Modify Device Tags

Update requests use JSON Patch syntax.

Parameters:

  • device_id (str) – A unique identifier for the device.

  • op (TagOp) – tag operation

  • value (list[str]) – list of tags

  • org_id (str)

Returns:

device details

Return type:

Device

activation_code(workspace_id: str = None, person_id: str = None, model: str = None, org_id: str = None) → ActivationCodeResponse[source]

Create a Device Activation Code

Generate an activation code for a device in a specific workspace by workspaceId or for a person by personId. This requires an auth token with the spark-admin:devices_write scope, and either identity:placeonetimepassword_create (allows creating activation codes for workspaces only) or identity:one_time_password (allows creating activation codes for workspaces or persons).

  • Adding a device to a workspace with calling type none or thirdPartySipCalling will reset the workspace calling type to freeCalling.

  • Either workspaceId or personId should be provided. If both are supplied, the request will be invalid.

  • If no model is supplied, the code returned will only be accepted on RoomOS devices.

  • If your device is a phone, you must provide the model as a field. You can get the model from the supported devices API.

Adding a device to a person with a Webex Calling Standard license will disable Webex Calling across their Webex mobile, tablet, desktop, and browser applications.

When adding devices to a Webex Calling Professional licensed person or workspace, wait for each API call to finish before starting the next. This prevents race conditions that can cause errors when assigning primary versus secondary device status.

Parameters:

  • workspace_id (str) – The ID of the workspace where the device will be activated.

  • person_id (str) – The ID of the person who will own the device once activated.

  • model (str) – The model of the device being created.

  • org_id (str) – The organization associated with the activation code generated.

Return type:

ActivationCodeResponse

base = 'devices'
create_by_mac_address(mac: str, workspace_id: str = None, person_id: str = None, model: str = None, password: str = None, org_id: str = None) → Device | None[source]

Create a Device by MAC Address

CCreate a phone by its MAC address in a specific workspace or for a person.

Specify the mac, model and either workspaceId or personId.

  • You can get the model from the `supported devices

<https://developer.webex.com/docs/api/v1/device-call-settings/read-the-list-of-supported-devices>`_ API.

  • Either workspaceId or personId should be provided. If both are supplied, the request will be invalid.

  • The password field is only required for third party devices. You can obtain the required third party phone

configuration from here.

Adding a device to a person with a Webex Calling Standard license will disable Webex Calling across their Webex mobile, tablet, desktop, and browser applications.

When adding devices to a Webex Calling Professional licensed person or workspace, wait for each API call to finish before starting the next. This prevents race conditions that can cause errors when assigning primary versus secondary device status.

Parameters:

  • mac (str) – The MAC address of the device being created.

  • workspace_id (str) – The ID of the workspace where the device will be activated.

  • person_id (str) – The ID of the person who will own the device once activated.

  • model (str) – The model of the device being created.

  • password (str) – SIP password to be configured for the phone, only required with third party devices.

  • org_id (str) – The organization associated with the device.

Returns:

created device information

Return type:

Device

class wxc_sdk.devices.Device(*, id: str, callingDeviceId: str | None = None, webexDeviceId: str | None = None, displayName: str, workspaceId: str | None = None, personId: str | None = None, orgId: str, capabilities: list[str], permissions: list[str], connectionStatus: ConnectionStatus | None = None, product: str, type: ProductType, tags: list[str], ip: str | None = None, activeInterface: str | None = None, mac: str | None = None, primarySipUrl: str | None = None, sipUrls: list[Any], errorCodes: list[Any] | None = None, serial: str | None = None, software: str | None = None, upgradeChannel: str | None = None, created: datetime | None = None, locationId: str | None = None, workspaceLocationId: str | None = None, firstSeen: datetime | None = None, lastSeen: datetime | None = None, managedBy: DeviceManagedBy | None = None, manufacturer: str | None = None, linePort: str | None = None, outboundProxy: str | None = None, sipUserName: str | None = None, devicePlatform: DevicePlatform | None = None, lifecycle: Lifecycle | None = None, plannedMaintenance: MaintenanceMode | None = None, **extra_data: Any)[source]

Bases: ApiModel

device_id: str

A unique identifier for the device.

calling_device_id: str | None

A unique identifier for the device specifically for use with Webex Calling APIs.

webex_device_id: str | None

A unique identifier for the device specifically for use with Webex Devices APIs.

display_name: str

A friendly name for the device.

workspace_id: str | None

The workspace associated with the device.

person_id: str | None

The person associated with the device.

org_id: str

The organization associated with the device

capabilities: list[str]

The capabilities of the device.

permissions: list[str]

The permissions the user has for this device. For example, xapi means this user is entitled to using the xapi against this device.

connection_status: ConnectionStatus | None

The connection status of the device.

product: str

The product name. A display friendly version of the device’s model.

product_type: ProductType

The product type.

tags: list[str]

Tags assigned to the device.

ip: str | None

The current IP address of the device.

active_interface: str | None

The current network connectivity for the device.

mac: str | None

The unique address for the network adapter.

primary_sip_url: str | None

The primary SIP address to dial this device.

sip_urls: list[Any]

All SIP addresses to dial this device.

error_codes: list[Any] | None
serial: str | None

Serial number for the device.

software: str | None

The operating system name data and version tag.

upgrade_channel: str | None

The upgrade channel the device is assigned to.

created: datetime | None

The date and time that the device was registered, in ISO8601 format.

location_id: str | None

The location associated with the device.

workspace_location_id: str | None

The workspace location associated with the device.

first_seen: datetime | None

The date and time that the device was first seen, in ISO8601 format.

last_seen: datetime | None

The date and time that the device was last seen, in ISO8601 format.

managed_by: DeviceManagedBy | None

Entity managing the device configuration.

manufacturer: str | None

Manufacturer of the device only for 3rd party devices

line_port: str | None

The Line/Port identifies a device endpoint in standalone mode or a SIP URI public identity in IMS mode only for 3rd party devices

outbound_proxy: str | None

Contains the body of the HTTP response received following the request to the Console API Not set if the response has no body only for 3rd party devices

sip_user_name: str | None

SIP authentication user ame for the owner of the device only for 3rd party devices

device_platform: DevicePlatform | None

The device platform.

lifecycle: Lifecycle | None

undocumented, WXCAPIBULK-719

Type:

TODO

planned_maintenance: MaintenanceMode | None
class wxc_sdk.devices.TagOp(*values)[source]

Bases: str, SafeEnum

An enumeration.

add = 'add'
remove = 'remove'
replace = 'replace'
class wxc_sdk.devices.ActivationCodeResponse(*, code: str, expiryTime: datetime, **extra_data: Any)[source]

Bases: ApiModel

code: str

The activation code.

expiry_time: datetime

The date and time the activation code expires.

class wxc_sdk.devices.ProductType(*values)[source]

Bases: str, SafeEnum

An enumeration.

phone = 'phone'
roomdesk = 'roomdesk'
class wxc_sdk.devices.ConnectionStatus(*values)[source]

Bases: str, SafeEnum

An enumeration.

connected = 'connected'
disconnected = 'disconnected'
connected_with_issues = 'connected_with_issues'
offline_expired = 'offline_expired'
activating = 'activating'
unknown = 'unknown'
offline_deep_sleep = 'offline_deep_sleep'
class wxc_sdk.devices.Lifecycle(*values)[source]

Bases: str, SafeEnum

An enumeration.

unknown = 'UNKNOWN'
active = 'ACTIVE'
end_of_sale = 'END_OF_SALE'
end_of_maintenance = 'END_OF_MAINTENANCE'
end_of_service = 'END_OF_SERVICE'
upcoming_end_of_support = 'UPCOMING_END_OF_SUPPORT'
end_of_support = 'END_OF_SUPPORT'