Importing external call recordings into Genesys Cloud EX: a practical guide

Picture a quality lead at 08:30 on a Monday. Her agents take their calls on an established contact centre platform that the business is not ready to replace, and the recordings sit in that platform's recorder. The organisation has chosen Genesys Cloud for workforce engagement: forecasting and scheduling, coaching, gamification, quality evaluation. Her question is simple. Can she open a Genesys Cloud evaluation form against last Friday's calls, when Genesys Cloud never carried them?

The answer is yes, through Genesys Cloud EX. Genesys describes EX as a separate base licence from Genesys Cloud CX: a Genesys Cloud package that does not include voice, email or digital interaction handling, but gives users the Workforce Engagement Management capabilities on voice interactions handled on an external platform. The platform itself keeps routing and recording the calls. An integration application synchronises the people, the configuration, the agent states and the interactions into the EX organisation, and uploads the voice recordings, so the quality lead evaluates them in Genesys Cloud as she would any other interaction.

When we first wrote about this in June 2023, recording upload had just arrived for EX organisations. It has matured since. Interaction synchronisation now covers voice and email, and Genesys lists interaction recording, quality management, web surveys and speech and text analytics among the EX capabilities. Recording upload itself remains voice only: Genesys does not support screen recordings or recordings of digital interactions. This guide is our current, evergreen view of how to do it well.

Genesys is clear about the division of labour: Genesys Cloud provides the interface, and an external integration application performs the synchronisation and decides the scope and mapping of the data. Configuration comes first, in two steps. An initial sync imports the existing external configuration once; an ongoing sync updates Genesys Cloud whenever the external configuration changes. The objects are users and person information, ACD skills and languages, divisions, queues, wrap-up codes and secondary statuses. Genesys recommends that deletions are not performed systematically by the integration: delete on the external platform first, then remove the object in Genesys Cloud through the UI.

Agent state follows. Presence says whether an agent is available; routing status reflects their work mode, such as On Queue, Communicating, Idle, Not Responding or Offline. Both are injected continuously, because workforce management adherence and performance views depend on them, and the external platform is the source of truth. Then come the interactions. Every external voice or email interaction is injected as a Genesys Cloud conversation and must carry an external source platform, so users can reference and tell external interactions apart. Only when a conversation exists does a recording have something to belong to.

The EX permission set mirrors this design. Alongside the familiar quality management and recording permissions, Genesys lists injection permissions: Conversation > Conversation > Inject, Presence > User Presence > Inject, Routing > Routing Status > Inject, and Recording > Recording > Upload, with Recording > Upload Report > Add and View for checking what arrived. That list is the starting point for a least-privilege role for the integration's OAuth client.

The upload pattern is best seen in Genesys's own EX Engage Connector, which injects recordings from Genesys Engage contact centres through the public EX API. Its recording provider takes one recorded segment of a call, encrypts the audio with the Genesys Cloud public key that it pulls periodically through the Public API, and builds a ZIP archive holding the encrypted audio file and a JSON file of metadata. It then asks the Public API for a pre-signed upload URL and uploads the archive to an S3 bucket with it. One segment, one archive, one upload: that granularity matters when a call has several agent legs.

The Public API call is POST /api/v2/uploads/recordings, which needs the recording:recording:upload permission. The request takes the file name, an optional Content-MD5, a content type, an optional AES256 server-side encryption flag and a validity period for the URL of between 1 and 604,800 seconds, defaulting to 600. The response returns the URL to PUT the file to, an upload key identifying the file, and the headers that the PUT must carry. Afterwards, POST /api/v2/recording/uploads/reports creates an upload status report for uploads since a given date, optionally filtered by status: Pending, Success, Failure or WaitForConversation. As its name suggests, that last status is the one to watch when recordings can arrive before their conversations are injected.

Illustrative request body for POST /api/v2/uploads/recordings

{
  "fileName": "segment-0001.zip",
  "contentType": "application/zip",
  "contentMd5": "<base64 MD5 of the archive>",
  "serverSideEncryption": "AES256",
  "signedUrlTimeoutSeconds": 600
}

Illustrative request body for POST /api/v2/recording/uploads/reports

{
  "dateSince": "2026-10-05T00:00:00.000Z",
  "uploadStatus": "Failure"
}

Most failed imports are mapping failures, not transport failures. A recording is only useful in Genesys Cloud if it lands on the right conversation, against the right agent, at the right time. That means the identifiers in the recording metadata must agree with what the integration injected as conversation events, and the users those events reference must already exist through configuration synchronisation. If the external platform knows an agent by a login and Genesys Cloud by a user ID, the mapping table between the two is a first-class design artefact, versioned and tested, not a lookup buried in code.

Time is the second trap. Segment start and end times, call start and end, and the agent's routing status at each moment come from different systems with different clocks and, often, different time zones. We agree one convention, UTC ISO-8601 timestamps in the payloads, and prove it with calls that cross midnight and a daylight saving change. Participants come third: a call with a consult and a transfer produces several agent segments, and each needs its own recording metadata so that an evaluator scoring the second agent hears the second agent.

Media is the fourth. Genesys notes that speech analytics on a recording needs higher-quality audio than a recording kept only for archive, and the Developer Center sets out the standard. The Engage Connector produces its recordings in Opus format. If the legacy recorder stores compressed mono audio, we test transcription quality on a sample before committing to analytics on the full estate, rather than discovering the limitation after the migration.

Recordings are personal data, and an import route is a new path for them, so we design it as carefully as the recorder itself. The audio is encrypted before it leaves the customer environment, with the Genesys Cloud public key fetched through the API, and the archive travels only to a pre-signed URL with a short validity period. Genesys Cloud protects recordings with encryption keys unique to each organisation. The integration's OAuth client gets a role holding only the injection, upload and upload report permissions it needs, and nothing that lets it read, play or delete recordings.

Retention needs the same deliberate choice it would on a native platform. Genesys Cloud lets authorised users modify a recording's archive or delete date, and the Public API exposes the retention records on a recording at PUT /api/v2/conversations/{conversationId}/recordings/{recordingId}. The EX permission set includes retention policy and recording deletion protection permissions. Deletion protection is how Genesys Cloud supports a legal hold directive: it prevents manual deletion and overrides policy deletion dates while it is in place, the Recording Audit trail captures protection events, and up to 1,000 conversations can be protected per organisation.

Genesys documents deletion protection for policy-based recordings, so we never assume it behaves identically for imported ones. Before go-live, our test pack protects an imported conversation, attempts a deletion, releases the protection and confirms the retention outcome, with the evidence filed in the test completion report. The legacy recorder's own retention rules are mapped too, so a recording does not outlive its lawful basis simply because it moved platforms.

For many organisations the real prize is analytics. Genesys lists speech and text analytics among the Genesys Cloud EX capabilities, with insights such as agent empathy, customer sentiment and topic trends. The Engage Connector documentation shows how analysis is requested for an injected recording: the connector inserts a speech and text analytics program ID and the recording language into the recording metadata. It requests analysis only when transcription is enabled for the organisation and on the queue, takes the program assigned to the queue that delivered the call, and falls back to the organisation's default program.

That pattern translates directly to any external platform. Programs and topics should be designed per line of business before the first recording arrives, because a technical support call and a wealth advisory call need different topics and possibly different languages. The language on each segment must be a code that Genesys Cloud supports for transcription, and the queue that delivered the call must be synchronised and mapped, so the right program is chosen. Done well, the quality lead from 08:30 can search transcripts and filter by topic across calls that Genesys never carried.

We start in Discover with the facts: which platform, which recorder, the volume of recordings per day, their format, how segments relate to calls, and what the business wants to do with them. In Define, our Senior Business Consultant turns that into requirements with acceptance criteria, including the awkward ones: transfers, consults, recordings without calls and calls without recordings. In Design, the Solution Architect records the synchronisation scope, the identity mapping, the metadata contract and the security model in the High-Level Design and an Interface Control Document, so every later change has something to be checked against.

Build follows the Senior Platform Practice Lead's engineering standards: retries with back-off within the API budget, idempotent uploads keyed on the segment, and a daily reconciliation that compares what the recorder produced with what the upload status report says arrived. Our Systems Integration Tester proves the failure paths deliberately: an expired upload URL, a recording before its conversation, an unknown agent, a corrupt archive and a duplicate upload. Training covers evaluators and supervisors, all delivered remotely unless agreed otherwise.

Scope matters as well. Genesys documents recording upload as a Genesys Cloud EX capability, and EX is a separate base licence from Genesys Cloud CX. An organisation moving its calls onto Genesys Cloud CX therefore plans its historical recordings as a separate workstream, with retrieval and retention kept in the legacy archive or an approved store, while new calls are recorded natively. Where EX is the bridge, a smaller synchronisation scope makes a sensible pilot, and the same integration can grow line of business by line of business.