Getting Started with the Converged Recordings APIs for Webex Calling

The Webex Calling product recently added the option to have “Webex” be the call recording provider for an organization, alongside the previous set of third-party call recording partners. When selecting Webex as the call recording provider, it utilizes the same mechanism as Webex Meeting recordings to output high quality audio files. Webex call recording is accessible to all users in a Calling organization and provides unlimited recording capabilities. Currently, Webex recordings have a retention period of one year, with each organization allotted 100GB of storage. Another great feature of Webex call recordings is the ability to receive AI-generated summaries, where you can quickly catch up on a discussion and get a better understanding of the conversation at a glance.

The Webex call recording option also gives developers access to a new set of APIs to automate the management of call recordings in Webex Calling – Converged Recordings APIs. These endpoints can be used for integrations that automate the archival of older recordings for long-term storage, satisfy compliance archival requirements, dynamically link conversations to customer profiles in a CRM, generate custom reports based on call recording metadata, route flagged recordings for supervisor review, and more.

In this article, we will first show how the Webex Call Recording option is selected in Control Hub. Then we will explore the new Converged Recordings API endpoints and explain how they work for different Webex user roles.

Webex Call Recording in a Developer Sandbox

The first step to start using the Converged Recordings APIs is for an admin to enable Webex as the call recording provider for the organization. This is where a Webex Developer Sandbox comes in handy, which provides administrator-level access to your own Webex organization. The instructions to enable Webex as the recording provider in Control Hub are rather straightforward:

1. Once you have access to a Developer Sandbox, log in to Control Hub with your admin credentials.
2. Go to Services > Calling > Service Settings.
3. Under Call Recording, select “Webex” as the call recording provider from the drop-down list.
4. Click “Save”.

• For the most up to date instructions on enabling Webex call recording at an organizational level, see these instructions.
• To configure your sandbox for call transcriptions (currently available only in the Webex app) and AI-generated summaries that includes Notes and Action Items (available on both the Webex app and Converged Recordings APIs), see the instructions here.

Since the developer sandboxes do not include public telephone access in Webex Calling, the easiest way to make test calls is by utilizing “extension dialing”.  This allows calling between test users without the need for setting up a paid PSTN number. In this scenario, the calls are supported by Webex and not through the public telephone network. Test users can essentially be assigned any number string as a dialable extension. A test user can dial another user’s extensions, answer incoming calls, and execute in-call actions (including recording) inside the Webex app or by leveraging the Call Control APIs.

• For instructions on setting up extension dialing on a developer sandbox, watch this helpful Vidcast.
• To get more familiarized with the Call Control APIs, check out my previous blog on this subject.

Exploring the Converged Recordings APIs

While the Webex Meetings and Calling products can share the same method of recording when Webex is selected as the call recording provider, the Recording APIs are still the exclusive to Meetings and Converged Recordings APIs are exclusive to Calling. In the future, Meeting Recordings will also be included in the Converged Recordings APIs. Until then, both sets of APIs do share the same basic schema that makes it easy to transition from one endpoint to the other.

In this section, we’ll break down the functionality for the Converged Recordings APIs based on specific roles in Webex.

User Level APIs

Integrations for regular Webex users have access to the following Converged Recordings APIs:

• List Recordings – required scope is spark:recordings_read

  • This endpoint is usually the first API call used to retrieve the ID that corresponds to a specific recording that is required for subsequent API calls. This API also returns some general data about the file and the available status of the file. If the status is specified as deleted, the recording has been moved to the recycle bin.

• Get Recording Details – required scope is spark:recordings_read

  • This endpoint requires the recordingID that is retrieved from the List Recordings API noted priorly. This returns the unique download links for the call recordings, AI-generated summaries (action items, suggested notes, and short notes), along with other data of the recording file.

• Get Recording metadata API – required scope is spark:recordings_read

  • This endpoint requires a recordingID to retrieve the metadata of the recording file which contains much more details of the recording, including sensitive data such as phone numbers. If the query parameter showAllTypes is true, the additional details about mediaStreams, participants, redirectInfo and redirectedCall are included in the response body.

• Move Recordings into the Recycle Bin – required scope is spark:recordings_write

  • This endpoint requires a recordingID to move individual recordings to the recycle bin (soft delete). To move all recordings of the user to the recycle bin, the trashAll parameter that is set to true can be added to the request body and no recordingIDis required.

• Purge Recordings from Recycle Bin – required scope is spark:recordings_write

  • This endpoint requires a recordingID that has a status specified as deleted to purge individual recordings from the recycle bin (hard delete). To purge all recordings of the user from the recycle bin, the purgeAll parameter that is set to true can be added to the request body and no recordingIDis required. Recordings are fully purged from the recycle bin only after the 30-day retention policy is met and cannot be restored after that. During the retention period, an admin or compliance officer can still restore recordings purged by the user.

• Restore Recordings from Recycle Bin – required scope is spark:recordings_write

  • This endpoint requires a recordingID that has a status specified as deleted to restore individual recordings from the recycle bin. To restore all recordings of the user from the recycle bin, the restoreAll parameter set to true can be added to the request body and no recordingIDis required.

Administrator and Compliance Officer Level APIs

Integrations for Webex administrators and compliance officers have access to larger set of Converged Recordings APIs, some of which are exclusive to either role:

• List Recordings for Admin or Compliance Officer – required scope for admin is spark-admin:recordings_read, required scope for compliance officer is spark-compliance:recordings_read

  • This endpoint works much like the List Recordings API for users to retrieve the recordingID for each file, except there are a variety of extra query parameters to filter by specific owners, dates, locations, etc.

• Get Recording Details – required scope for admin is spark-admin:recordings_read, required scope for compliance officer is spark-compliance:recordings_read

  • This endpoint requires the recordingID that is retrieved from the List Recordings for Admin or Compliance Officer API noted priorly. This returns the unique download links along with other data of the recording file.

• Get Recording metadata API – required scope for admin is spark-admin:recordings_read, required scope for compliance officer is spark-compliance:recordings_read

  • Just like the user level scope, this endpoint requires a recordingID to retrieve the metadata of the recording file which contains much more details of the recording, including PII data. If the query parameter showAllTypes is true, the additional details about mediaStreams, participants, redirectInfo and redirectedCall are included in the response body.

• Move Recordings into the Recycle Bin – required scope for admin is spark-admin:recordings_write

  • Just like the user level scope, this endpoint requires a recordingID to move individual recordings to the recycle bin (soft delete). To move all recordings of the user to the recycle bin, the trashAll parameter that is set to true can be added to the request body. In this case, an ownerEmail is now required and a recordingIDis not.

• Purge Recordings from Recycle Bin – required scope for admin is spark-admin:recordings_write

  • Just like the user level scope, this endpoint requires a recordingID that has a status specified as deleted to purge individual recordings from the recycle bin (hard delete). To purge all recordings of the user from the recycle bin, the purgeAll parameter that is set to true can be added to the request body. In this case, an ownerEmail is now required and a recordingIDis not. Recordings are fully purged from the recycle bin only after the 30-day retention policy is met and cannot be restored after that. See the Compliance Guide for more information on recording file retention policy.

• Restore Recordings from Recycle Bin – required scope for admin is spark-admin:recordings_write

  • Just like the user level scope, this endpoint requires a recordingID that has a status specified as deleted to restore individual recordings from the recycle bin. To restore all recordings of the user from the recycle bin, the restoreAll parameter that is set to true can be added to the request body. In this case, an ownerEmail is now required and a recordingIDis not.

• Reassign Recordings – required scope is spark-admin:recordings_write

  • This endpoint is exclusive toadministrators and requires two parameters: reassignOwnerEmail for the account the recordings will be moved into, and recordingIds which accepts a list of one or more recordingID values that specify the files to be reassigned.

• Delete a Recording – required scope is spark-compliance:recordings_write

  • This endpoint is exclusive to compliance officers and requires a recordingID to permanently delete a call recording. Once a recording is deleted by a compliance officer, it becomes inaccessible no matter the user role and purged from Webex altogether.

Need Some More Help? We’ve Got You Covered

We are excited to provide support for these new APIs and eager to see some of the outcomes from our developer community! As always, the Webex Developer Support Team is standing by and happy to assist if you gave any questions or need help. You can also start or join a conversation on the Webex for Developers Community Forum. Until next time, happy developing!