Getting Started with the Converged Recordings APIs for Webex Calling
May 21, 2025

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:
- Once you have access to a Developer Sandbox, log in to Control Hub with your admin credentials.
- Go to Services > Calling > Service Settings.
- Under Call Recording, select “Webex” as the call recording provider from the drop-down list.
- 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 availablestatus
of the file. If thestatus
is specified asdeleted
, the recording has been moved to the recycle bin.
- This endpoint is usually the first API call used to retrieve the
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.
- This endpoint requires the
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 istrue
, the additional details aboutmediaStreams
,participants
,redirectInfo
andredirectedCall
are included in the response body.
- This endpoint requires a
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, thetrashAll
parameter that is set totrue
can be added to the request body and norecordingID
is required.
- This endpoint requires a
Purge Recordings from Recycle Bin – required scope is
spark:recordings_write
- This endpoint requires a
recordingID
that has astatus
specified asdeleted
to purge individual recordings from the recycle bin (hard delete). To purge all recordings of the user from the recycle bin, thepurgeAll
parameter that is set totrue
can be added to the request body and norecordingID
is 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.
- This endpoint requires a
Restore Recordings from Recycle Bin – required scope is
spark:recordings_write
- This endpoint requires a
recordingID
that has astatus
specified asdeleted
to restore individual recordings from the recycle bin. To restore all recordings of the user from the recycle bin, therestoreAll
parameter set totrue
can be added to the request body and norecordingID
is required.
- This endpoint requires a
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 isspark-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.
- This endpoint works much like the List Recordings API for users to retrieve the
Get Recording Details – required scope for admin is
spark-admin:recordings_read
, required scope for compliance officer isspark-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.
- This endpoint requires the
Get Recording metadata API – required scope for admin is
spark-admin:recordings_read
, required scope for compliance officer isspark-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 aboutmediaStreams
,participants
,redirectInfo
andredirectedCall
are included in the response body.
- Just like the user level scope, this endpoint requires a
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, thetrashAll
parameter that is set totrue
can be added to the request body. In this case, anownerEmail
is now required and arecordingID
is not.
- Just like the user level scope, this endpoint requires a
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 astatus
specified asdeleted
to purge individual recordings from the recycle bin (hard delete). To purge all recordings of the user from the recycle bin, thepurgeAll
parameter that is set totrue
can be added to the request body. In this case, anownerEmail
is now required and arecordingID
is 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.
- Just like the user level scope, this endpoint requires a
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 astatus
specified asdeleted
to restore individual recordings from the recycle bin. To restore all recordings of the user from the recycle bin, therestoreAll
parameter that is set totrue
can be added to the request body. In this case, anownerEmail
is now required and arecordingID
is not.
- Just like the user level scope, this endpoint requires a
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, andrecordingIds
which accepts a list of one or morerecordingID
values that specify the files to be reassigned.
- This endpoint is exclusive toadministrators and requires two parameters:
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.
- This endpoint is exclusive to compliance officers and requires a
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!