> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Genesys Cloud integration

> Connect Genesys Cloud to Operata and get real-time CX observability over every Conversation — quality signals, analytics, and insights in one place.

Connect Genesys Cloud to Operata and get real-time visibility over every Conversation — whether a human agent or an AI agent handled it — so you can see why call quality, routing outcomes, and customer results are what they are. Operata is CX observability for cloud contact centers.

The integration runs without touching call audio or agent desktops. Genesys Cloud streams analytics and platform events to Operata via Amazon EventBridge (the primary ingestion path), and a read-only OAuth client lets Operata fetch the canonical Conversation Detail record on each conversation end. Operata stitches those signals into observations, derives insights, and surfaces them in the Operata console and over the API.

The Genesys Cloud integration shares the redaction model with the [Cloud Collector](/docs/concepts-cloud-collector) on Amazon Connect — field-level deny policies you define apply consistently across both platforms.

## How it works

Operata reads Genesys Cloud through two channels.

* **Amazon EventBridge** is the primary ingestion path. Genesys Cloud publishes analytics, operational, and platform events to an EventBridge event bus in Operata's AWS account. Amazon EventBridge rules forward the events to the Operata ingestion endpoint over HTTPS.
* **Genesys Cloud REST APIs** provide the enrichment path. On conversation end, Operata calls a small set of read-only endpoints to fetch the canonical Conversation Detail record and any optional enrichment data you have enabled.

Operata does not access call audio, agent desktops, or screen recordings. The integration uses OAuth 2.0 client credentials with least-privilege scopes; you can revoke access from the Genesys Cloud admin console at any time.

```mermaid theme={null}
flowchart LR
    G[Genesys Cloud] -->|EventBridge| B[Operata event bus]
    B -->|HTTPS| I[Operata ingestion endpoint]
    F[Operata Fetcher Service] -->|read-only REST| G
    I --> F
```

## Amazon EventBridge topics Operata subscribes to

Operata subscribes to the following topics. These are metadata and analytics events only; no media flows through Amazon EventBridge.

| Category                               | Topic pattern                                                                                                                          | Purpose                                                                               |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Conversation analytics and lifecycle   | `v2.detail.events.conversation.{conversationId}.*`                                                                                     | Per-interaction lifecycle, IVR and flow timeline, routing outcomes, call disposition. |
| Conversation end                       | `v2.detail.events.conversation.{id}.user.end`                                                                                          | Triggers the Operata Fetcher Service to retrieve full conversation details.           |
| Conversation metrics                   | `v2.analytics.conversation.{conversationId}.metrics`                                                                                   | Per-interaction metrics (handle, queue, talk, hold, ACD).                             |
| Queue and agent real-time state        | `v2.analytics.queues.{queueId}.observations`, `v2.users.{userId}.routingStatus`, `v2.users.{userId}.activity`                          | Real-time queue depth, staffing, agent routing availability.                          |
| Platform and operational health        | `v2.operations.events.{eventId}`                                                                                                       | Telephony or Edge issues, flow failures, degradation.                                 |
| Speech and CX signals (optional)       | `v2.speechandtextanalytics.conversation.{conversationId}.sentiment`, `v2.speechandtextanalytics.conversation.{conversationId}.empathy` | Sentiment and empathy analysis. Textual metadata only; no raw audio.                  |
| Analytics data availability (optional) | `v2.analytics.conversations.details.jobs.availability`                                                                                 | Signals availability of bulk conversation detail data for backfill or reconciliation. |

## REST APIs Operata calls

Amazon EventBridge provides signals and deltas. Operata calls REST APIs to enrich and reconcile.

**Analytics (read-only):**

* `POST /api/v2/analytics/queues/aggregates/query` — queue KPIs (ASA, service level, abandons, volume).
* `POST /api/v2/analytics/users/aggregates/query` — agent KPIs (AHT, handled, occupancy).
* `POST /api/v2/analytics/conversations/aggregates/query` — KPIs across interactions.
* `GET /api/v2/analytics/conversations/{conversationId}/details` — the canonical Conversation Detail record (CDR equivalent).
* `POST /api/v2/analytics/conversations/details/query` — bulk query for backfill and reconciliation.

**Configuration and reference data (read-only):**

* `GET /api/v2/routing/queues` — queue name and config lookup.
* `GET /api/v2/flows` — flow and IVR name resolution.
* `GET /api/v2/users` — user and agent identity resolution.
* `GET /api/v2/telephony/providers/edges`, `GET /api/v2/telephony/siptrunks` — telephony context.

**Optional enrichment:**

* `GET /api/v2/conversations/calls/{conversationId}` — additional Conversation metadata.
* `GET /api/v2/recordings/conversations/{conversationId}` — recording metadata only, never audio.
* `/api/v2/speechandtextanalytics/*` — sentiment, topics, and transcript-derived analytics (when enabled).
* `/api/v2/quality/evaluations` — QM scores (when enabled).
* `GET /api/v2/audit/organization/configuration` — configuration change history.

Genesys Cloud does not expose a single CDR or CTR object. The Conversation Detail record from the Analytics Conversations API is the canonical equivalent. On every `v2.detail.events.conversation.*.user.end` event, the Fetcher Service calls `GET /api/v2/analytics/conversations/{conversationId}/details` to load the full record.

## OAuth scopes required

Operata uses client-credentials OAuth with least-privilege scopes. No write permissions are required.

**Core required:**

* `analytics:read`
* `routing:read`
* `users:read`

**Common optional enrichment:**

* `conversations:read`

**Optional, feature-dependent:**

* `speechTextAnalytics:read`
* `recording:read` (metadata only)
* `quality:read`
* `telephony:read`
* `audit:read`

## Verify

In the Operata console, open **Group Settings > Integrations**. The **Genesys Cloud** integration appears with status `Active` once the Fetcher Service receives its first conversation-end event and resolves the Conversation Detail record. Per-conversation analytics appear in the **Contacts** view within five minutes of conversation end.

## Mandatory observability fields

For Operata to deliver observability analytics on Genesys Cloud, the following fields must reach the platform. The Fetcher Service treats these as Mandatory tier; you cannot deny, encrypt, or transform them through the redaction config.

**EventBridge — conversation end event**

* `Event.Conversation.data.source`
* `Event.Conversation.data.timestamp`
* `Event.Conversation.data.conversationId`

**API — `GET /users/{id}`**

* `API.Users.username`

**API — `GET /conversations/{id}/details`**

* `API.Conversation.participants[purpose=*].sessions[*].edgeId`
* `API.Conversation.participants[purpose=agent]`
* `API.Conversation.divisionIds`
* `API.Conversations.participants[purpose=customer].sessions[*].segments[type=interact].disconnectType`
* `API.Conversations.participants[purpose=external].sessions[*].segments[type=interact].disconnectType`
* `API.Conversation.conversationId`
* `API.Conversation.originatingDirection`
* `API.Conversation.conversationStart`
* `API.Conversation.conversationEnd`
* `API.Conversation.participants[purpose=acd]`
* `API.Conversations.participants[*].sessions[*].mediaEndpointStats`
* `API.Conversation.mediaStatsMinConversationMos`
* `API.Conversation.mediaStatsMinConversationRFactor`
* `API.Conversations.participants[*].sessions[*].mediaType`
* `API.Conversation.participants[purpose=customer].sessions[*].dnis`
* `API.Conversation.participants[purpose=external].sessions[*].dnis`

## Related

* [Install the Genesys Cloud integration](/docs/genesys-installation) — Set up the OAuth client, Amazon EventBridge source, and Operata configuration.
* [Configure Genesys Cloud redaction](/docs/genesys-privacy) — Allow or deny fields the Fetcher Service forwards to Operata.
* [Concept: Privacy and redaction](/docs/concepts-privacy-and-redaction) — The cross-integration model the Fetcher Service implements.
* [Mandatory observability fields](#mandatory-observability-fields) — The fields Operata always retains.