# Genesys Cloud API & Webhook Integration Reference
Overview
Nectar's integration with Genesys Cloud collects inventory and real-time data through two mechanisms:
- Polling APIs — Scheduled REST API calls that retrieve configuration and inventory data on a defined cadence (hourly or daily).
- Webhooks (Event Subscriptions) — Real-time event-driven notifications pushed from Genesys Cloud via the EventBridge notification framework whenever a state change occurs.
The data collected is used to populate Nectar's real-time (RT) database tables for inventory management, capacity reporting, and real-time monitoring dashboards.
Polling APIs
The following APIs are called on a scheduled basis. Where individual subscriptions are required (e.g., per-site or per-edge), Nectar iterates over all known instances automatically.
Architecture & Design
| Data Object | API Endpoint | Pull Frequency | Required Permission |
|---|---|---|---|
| Agent Assistants | GET /api/v2/assistants |
Daily | assistants:assistant:view |
| Divisions | GET /api/v2/authorization/divisions |
Daily | None (authorization scope) |
| Flows | GET /api/v2/flows |
Daily | architect:flow:view |
| IVR Configs | GET /api/v2/architect/ivrs |
Daily | routing:callRoute:view |
| Locations | GET /api/v2/locations |
Daily | None |
| Outbound Campaigns | GET /api/v2/outbound/campaigns |
Daily | outbound:campaign:view |
| System Prompts | GET /api/v2/architect/systemprompts |
Daily | architect:systemPrompt:view |
Routing
| Data Object | API Endpoint | Pull Frequency | Required Permission |
|---|---|---|---|
| Routing Queues | GET /api/v2/routing/queues |
Daily | routing:queue:view |
| Routing Skill Groups | GET /api/v2/routing/skillgroups |
Daily | routing:skillGroup:view |
| Routing Skills | GET /api/v2/routing/skills |
Daily | None |
Telephony / Edge Infrastructure
| Data Object | API Endpoint | Pull Frequency | Required Permission |
|---|---|---|---|
| Edge Providers | GET /api/v2/telephony/providers/edges |
Daily | telephony:plugin:all |
| Edge DID Pools | GET /api/v2/telephony/providers/edges/didpools |
Daily | telephony:plugin:all |
| Edge DIDs | GET /api/v2/telephony/providers/edges/didpools/dids |
Daily | telephony:plugin:all |
| Edge Groups | GET /api/v2/telephony/providers/edges/edgegroups |
Daily | telephony:plugin:all |
| Edge Phones | GET /api/v2/telephony/providers/edges/phones |
Daily | telephony:plugin:all |
| Edge Sites | GET /api/v2/telephony/providers/edges/sites |
Daily | None |
| Edge Trunks | GET /api/v2/telephony/providers/edges/trunks |
Daily | telephony:plugin:all |
| Number Plans | GET /api/v2/telephony/providers/edges/sites/{siteId}/numberplans |
Daily | telephony:plugin:all |
| Phone Base Settings | GET /api/v2/telephony/providers/edges/phonebasesettings |
Daily | telephony:plugin:all |
| Stations | GET /api/v2/stations |
Hourly | None |
Note: Number Plans are pulled per site. Nectar iterates over all known sites and calls the endpoint for each
siteId. The API returns a maximum of 200 records per site.
Conversations
| Data Object | API Endpoint | Pull Frequency | Required Permission |
|---|---|---|---|
| Conversation Details | GET /api/v2/analytics/conversations/{conversationId}/details |
Per conversation | analytics:conversationDetail:view |
Users & Licensing
| Data Object | API Endpoint | Pull Frequency | Required Permission |
|---|---|---|---|
| User License | GET /api/v2/license/users |
Daily | None |
Webhooks
The following data objects are collected via real-time event subscriptions using the Genesys Cloud notification framework. Nectar subscribes to these topics through AWS EventBridge. Where individual subscriptions are required, Nectar subscribes for each known entity (e.g., per edge, per trunk, per queue).
Pull Frequency: All webhook-based data is event-driven — data is received in real-time as state changes occur in Genesys Cloud. There is no scheduled polling interval.
Conversations & Analytics
| Data Object | Notification Topic | Subscription Scope | Required Permission |
|---|---|---|---|
| Conversation Customer End Event | v2.detail.events.conversation.{id}.customer.end |
Per Conversation | None |
| Flow Metrics | v2.analytics.flow.{id}.metrics |
Per Flow | analytics:flowAggregate:view |
| Queue Activity | v2.analytics.queues.{id}.activity |
Per Queue | analytics:queueObservation:view |
| Queue User Events | v2.routing.queues.{id}.users |
Per Queue | routing:queue:view |
Edge Infrastructure
| Data Object | Notification Topic | Subscription Scope | Required Permission |
|---|---|---|---|
| Edge Metrics | v2.telephony.providers.edges.{id}.metrics |
Per Edge | None |
| Edge Trunk Instance | v2.telephony.providers.edges.trunks.{id} |
Per Trunk | None |
| Edge Trunk Metrics | v2.telephony.providers.edges.trunks.{id}.metrics |
Per Trunk | None |
| Edge Phone Status | v2.telephony.providers.edges.phones.{id} |
Per Phone | telephony:plugin:all |
Platform & Operations
| Data Object | Notification Topic | Subscription Scope | Required Permission |
|---|---|---|---|
| Operational Events | v2.operations.events.{id} |
Per Operation | None |
Users
| Data Object | Notification Topic | Subscription Scope | Required Permission |
|---|---|---|---|
| User Activity | v2.users.{id}.activity |
Per User | None |
| User Token Events | v2.users.{id}.tokens |
Per User | None |
Genesys Cloud Notification Framework
Nectar uses the Genesys Cloud EventBridge integration to receive webhook notifications. Subscriptions are managed server-side, and all incoming events are processed through Nectar's cloud agent, published to a Kafka pipeline, and persisted into the real-time database.
For reference on available notification topics, see the Genesys Cloud Notifications Documentation.
For reference on the REST APIs used, see the Genesys Cloud API Explorer.