Analyze conversations using Custom Highlights

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

Overview

Custom Highlights functions in a similar way as the Smart Highlights feature. A highlight contains keywords, phrases and/or sentences that CCAI Insights recognizes as being important to determining the user's intent. If highlights are present, they are labeled in the returned transcript. Smart Highlights automatically detects highlights based on a range of pre-set scenarios, while Custom Highlights allows you to specify custom criteria that should be recognized as highlights.

A custom highlight can be made up of one or more phrase match rule groups. A phrase match rule group contains one or more rules. You can use the following parameters to customize the behavior of your rules.

Rules to determine a match

You can specify whether a highlight should be detected if only one of the rule groups resolves to true, or if all of the rule groups resolve to true. Similarly, you can specify that a rule group should resolve to true if only one of its rules is met, or if conditions for all rules in the rule group must be met.

Exact match vs. semantic match

You can specify whether a match must be an exact match to a provided word/phrase or whether a match can be text with a similar intent.

Match type Description Additional configurations Example
Exact match Determines whether a text is an exact match to a provided keyword or phrase. case_sensitive. Specifies whether the match must be case sensitive. A highlight must be an exact match to the keyword BERRY. If you disable case sensitivity, BERRY, berry, Berry, and so on will all be considered matches. If you enable case sensitivity, only BERRY will be considered a match.
Semantic match Determines whether a text has a similar intent to the provided phrase or sentence. similarity_threshold. Specifies how similar the text's intent must be to be considered a match. The phrase "Let me take care of this" must be matched with similar phrases. You can use the value of similarity_threshold so that the phrase "I will get things sorted for you" is considered a match (with similar intent, but "how are you today" is not.

If you would like to try this feature without needing to upload your own data, CCAI Insights provides a publicly-available sample conversation in the following location: gs://cloud-samples-data/ccai/chat_sample.json.

Create a custom highlight using the CCAI Insights API

Detect "any of" a list of specified query strings

The following sample creates a PhraseMatcher object that tells CCAI Insights to add highlight labels to either of two phrases whenever they appear in a conversation. Both phrases do not need to appear in order to be detected as a highlight.

REST

See the PhraseMatcherType and PhraseMatchRuleGroupType reference documentation for complete details. Substituting PHONE and CELLPHONE for the two query fields should result in the sample output.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your GCP project ID.
  • LOCATION_ID: the location you chose for your Cloud Storage bucket. The only location currently available is us-central1.
  • DISPLAY_NAME: the human-readible name of the phrase matcher.
  • QUERY: the word or phrase to be matched.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/phraseMatchers

Request JSON body:

{
  "display_name": DISPLAY_NAME,
  "type": "ANY_OF",
  "active": true,
  "phrase_match_rule_groups": {
      "type": "ANY_OF",
      "phrase_match_rules": {
          "query": QUERY
          "config": {
              "exact_match_config": {
             }
          }
       },
       "phrase_match_rules": {
          "query": QUERY
          "config": {
              "exact_match_config": {
              }
           }
       }
  },
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/phraseMatchers/PHRASE_MATCHER_ID",
  "revisionId": "REVISION_ID",
  "revisionCreateTime": "2021-01-20T10:10:10.123000Z",
  "displayName": "PHONE_SERVICE",
  "type": "ANY_OF",
  "active": true,
  "phraseMatchRuleGroups": [
    {
      "type": "ANY_OF",
      "phraseMatchRules": [
        {
          "query": "PHONE",
          "config": {
            "exactMatchConfig": {}
          }
        },
        {
          "query": "CELLPHONE",
          "config": {
            "exactMatchConfig": {}
          }
        }
      ]
    }
  ],
  "activationUpdateTime": "2021-01-20T10:10:10.123000Z"
}

Python

from google.cloud import contact_center_insights_v1


def create_phrase_matcher_any_of(
    project_id: str,
) -> contact_center_insights_v1.PhraseMatcher:
    """Creates a phrase matcher that matches any of the specified queries.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.

    Returns:
        A phrase matcher.
    """
    # Construct a parent resource.
    parent = (
        contact_center_insights_v1.ContactCenterInsightsClient.common_location_path(
            project_id, "us-central1"
        )
    )

    # Construct a phrase matcher that matches any of its rule groups.
    phrase_matcher = contact_center_insights_v1.PhraseMatcher()
    phrase_matcher.display_name = "PHONE_SERVICE"
    phrase_matcher.type_ = (
        contact_center_insights_v1.PhraseMatcher.PhraseMatcherType.ANY_OF
    )
    phrase_matcher.active = True

    # Construct a rule group to match the word "PHONE" or "CELLPHONE", ignoring case sensitivity.
    rule_group = contact_center_insights_v1.PhraseMatchRuleGroup()
    rule_group.type_ = (
        contact_center_insights_v1.PhraseMatchRuleGroup.PhraseMatchRuleGroupType.ANY_OF
    )

    for word in ["PHONE", "CELLPHONE"]:
        rule = contact_center_insights_v1.PhraseMatchRule()
        rule.query = word
        rule.config.exact_match_config = contact_center_insights_v1.ExactMatchConfig()
        rule_group.phrase_match_rules.append(rule)
    phrase_matcher.phrase_match_rule_groups.append(rule_group)

    # Call the Insights client to create a phrase matcher.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    phrase_matcher = insights_client.create_phrase_matcher(
        parent=parent, phrase_matcher=phrase_matcher
    )

    print(f"Created {phrase_matcher.name}")
    return phrase_matcher

Java


import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.ExactMatchConfig;
import com.google.cloud.contactcenterinsights.v1.LocationName;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRule;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRuleConfig;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRuleGroup;
import com.google.cloud.contactcenterinsights.v1.PhraseMatcher;
import java.io.IOException;

public class CreatePhraseMatcherAnyOf {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String projectId = "my_project_id";

    createPhraseMatcherAnyOf(projectId);
  }

  public static PhraseMatcher createPhraseMatcherAnyOf(String projectId) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct a phrase matcher that matches any of its rule groups.
      PhraseMatcher.Builder phraseMatcher =
          PhraseMatcher.newBuilder()
              .setDisplayName("PHONE_SERVICE")
              .setTypeValue(2)
              .setActive(true);

      // Construct a rule group to match the word "PHONE" or "CELLPHONE", ignoring case sensitivity.
      PhraseMatchRuleGroup.Builder ruleGroup = PhraseMatchRuleGroup.newBuilder().setTypeValue(2);

      String[] words = {"PHONE", "CELLPHONE"};
      for (String w : words) {
        PhraseMatchRule.Builder rule =
            PhraseMatchRule.newBuilder()
                .setQuery(w)
                .setConfig(
                    PhraseMatchRuleConfig.newBuilder()
                        .setExactMatchConfig(ExactMatchConfig.newBuilder().build())
                        .build());
        ruleGroup.addPhraseMatchRules(rule.build());
      }
      phraseMatcher.addPhraseMatchRuleGroups(ruleGroup.build());

      // Construct a parent resource.
      LocationName parent = LocationName.of(projectId, "us-central1");

      // Call the Insights client to create a phrase matcher.
      PhraseMatcher response = client.createPhraseMatcher(parent, phraseMatcher.build());
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const projectId = 'my_project_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createPhraseMatcherAnyOf() {
  const [phraseMatcher] = await client.createPhraseMatcher({
    parent: client.locationPath(projectId, 'us-central1'),
    phraseMatcher: {
      displayName: 'PHONE_SERVICE',
      type: 'ANY_OF',
      active: true,
      phraseMatchRuleGroups: [
        {
          type: 'ANY_OF',
          phraseMatchRules: [
            {
              query: 'PHONE',
              config: {
                exactMatchConfig: {},
              },
            },
            {
              query: 'CELLPHONE',
              config: {
                exactMatchConfig: {},
              },
            },
          ],
        },
      ],
    },
  });
  console.info(`Created ${phraseMatcher.name}`);
}
createPhraseMatcherAnyOf();

Detect "all of" a list of specified query strings

The following sample creates a PhraseMatcher object that tells CCAI Insights to add highlight labels to conversations that do contain the query words in the first phraseMatchRuleGroups but also do not contain the query words in the second phraseMatchRuleGroups.

REST

See the PhraseMatcherType and PhraseMatchRuleGroupType reference documentation for complete details. Substituting PHONE and CELLPHONE for the two query fields and SHIPPING and DELIVERY for the second two query fields should result in the sample output. The sample tells CCAI Insights to add highlight labels to conversations that contain "phone" and "cellphone" but do not contain "shipping" or "delivery".

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your GCP project ID.
  • LOCATION_ID: the location you chose for your Cloud Storage bucket. The only location currently available is us-central1.
  • DISPLAY_NAME: the human-readible name of the phrase matcher.
  • QUERY: the word or phrase to be matched.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/phraseMatchers

Request JSON body:

{
  "display_name": DISPLAY_NAME,
  "type": "ALL_OF",
  "active": true,
  "phrase_match_rule_groups": {
      "type": "ANY_OF",
      "phrase_match_rules": {
          "query": QUERY
          "config": {
              "exact_match_config": {
             }
          }
       },
       "phrase_match_rules": {
          "query": QUERY
          "config": {
              "exact_match_config": {
              }
           }
       }
      "phrase_match_rule_groups": {
          "type": "ALL_OF",
          "phrase_match_rules": {
              "query": QUERY
              "negated": "true"
              "config": {
                  "exact_match_config": {
                 }
              }
           },
           "phrase_match_rules": {
              "query": QUERY
              "negated": "true"
              "config": {
                  "exact_match_config": {
              }
           }
       }
  },
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/phraseMatchers/PHRASE_MATCHER_ID",
  "revisionId": "456456456",
  "revisionCreateTime": "2021-01-20T10:10:10.123000Z",
  "displayName": "NON_SHIPPING_PHONE_SERVICE",
  "type": "ALL_OF",
  "active": true,
  "phraseMatchRuleGroups": [
    {
      "type": "ANY_OF",
      "phraseMatchRules": [
        {
          "query": "PHONE",
          "config": {
            "exactMatchConfig": {}
          }
        },
        {
          "query": "CELLPHONE",
          "config": {
            "exactMatchConfig": {}
          }
        }
      ]
    },
    {
      "type": "ALL_OF",
      "phraseMatchRules": [
        {
          "query": "SHIPPING",
          "negated": true,
          "config": {
            "exactMatchConfig": {}
          }
        },
        {
          "query": "DELIVERY",
          "negated": true,
          "config": {
            "exactMatchConfig": {}
          }
        }
      ]
    }
  ],
  "activationUpdateTime": "2021-01-20T10:10:10.123000Z"
}

Python

from google.cloud import contact_center_insights_v1


def create_phrase_matcher_all_of(
    project_id: str,
) -> contact_center_insights_v1.PhraseMatcher:
    """Creates a phrase matcher that matches all specified queries.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.

    Returns:
        A phrase matcher.
    """
    # Construct a parent resource.
    parent = (
        contact_center_insights_v1.ContactCenterInsightsClient.common_location_path(
            project_id, "us-central1"
        )
    )

    # Construct a phrase matcher that matches all of its rule groups.
    phrase_matcher = contact_center_insights_v1.PhraseMatcher()
    phrase_matcher.display_name = "NON_SHIPPING_PHONE_SERVICE"
    phrase_matcher.type_ = (
        contact_center_insights_v1.PhraseMatcher.PhraseMatcherType.ALL_OF
    )
    phrase_matcher.active = True

    # Construct a rule group to match the word "PHONE" or "CELLPHONE", ignoring case sensitivity.
    rule_group_phone_or_cellphone = contact_center_insights_v1.PhraseMatchRuleGroup()
    rule_group_phone_or_cellphone.type_ = (
        contact_center_insights_v1.PhraseMatchRuleGroup.PhraseMatchRuleGroupType.ANY_OF
    )

    for word in ["PHONE", "CELLPHONE"]:
        rule = contact_center_insights_v1.PhraseMatchRule()
        rule.query = word
        rule.config.exact_match_config = contact_center_insights_v1.ExactMatchConfig()
        rule_group_phone_or_cellphone.phrase_match_rules.append(rule)
    phrase_matcher.phrase_match_rule_groups.append(rule_group_phone_or_cellphone)

    # Construct another rule group to not match the word "SHIPPING" or "DELIVERY", ignoring case sensitivity.
    rule_group_not_shipping_or_delivery = (
        contact_center_insights_v1.PhraseMatchRuleGroup()
    )
    rule_group_not_shipping_or_delivery.type_ = (
        contact_center_insights_v1.PhraseMatchRuleGroup.PhraseMatchRuleGroupType.ALL_OF
    )

    for word in ["SHIPPING", "DELIVERY"]:
        rule = contact_center_insights_v1.PhraseMatchRule()
        rule.query = word
        rule.negated = True
        rule.config.exact_match_config = contact_center_insights_v1.ExactMatchConfig()
        rule_group_not_shipping_or_delivery.phrase_match_rules.append(rule)
    phrase_matcher.phrase_match_rule_groups.append(rule_group_not_shipping_or_delivery)

    # Call the Insights client to create a phrase matcher.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    phrase_matcher = insights_client.create_phrase_matcher(
        parent=parent, phrase_matcher=phrase_matcher
    )

    print(f"Created {phrase_matcher.name}")
    return phrase_matcher

Java


import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.ExactMatchConfig;
import com.google.cloud.contactcenterinsights.v1.LocationName;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRule;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRuleConfig;
import com.google.cloud.contactcenterinsights.v1.PhraseMatchRuleGroup;
import com.google.cloud.contactcenterinsights.v1.PhraseMatcher;
import java.io.IOException;

public class CreatePhraseMatcherAllOf {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String projectId = "my_project_id";

    createPhraseMatcherAllOf(projectId);
  }

  public static PhraseMatcher createPhraseMatcherAllOf(String projectId) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct a phrase matcher that matches all of its rule groups.
      PhraseMatcher.Builder phraseMatcher =
          PhraseMatcher.newBuilder()
              .setDisplayName("NON_SHIPPING_PHONE_SERVICE")
              .setTypeValue(1)
              .setActive(true);

      // Construct a rule group to match the word "PHONE" or "CELLPHONE", ignoring case sensitivity.
      PhraseMatchRuleGroup.Builder ruleGroup1 = PhraseMatchRuleGroup.newBuilder().setTypeValue(2);

      String[] words1 = {"PHONE", "CELLPHONE"};
      for (String w : words1) {
        PhraseMatchRule.Builder rule =
            PhraseMatchRule.newBuilder()
                .setQuery(w)
                .setConfig(
                    PhraseMatchRuleConfig.newBuilder()
                        .setExactMatchConfig(ExactMatchConfig.newBuilder().build())
                        .build());
        ruleGroup1.addPhraseMatchRules(rule.build());
      }
      phraseMatcher.addPhraseMatchRuleGroups(ruleGroup1.build());

      // Construct another rule group to not match the word "SHIPPING" or "DELIVERY",
      // ignoring case sensitivity.
      PhraseMatchRuleGroup.Builder ruleGroup2 = PhraseMatchRuleGroup.newBuilder().setTypeValue(1);

      String[] words2 = {"SHIPPING", "DELIVERY"};
      for (String w : words2) {
        PhraseMatchRule.Builder rule =
            PhraseMatchRule.newBuilder()
                .setQuery(w)
                .setNegated(true)
                .setConfig(
                    PhraseMatchRuleConfig.newBuilder()
                        .setExactMatchConfig(ExactMatchConfig.newBuilder().build())
                        .build());
        ruleGroup2.addPhraseMatchRules(rule.build());
      }
      phraseMatcher.addPhraseMatchRuleGroups(ruleGroup2.build());

      // Construct a parent resource.
      LocationName parent = LocationName.of(projectId, "us-central1");

      // Call the Insights client to create a phrase matcher.
      PhraseMatcher response = client.createPhraseMatcher(parent, phraseMatcher.build());
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const projectId = 'my_project_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createPhraseMatcherAllOf() {
  const [phraseMatcher] = await client.createPhraseMatcher({
    parent: client.locationPath(projectId, 'us-central1'),
    phraseMatcher: {
      displayName: 'NON_SHIPPING_PHONE_SERVICE',
      type: 'ALL_OF',
      active: true,
      phraseMatchRuleGroups: [
        {
          type: 'ANY_OF',
          phraseMatchRules: [
            {
              query: 'PHONE',
              config: {
                exactMatchConfig: {},
              },
            },
            {
              query: 'CELLPHONE',
              config: {
                exactMatchConfig: {},
              },
            },
          ],
        },
        {
          type: 'ALL_OF',
          phraseMatchRules: [
            {
              query: 'SHIPPING',
              negated: true,
              config: {
                exactMatchConfig: {},
              },
            },
            {
              query: 'DELIVERY',
              negated: true,
              config: {
                exactMatchConfig: {},
              },
            },
          ],
        },
      ],
    },
  });
  console.info(`Created ${phraseMatcher.name}`);
}
createPhraseMatcherAllOf();