Autolabeling and correlation rules

Customer Experience Insights introduces two rule-based features to enhance conversation processing:

Autolabeling rules: Automatically apply key-value labels to conversations based on defined conditions.
Correlation rules: Define how to link related conversation segments together to form complete customer interaction views.

Both rule types use the Common Expression Language (CEL) to provide flexible and dynamic rule definitions. CEL is fundamental to both autolabeling and correlation rules. You can configure these rules with the API or the CX Insights console.

Autolabeling rules

Autolabeling rules automatically enrich conversations with custom key-value labels during import. These labels improve filtering, categorization, and integration with other analyses and workflows. You can perform the following actions with autolabeling rules:

Categorize conversations by topic, customer type, product, or outcome.
Extract key data points from conversation metadata or Dialogflow parameters, such as callId, isAuthenticated, and intent names, into labels.
Flag conversations requiring specific attention, such as high_escalation_risk.

Labels

Each autolabeling rule defines a label and contains ordered condition messages. Each label uses the following CEL expressions:

Condition: evaluates whether a conversation is true or false. An empty condition defaults to true.
Value: produces the string value for a label if the condition is true.

The first LabelingCondition that matches determines the label's value.

Configure rules

Follow these steps to configure autolabeling rules using either the API or the CX Insights console.

API

Use the Create operation to configure an AutoLabelingRule. Sample request body:

{
  "displayName": "$DISPLAY_NAME",
  "labelKey": "$UNIQUE_KEY_NAME",
  "labelKeyType": LABEL_KEY_TYPE_CUSTOM 
"conditions": [
    {
      "condition": "conversation.turn_count > 10 && conversation.duration > "60s"",
      "value": "'long_call'"
    },
    {
      "condition": "conversation.agent_id == "agent_007"",
      "value": "'special_agent'"
    }
  ],
"active": true
}

Curl command, if the request is saved in auto_labeling_rule.json:

  curl-X POST 

      -H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

      -H "Content-Type: application/json; charset=utf-8" 

      -d @auto_labeling_rule.json 

  "https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/autoLabelingRules?auto_labeling_rule_id=$RULE_ID"

Give your rule a name in the following format: projects/[project-id]/locations/[location-id]/autoLabelingRules/[auto_labeling_rule]. The [auto_labeling_rule] ID is the label_key for custom rules.

You can also use any of the following operations with autolabeling rules. An autolabeling rule can have a maximum of 100 labels per conversation with a maximum of 256 characters per entry.

Get.

curl  -X GET 

  -H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

  -H "Content-Type: application/json; charset=utf-8" \ "https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/autoLabelingRules/$RULE_ID"

List.

curl  -X GET 

  -H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

  -H "Content-Type: application/json; charset=utf-8" \ "https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/autoLabelingRules"

Update. Depending on what fields to update, specify the update_mask.

curl  -X PATCH 

  -H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

  -H "Content-Type: application/json; charset=utf-8" 

  -d @update_payload.json \ "https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/autoLabelingRules/$RULE_ID?update_mask=displayName,active"

TestAutoLabelingRule. Your payload should contain the rule to test and a sample conversation the rule will be evaluated on. Example:

{
"conversation": {
"agentId": "agent_007",
"turnCount": 15,
"duration": "75s"
/# Add other conversation fields relevant to the rule
},
"autoLabelingRule": {
"displayName": "Test Rule",
"labelKey": "test_category",
"conditions": [
  {
   "condition": "conversation.turn_count > 10 && conversation.duration > "60s"",
    "value": "'long_call_test'"
  }
],
"active": true
}
}

Console

Navigate to the CX Insights console, sign in, and select your project. CX Insights console
Click settingsSettings > Auto Labeling Rules.
Enter CEL expressions with a Monaco editor.
Click Save.

CEL examples

Label by agent ID:

label_key: "agent_category"
conditions {
condition: "conversation.agent_id == '007'"
value: "'special_agent'"
}
conditions {
condition: "conversation.agent_id.startsWith('team_a')"
value: "'tier_1_support'"
}
conditions {
condition: "" // Default
value: "'standard'"
}

Flag negative sentiment:

label_key: "needs_review"
conditions {
// This example assumes sentiment scores are present in the conversation's latest_analysis
condition: "has(conversation.latest_analysis.analysis_result.call_analysis_metadata.sentiments) && conversation.latest_analysis. analysis_result.call_analysis_metadata.sentiments.exists(s, s.    sentiment_data.score < -0.5)"
value: "'true'"
}

Extract a Dialogflow parameter:

label_key: "df_session_outcome"
conditions {
condition: "" // Always try to extract
value: "conversation.runtime_annotations.map(a, a.dialogflow_interaction.detect_intent_response_v3.query_result.parameters).filter(p, has(p.outcome)).map(p, p.outcome).first_element_or_empty_string()"
}

Use autolabels in analysis rule filters

Autolabeling rules can apply labels that control which conversations the main analysis rules process. The conversation_filter field in an analysis rule can reference labels using the labels map.

Example:

// AnalysisRule to run detailed analysis on conversations labeled 'needs_review: true'
display_name: "Detailed Analysis for Reviewed Conversations"
conversation_filter: "labels.needs_review = \"true\""
annotator_selector: {
  run_summarization_annotator: true
  // ... other annotators
}
analysis_percentage: 1.0
active: true

Correlation rules

Correlation rules define how Customer Experience Insights identifies and links related conversation segments. A conversation segment represents a single piece of a conversation, as it was ingested, such as a Dialogflow session or a single agent interaction. A full conversation represents a complete, linked conversation composed of one or more segments. By default, all new conversations start as segments. Correlation rules help you create a complete history of a customer's interaction, even when it spans multiple agents, channels, or sessions.

Correlation rules provide the following benefits for customer service conversation analysis.

Unified transcript: View a single, chronological transcript that combines utterances from multiple sources, such as a chatbot session followed by a live agent call.
Cross-channel analysis: Link interactions across different channels, such as chat and voice, to analyze sentiment trends and topic progression throughout an entire conversation journey.
Metric accuracy: Calculate metrics like total handling time or resolution rate for the full interaction rather than only individual parts.
Context for agents: Provide human agents with the full history of previous automated interactions.

Correlation process

When correlation rules match multiple conversation segments, CX Insights groups them together. CX Insights then creates a new entry to represent the full conversation with its own unique conversation ID. CX Insights sets a full conversation's correlation ID to the common key that links the segments, and its type to FULL. CX Insights sets the original segments' correlation IDs to the common key and their types to SEGMENT. If a segment is not correlated with any other segments, CX Insights gives it both SEGMENT and FULL correlation types.

Link messages

Correlation rules link related conversation segments from different sources and channels. CX Insights follows these steps to link conversation segments:

Group by join key: CX Insights evaluates a CEL join key expression to extract a common identifier from the conversation, such as callId. Conversations sharing the same join key are potential candidates for linking. Join keys must be specific. If a key matches more than 20 conversations, the correlation might be rejected to prevent performance issues.
Refine with constraints: The CEL constraint expression is an optional boolean check evaluated pairwise between candidates. This expression helps confirm if two segments sharing a key should actually be linked. This check is bidirectional, so it could include segment A linked to segment B and segment B linked to segment A.
Transitive link: Linking is transitive. If conversation A is linked to B, and B is linked to C, then A, B, and C are merged into a single FULL conversation group.

A merged conversation can contain a maximum of five segments.

Configure correlation rules

You can configure correlation rules using either the API or the CX Insights console.

API

Run the following code to set up a CorrelationConfig.

curl  -X PATCH 

  -H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

  -H "Content-Type: application/json; charset=utf-8" 

  -d @update_corr_config.json 

"https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/correlationConfig?update_mask=fullConversationConfig"

Give your rule a name with the following format: projects/{project-id}/locations/{location-id}/correlationConfig.
View the result in the Conversation.CorrelationInfo field.

You can use any of the following operations with correlation rules.

GetCorrelationConfig.

curl-X GET 

-H "Authorization: Bearer $(gcloud auth --impersonate-service-account=$SA_EMAIL print-access-token)" 

-H "Content-Type: application/json; charset=utf-8" 

"https://$ENDPOINT/v1/projects/$PROJECT/locations/$LOCATION/correlationConfig"

UpdateCorrelationConfig. Sample body request, if it is saved in a updated_corr_config.json:

{
"fullConversationConfig": {
"correlationRules": [
  {
    "joinKeyExpression": "conversation.labels.uui",
    "active": true
  }
]
}
}

TestCorrelationConfig. Your payload should specify the sample conversation details besides the correlation rule to test. Example:

{
"correlationConfig": {
"fullConversationConfig": {
  "correlationRules": [
   {
      "joinKeyExpression": "conversation.agent_id",
     "active": true
    }
  ]
}
},
"filter": "agent_id="agent_007"",
"maxSampleCount": 100
}

Console

Navigate to the CX Insights console, sign in, and select your project. CX Insights console
Click settingsSettings > Correlation Config.
Click Save.

Administrators can define and manage CorrelationRule entries within the CorrelationConfig. You can test your correlation rules by selecting conversations. Test results are added to a dataset for review.

CEL example

Link by callId from Dialogflow:

join_key_expression:
// Extracts 'callId' from Dialogflow parameters, falls back to conversation name.
default(conversation.runtime_annotations.map(a,
  a.dialogflow_interaction.detect_intent_response_v3.query_result.parameters)
  .filter(p, has(p.callId))
  .map(p, p.callId)
  .first_element_or_empty_string(), conversation.name)

Segment and conversation-level analysis

With CX Insights you can analyze conversations at different granularities, including both per-segment and per-conversation analysis for all features.

Navigate to the CX Insights console, sign in, and select your project. CX Insights console
Click settingsSettings, and choose your analysis granularity. Your choice applies to future analyses and can be applied retroactively, with potential additional costs.
Click Save.

The Conversation Hub and Quality AI pages in the console compare conversation- and segment-level data, and indicate the multisegment structure of linked conversations.

Filter metrics and analysis

To target specific levels of analysis in the API or console, use the following filters.

Segment-level view

The goal of this view is to analyze specific parts of an interaction, such as a single agent's turn. Use the correlation_info.correlation_types:SEGMENT parameter to filter the segment level view.

Full conversation view

Use this view to analyze the complete customer journey, whether it consists of linked or standalone conversations. Use the correlation_info.correlation_types:FULL parameter to filter the full conversation view.

Autolabeling and correlation rules Stay organized with collections Save and categorize content based on your preferences.

Autolabeling rules

Labels

Configure rules

API

Console

CEL examples

Use autolabels in analysis rule filters

Correlation rules

Correlation process

Link messages

Configure correlation rules

API

Console

CEL example

Segment and conversation-level analysis

Filter metrics and analysis

Segment-level view

Full conversation view

Autolabeling and correlation rules