Implementing Agent Net Promoter Score (eNPS) Collection Workflows via Internal Survey Bots in Genesys Cloud CX
What This Guide Covers
This guide details the architectural implementation of an automated Employee Net Promoter Score (eNPS) collection workflow using internal survey bots within Genesys Cloud CX. The end result is a production-ready configuration where agents are prompted for feedback immediately following their interactions, with responses ingested into Analytics Custom Fields without impacting post-call wrap-up latency.
Prerequisites, Roles & Licensing
- Licensing Tier: Genesys Cloud CX Premium (CX2 or CX3). Basic plans lack the Survey Builder API access required for programmatic survey injection.
- WFM Add-on: Required if eNPS data is to be correlated with Quality Management (QM) scores in real-time dashboards.
- Granular Permissions:
Survey > Survey > EditandSurvey > Survey > View. Additionally,Analytics > Custom Fields > Writepermissions are required for storing the score metadata. - OAuth Scopes:
survey:write,analytics:read,agent:write. These scopes must be granted to the integration user or application token used to push survey results. - External Dependencies: A configured Survey Builder template exists prior to flow deployment. The target system for long-term storage (e.g., Snowflake, Data Lake) must accept JSON POST requests within 5 seconds of submission.
The Implementation Deep-Dive
1. Architect Flow Triggering and Context Injection
The core mechanism involves intercepting the agent interaction lifecycle at the Post-Call state. We do not use standard outbound surveys here; we utilize an internal flow triggered by a specific event, typically On Agent Logoff or On Call End. The Architect flow must determine if the agent is eligible for eNPS collection based on their employee status or department code before initiating the survey prompt.
Architect Flow Logic:
Configure a Set Variable node immediately after the call disconnects to capture the CallDuration, AgentName, and QueueName. Pass these variables into the Survey API payload. Use an Expression node to check if the agent is marked as internal (e.g., agent.employeeType == "Internal"). If false, route to a standard end-node to prevent survey fatigue among non-staff personnel.
Production-Ready Payload Example:
When invoking the Survey API via the Architect Send Data action or HTTP Callout node, the payload must adhere strictly to the Genesys Cloud CX Survey API schema. Do not include unnecessary fields that increase latency.
{
"surveyId": "YOUR_INTERNAL_ENPS_SURVEY_ID",
"contactId": "CALL_CONTACT_ID",
"agentId": "AGENT_USER_ID",
"fields": {
"eNPS_Score": "{!Score}",
"CallDuration": "{!CallDuration}",
"Timestamp": "{!CallEndTime}"
},
"callbackUrl": "https://your-crm-endpoint.com/api/feedback"
}
The Trap:
A common misconfiguration is triggering the survey API call synchronously within the main call flow before the agent has fully disconnected. If the Survey API endpoint experiences latency (e.g., >2 seconds), the Architect flow blocks, causing the agent to remain in the Wrap-Up state indefinitely. This creates a bottleneck where agents cannot log off, leading to system-wide queue starvation and increased Average Handle Time (AHT) metrics artificially inflated by survey wait times.
Architectural Reasoning:
We recommend an asynchronous fire-and-forget pattern for the API call. Use the Send Data action with Wait For Response set to False. This ensures the flow proceeds immediately after queuing the request, decoupling the survey logic from the agent log-off sequence. The latency of the network handshake must be minimized by placing the API call node as late as possible in the post-call state, ideally after any local caching operations complete.
2. Survey Builder Configuration and Data Parsing
The Survey Builder interface within Genesys Cloud CX requires specific configuration to ensure the eNPS data is structured correctly for downstream analytics. A standard text input field is insufficient because it does not enforce the 0-10 scale required by Net Promoter Score standards. The survey must utilize a Rating or Scale component type.
Configuration Steps:
- Navigate to Surveys > Create Survey.
- Select Internal Agent as the audience type. This restricts visibility and prevents external customers from accessing the form.
- Add a single question node labeled “How likely are you to recommend working at this company?”.
- Set the input type to
Scalewith Min Value 0 and Max Value 10. - Define response labels:
Detractors (0-6),Passives (7-8),Promoters (9-10).
Data Mapping:
Ensure the eNPS_Score variable in the Architect flow maps directly to the responseValue field in the Survey API. Do not attempt to map this via a custom field name that differs from the survey definition, as this causes null values in Analytics Custom Fields and breaks dashboard calculations.
The Trap:
Engineers often configure the survey question using a generic text box and rely on regex parsing later to extract the number. This introduces a failure mode where agents type “8” or “8 points” or “eight”. The downstream analytics pipeline fails to parse these strings into numeric values, resulting in NaN (Not a Number) errors in reporting dashboards.
Architectural Reasoning:
Using the native Scale component enforces data integrity at the source. This reduces the computational load on the ETL pipeline that processes survey responses. If you must use text inputs due to legacy constraints, implement a validation regex within the flow before sending the data to Analytics. The regex ^[0-9]$ ensures only single-digit integers are accepted, while ^[1-9][0-9]? allows for the 10 value. Failing to validate input types creates noise in the dataset that skews eNPS trends over time.
3. Integration with Analytics Custom Fields and WFM
Once the survey response is collected, it must be written back into the Genesys Cloud CX environment or pushed to an external Data Lake. The most robust method for immediate visibility is writing to Analytics Custom Fields. This allows you to join eNPS data with other interaction metrics like AHT, FCR (First Contact Resolution), and CSAT.
API Endpoint:
Use the POST /analytics/customfields endpoint to update the agent profile or interaction record with the score.
{
"entityId": "AGENT_USER_ID",
"dataType": "INTEGER",
"fieldName": "eNPS_Score_Last_Interaction",
"value": "9"
}
WFM Integration:
If you utilize Workforce Management (WFM) for performance reviews, do not rely solely on the Analytics Custom Field. Push the data to the WFM API via POST /wfm/v1/agents/{agentId}/performance. This ensures that a low eNPS score triggers an immediate coaching notification within the WFM interface rather than waiting for a weekly report generation.
The Trap:
A frequent error occurs when the integration user lacks the Analytics > Custom Fields > Write permission for the specific tenant organization. This results in a 403 Forbidden response from the API, causing the survey flow to fail silently if error handling is not explicitly configured. The agent receives the survey prompt, submits it, but the score never appears in the reporting dashboard, leading stakeholders to believe the program is ineffective.
Architectural Reasoning:
Implement a retry mechanism with exponential backoff for API failures. If the Analytics Custom Field write fails, queue the request in a temporary storage bucket (e.g., S3) rather than discarding it. This ensures data completeness over time. Furthermore, avoid writing to WFM synchronously during the post-call window if your WFM API is under heavy load. Prefer an asynchronous webhook handler that acknowledges receipt immediately and processes the score update in the background within a 60-second window.
Validation, Edge Cases & Troubleshooting
Edge Case 1: Agent Logoff During Survey Submission
The Failure Condition: An agent begins the survey but logs off or terminates the browser session before the API acknowledgment is received. The flow hangs waiting for confirmation that the data was saved.
The Root Cause: The Wait For Response flag in the Architect node is set to True, causing the thread to block until the HTTP response arrives. If the network drops during this window, the agent remains stuck in the workflow.
The Solution: Set Wait For Response to False. Implement a heartbeat check or use the On Agent Logoff event as a secondary trigger to push any pending survey data stored in a local cache (if available) or flag the session as incomplete for manual review.
Edge Case 2: Survey Fatigue and Response Rate Degradation
The Failure Condition: Over time, agents stop responding to the survey prompts or provide random scores, skewing the eNPS data validity.
The Root Cause: The workflow triggers on every single interaction without frequency capping. Agents perceive the survey as a redundant administrative burden.
The Solution: Implement a frequency cap logic within the Architect flow. Check a custom field Last_Survey_Time. Only trigger if Current_Time - Last_Survey_Time > 168 hours (weekly threshold). This ensures agents are surveyed no more than once per week, preserving data quality and agent goodwill.
Edge Case 3: PII Leakage in Survey Responses
The Failure Condition: Sensitive customer information is inadvertently captured within the fields object of the survey payload due to a variable misconfiguration.
The Root Cause: The Architect flow passes the CustomerName or AccountNumber variables into the survey payload alongside the eNPS score, assuming they are sanitized. However, if the survey template allows free-text input in other fields, PII can be stored in plain text within Genesys Cloud CX logs.
The Solution: Strictly define the data schema for the Survey API call. Use a Sanitize node to remove all PII variables before injection into the payload. Ensure the Survey Template is configured with “Masking Enabled” for all non-score fields. Audit the data storage configuration to ensure encryption at rest is active for all survey response objects.