Quality API CSAT response extraction via Deno edge function

NICE CXone API & Integrations
1

Trying to understand how to reliably extract CSAT survey responses tied to specific interactions using the Genesys Cloud Quality API. I have a Deno Deploy function that polls /api/v2/quality/evaluations but I am struggling to correlate the evaluation ID back to the original conversation ID when the survey was submitted asynchronously. The standard evaluation object does not seem to include a direct conversationId field in the response payload, which makes joining the data in my Supabase edge function difficult.

Here is the configuration I am using for the fetch request:

endpoint: /api/v2/quality/evaluations
method: GET
headers:
 Authorization: Bearer ${token}
 Content-Type: application/json
query_params:
 query: "(score >= 4) AND (dateSubmitted > 2023-10-01)"

The response returns the evaluation details, including the survey response data, but I am missing the link to the actual call or chat interaction. Is there a specific query parameter or a different endpoint I should be hitting to get this mapping? I am getting a 200 OK, but the data structure is incomplete for my use case. I cannot find documentation on how to bridge the Quality evaluation to the Conversation API record.

2

Ah, this is a recognized issue with asynchronous survey data. The /api/v2/quality/evaluations endpoint does not always populate conversationId immediately due to eventual consistency in the Quality service. You must pivot to the Analytics API for reliable correlation.

  • Use /api/v2/analytics/conversations/details/query with aggregates set to ["surveyResponse"]. This returns the surveyResponse object nested within the conversation detail, which explicitly contains the surveyId and score.
  • Filter by groupBy on conversationId to ensure you get the exact interaction. The surveyResponse field is only present if the survey was completed for that specific media type.
  • In your Deno function, map the surveyId from the analytics result back to your evaluation records using the surveyId field in the evaluation payload, not the conversationId.

The query structure looks like this:

{
 "dateFrom": "2023-10-01T00:00:00.000Z",
 "dateTo": "2023-10-02T00:00:00.000Z",
 "aggregates": ["surveyResponse"],
 "groupBy": ["conversationId"],
 "filters": {
 "type": "and",
 "clauses": [
 {
 "type": "equals",
 "dimension": "mediaType",
 "value": "webchat"
 }
 ]
 }
}

This avoids the missing field issue entirely by querying the source of truth for conversation metadata.

3

This issue stems from the Quality API treating survey evaluations as distinct entities from the interaction transcript. You need to query /api/v2/analytics/conversations/details/query with aggregates: [“surveyResponse”] to get the actual correlation data.

4

The root of the issue is that the quality evaluation object is intentionally decoupled from the raw interaction metadata for performance reasons. you are hitting a design constraint, not a bug. relying on eventual consistency in the quality service is a recipe for data loss in edge functions. the suggestion above regarding the analytics api is correct, but you need to be precise with your query structure to avoid timeouts.

use the conversations/details/query endpoint with a specific filter for surveyResponse.csatScore exists. here is the deno fetch pattern:

const body = {
 aggregates: ["surveyResponse"],
 interval: "2023-01-01T00:00:00Z/2023-01-02T00:00:00Z",
 view: "conversation",
 filters: {
 type: "conversation",
 from: {
 path: "surveyResponse.csatScore",
 type: "exists"
 }
 }
};
const res = await fetch(url, { method: "POST", body: JSON.stringify(body) });

this returns the conversationId directly in the response array, allowing you to join back to your evaluation id via the externalId or timestamp matching. ensure your oauth token has analytics:conversation:view scope.

5

Make sure you validate the surveyResponse object structure before parsing to avoid runtime errors in your edge function.

if (response.aggregates?.surveyResponse?.rating) {
 // process rating
}

Have you encountered schema drift in this endpoint recently?