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.

On demand Analysis

Insights will use analysis rules to determine which analysis should be performed on the conversation, unless the user explicitly specifies the analysis types to use.

CreateAnalysis API will always analyze the conversation when requested and it will disregard the percentage specified in the matching analysis rules.
BulkAnalyzeConversations API will use the percentage specified in the BulkAnalyzeConversations request over the one in the analysis rules.

Automatic Analysis

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

Insights matches conversations against all active analysis rules to decide what analysis should be performed for the conversation.
If a conversation does not fit any rules, then Insights does not automatically analyze the conversation.

Automatic analysis is supported for conversations uploaded through the following methods:

UploadConversations API
Dialogflow runtime Ingestion AnalyzeContent API
CreateAnalysis API

Automatic analysis is not supported for conversations uploaded through the following methods:

Dialogflow runtime Ingestion DetectIntent API - As this API does not have a notion of conversation completion, Insights cannot determine when to analyze this conversation.
IngestConversations API - Also referred to bulk upload.

To analyze these conversations, you can use the BulkAnalyzeConversations 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"