Configure analysis rules using the API

You can customize your Conversational Insights analyses using analysis rules within an API. You can automatically apply these rules when you upload conversations into Insights.

Analysis rule capabilities

Analysis rules provide the following customization capabilities all in one place:

  • Use filters to choose which conversations to analyze.
  • Specify the percentage of your conversation dataset for Insights to analyze.
  • Designate different types of analysis for each portion of your dataset.

The existing analysis configuration settings let you specify the percentage of conversations to analyze and designate the type of analysis to use on your full conversation dataset. However, with analysis rules, you can also filter your conversations, then specify both the percentage and analysis type to use for the filtered dataset. Analysis rule replaces the analysis configuration settings.

Effects of analysis rules on Insights behavior

After you configure active analysis rules, the following changes occur:

  1. Insights matches every conversation against all active analysis rules to decide what analysis should be automatically run for the conversation.
  2. If a conversation does not fit any rules, then Insights does not automatically analyze the conversation.
  3. Insights denies any updates to analysis configuration settings.

Analysis rule compatibilities

Analysis rules are compatible with the following:

Analysis configurations created in the Insights console override analysis rules created with the AnalysisRules API. Analysis percentages specified in the BulkAnalyzeConversations API override analysis percentages configured through the AnalysisRules API.

Create a rule

Using the AnalysisRules API, you can create an analysis rule with the CreateAnalysisRule command. You can define each aspect of a rule with parameter values. For example, you must give each rule a name using the Display_name parameter with a non-empty string value of less than 64 characters. You can also decide whether or not to use a rule for conversation analysis by setting the Active parameter with a boolean value.

You can also create multiple analysis rules in Insights. If a conversation matches multiple rules, Insights applies a combination of all the requirements specified in all the matching rules. However, if a conversation matches conflicting rules, Insights doesn't analyze that conversation.

The following code illustrates how to create a new rule with CreateAnalysisRule:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d "{ display_name: 'runtime' , conversation_filter: 'data_source.gcs_source: "*"', annotator_selector:{run_silence_annotator : true,  run_sentiment_annotator: true}, analysis_percentage:0.4, active:true}" \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/analysisRules"

The following is an example JSON representation of an analysis rule:

{
"display_name": string , 
"conversation_filter": string, 
"annotator_selector": object (AnnotatorSelector), 
"analysis_percentage": number, 
"active": boolean
}

Filter conversations

Conversation filters allow you to narrow down your conversation dataset and analyze a smaller number of related conversations. Analysis rules offer the ability to filter your conversation dataset before running any analyses.

Define your filters using the Conversation_filter parameter. The value must be an alphanumeric string. If the value is empty, the rule applies to all your conversations.

Crucially, the filtering criteria cannot depend on the analysis result. For example, a single conversation with a specific custom highlight cannot be a conversation filter.

Conversation percentage

With an analysis rule, you can also configure the percentage of conversations for Insights to automatically analyze. If an uploaded conversation passes the filter a rule's filter, then Insights decides whether or not that conversation should be analyzed based on the percentage specified in the rule.

Set your conversation percentage using the Analysis_percentage parameter. The value must be a number between 0 and 1, where 1 means 100%. You can only use this parameter in a rule to configure an automated analysis. In other words, this percentage does not apply to the CreateAnalysis or BulkAnalysis commands.

Analysis types

Conversational Insights offers a variety of analysis types to help you better understand your conversation data. With an analysis rule, you can apply different analysis types to each portion of your filtered or unfiltered conversation dataset.

Insights offers the following analysis types:

  • Custom and smart highlights
  • Entity extraction
  • Intent extraction
  • Interruptions
  • Sentiment
  • Silence
  • Quality AI
  • Summarization
  • Topic modeling

Analysis types are set using the Annotator_selector parameter. The value must be an AnnotatorSelector object. This configuration specifies which annotators to run for a specific set of conversations. A valid active analysis rule must contain at least one enabled annotator.

Additional operations

You can use the following additional API commands with analysis rules:

  • Find the rule used for a particular conversation with GetAnalysisRule.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/analysisRules/ANALYSIS_RULE_ID"

  • List all of your rules with ListAnalysisRules.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/analysisRules"

  • Edit a rule with UpdateAnalysisRule.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{annotator_selector: {run_silence_annotator: true}}' \
"https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/analysisRules/ANALYSIS_RULE_ID?updateMask=annotator_selector"

  • Remove a rule with DeleteAnalysisRule.

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/analysisRules/ANALYSIS_RULE_ID"