This article describes how to manage images using Webex Control Hub as well as the Webex REST APIs.

anchorPrerequisites for Background Images

Before continuing, verify your Cisco device compatibility as well as your background image format and size constraints as follows:

Supported Devices

• 8800 series (all except 8875)
• 6871

Supported Image Sizes per Model

• 8811: greyscale - 480x128
• 8832: color - 480x128
• Other 8800 series: color - 800x480
• 6871: color - 480 x 272

Supported Image formats:

• PNG
• JPG

Maximum File Size

• 625 KB

anchorBackground Image REST Endpoints

Background image REST endpoints are found on the Webex Developer Portal, but can be called using Postman, or integrated into code or scripts.

Three REST endpoints exist for handling background images:

• Upload: Upload a new background image.
• List: List existing background images.
• Delete: Delete existing images.

anchorUpload Image Using the Upload REST Endpoint

The upload endpoint adds a new background image file for the entire organization to use and sets up a device to display it. After uploading, a resync request is sent to the device to display the new background image.

The upload endpoint uses a multipart/form-data request with two entries:

• name=”file” where file is the name of the image file on the uploading computer.
• name="filename" where filename is the name you want to use for the uploaded image in Webex.

Example:

Body: multipart/form-data
--aBoundaryString
Content-Disposition: form-data; name="file"; fileName=<name of file on computer> 
Content-Type: <png | jpg>
<image binary>
--aBoundaryString
Content-Disposition: form-data; name="fileName"
<name to call the uploaded image>
--aBoundaryString

API details can be found here: POST Upload Background Image

anchorList Images Using the List REST Endpoint

List the images that are uploaded and ready for use. API details can be found here: GET Background Image List

anchorDelete Images Using the Delete REST Endpoint

Use the delete endpoint to delete the list of designated device background images for an organization. You can delete a maximum of 10 images per request.

API details can be found here: DELETE Background Images.

When deleting an image keep the following points in mind:

• If forceDelete is set to false or is not specified, and the custom background URL is configured with the image being deleted at the device, location, or organization level, the request is rejected.
• If forceDelete is set to true, and the custom background URL is configured with the image being deleted at the device, location, or organization level, the background image configuration will be set to None at those levels. The change to None will be applied to devices when "Apply changes" is requested for the device, during the nightly resync, or upon reboot or power cycle of the phone. The image will still be visible on any phone that was configured until None has been applied.

anchorManage Images via Control Hub

You can easily configure uploaded images to devices at different levels using Webex Control hub.

Configure an Image URL using Control Hub at an Organization Level

To configure an image URL using Control Hub at a organization level:

1. Log in to Control Hub with your administrator credentials.
2. Navigate to the Calling section.
3. Move to the Service Settings tab.
4. Select Configure Default Device Settings.
5. Under MPP Device Settings, set the Background Image option to Custom Background.
6. Configure the URL of the file in the Custom Background URL field and save it.

Configure an image URL using Control Hub at Location Level

To configure an image URL using Control Hub at a location level:

1. Log in to Control Hub with your administrator credentials.
2. Navigate to the Location List section.
3. Select the location you want to update.
4. Move to Calling section.
5. In the Device Management card, click Manage.
6. Choose Define Custom Device Settings.
7. Under MPP Device Settings, set Background Image option to Custom Background.
8. Configure the URL of the file in the Custom Background URL field and save it.

Configure an Image URL using Control Hub at a Device Level

To configure an image URL using Control Hub at a device level:

1. Log in to Control Hub with your administrator credentials.
2. Navigate to the Devices List section.
3. Select the Device you want to update.
4. In Device Management card, click on Device Settings Manage.
5. Choose Define Custom Device Dettings.
6. Set Background Image option to Custom Background.
7. Configure the URL of the file in Custom Background URL text field and save it.

anchorManage Images Using the Developer Portal

You can easily manage background images at different levels in the Developer Portal using the associated REST APIs. Begin by logging in and grabbing your temporary developer access token for your account by navigating to the Access the Webex API page. Save the token and use it the REST API calls described in the following sections. In addition, you can also use the developer portal Try it mode to experiment with APIs as well. If you’re new to REST APIs or need a quick refresher, see REST API Basics.

Configure an Image URL Using the REST API at an Organization or Location Level

To configure an image URL using the REST API at an organization or location level see the following API entries:

• To update the background image, see POST Device Settings.
• To read configuration for a location, see GET Location Device Settings.
• To read configuration for an organization, see GET Org Device Settings.

Configure an Image URL Using the REST API at a Device Level

To configure an image URL using the REST API at a device level see the following API entries:

• To update the background image, see PUT Device Settings.
• To read the configuration, see GET Device Settings.