Enable Summarization

The Summarization annotator returns summaries of your Conversational Insights conversations. Summarization is an Agent Assist feature that can be used with Insights only or in conjunction with your pre-existing Agent Assist conversation profiles. This page walks you through the process of enabling this feature.

Billing

Conversational Insights uses Agent Assist to generate conversation summaries. When you implement Summarization for Conversational Insights analyses, you will see an additional line item on your bill for Agent Assist API usage. See the Agent Assist pricing page for details.

AnnotatorSelector

As detailed in Billing, unlike other analysis annotators, the Summarization annotator is disabled by default. Enable it by setting AnnotatorSelector.run_summarization_annotator to true. Find more later in this document about configuring Summarization.

If AnnotatorSelector is specified in your requests, Insights only runs explicitly enabled annotators. So, to run annotators other than summarization, enable them in your request. For available options, see AnnotatorSelector.

Prerequisites

Enable the Dialogflow API and Contact Center AI Insights API for your Google Cloud project.

Summarize conversations using Insights analysis

You can generate a summary of a Insights conversation by creating an analysis for that conversation. For details, see Create and analyze a conversation using the API. Summarization is enabled and configured using the AnnotatorSelector when you create an analysis.

Refer to the Agent Assist language support documentation for a list of supported languages per summarization model.

Use the baseline Summarization model

A baseline model may be used without any further setup or customization. SummarizationConfig lists the baseline models available for use.

To generate summaries using the default baseline model:

  1. Set run_summarization_annotator to true.
  2. Set summarization_config.summarization_model to BASELINE_MODEL.

For example:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{annotator_selector: {run_summarization_annotator: true, summarization_config: {summarization_model: "BASELINE_MODEL"}}}' \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/analyses"

Use a custom Summarization model

If you use Agent Assist, you might already be using a custom Summarization model. You can provide a pre-existing Agent Assist conversation profile to Insights to get consistent Summarization results from both Agent Assist and Insights.

See the Agent Assist documentation for details about creating a conversation profile and training and configuring a custom Agent Assist Summarization model.

The following example creates a minimal conversation profile with no redaction and uses the baseline summarization model. First, create a SecuritySettings resource:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{display_name: "Summarization security settings"}' \
    "https://dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/global/securitySettings"

Next, create a conversation profile:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{display_name: "Summarization conversation profile", language_code: "en-US", security_settings: "projects/PROJECT_ID/locations/global/securitySettings/SECURITY_SETTINGS_ID", human_agent_assistant_config: {human_agent_suggestion_config: {feature_configs: {conversation_model_config: {baseline_model_version: "1.0"}, suggestion_feature: {type: "CONVERSATION_SUMMARIZATION"}}}}}' \
    "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/conversationProfiles"

Then, create an analysis and configure your annotator selector to use the conversation profile for Summarization:

  • Set run_summarization_annotator to true.
  • Set summarization_config.conversation_profile to the name of your conversation profile resource.

For example:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{annotator_selector: {run_summarization_annotator: true, summarization_config: {conversation_profile: "projects/PROJECT_ID/locations/global/conversationProfiles/PROFILE_ID"}}}' \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/analyses"

View Summarization results

Whether you use the baseline or a custom model, creating the analysis will return an operation ID. Poll the operation to track its progress. After the analysis is complete, query the conversation to see the analysis results:

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

Summary data will be populated in the response:

  • The summary will be stored as a runtimeAnnotation with the conversationSummarizationSuggestion field populated.
  • The conversation latestSummary field will be populated.

Subsequent analyses will add new runtime annotations, and the latest summary will be overwritten.

{
  "name": "projects/694347961123/locations/us-east1/conversations/14849016801257151776",
  "createTime": "2023-03-07T23:00:00.243902Z",
  "updateTime": "2023-03-07T23:00:01.167050Z",
  …
  "runtimeAnnotations": [
    {
      "annotationId": "14849016801257150641",
      "createTime": "2023-03-07T23:00:01.167050Z",
      "conversationSummarizationSuggestion": {
        "text": "A summary of your conversation."
        "textSections": {
          "DEFAULT_SECTION": "A summary of your conversation."
        }
      }
    }
  ],
  "latestSummary": {
    "text": "A summary of your conversation."
    "textSections": {
      "DEFAULT_SECTION": "A summary of your conversation."
    }
  }
}

Summarize conversations by default

Rather than specifying a Summarization configuration every time you create an analysis, you can configure a default annotator selector in your project settings. The configuration you set will be used for every analysis unless that analysis contains its own annotator selector. Be aware that each analysis will incur an additional charge.

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

Dialogflow runtime integration

If you enable Dialogflow runtime integration, any summaries created by Agent Assist can be viewed in Insights as well. As with other Insights summaries, summary content will be available as a runtime annotation and in the latest summary field.

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID",
  "dataSource": {
    "dialogflowSource": {
      "dialogflowConversation": "projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID",
      "conversationDataItem": "projects/PROJECT_ID/locations/us/conversationDatasets/DATASET_ID/conversationDataItems/DATA_ITEM_ID"
    }
  },
  …
  "runtimeAnnotations": [
    {
      "annotationId": "projects/PROJECT_ID/locations/us/conversationDatasets/DATASET_ID/conversationDataItems/DATA_ITEM_ID/conversationAnnotations/ANNOTATION_ID",
      "createTime": "2023-03-20T19:49:01.929940Z",
      "startBoundary": {},
      "endBoundary": {
        "transcriptIndex": 1
      },
      "answerFeedback": {},
      "conversationSummarizationSuggestion": {
        "text": "The customer had a query about the service. Closed conversation prior to the resolution.",
        "textSections": {
          "DEFAULT_SECTION": "The customer had a query about the service. Closed conversation prior to the resolution."
        }
      }
    }
  ],
  "latestSummary": {
    "text": "The customer had a query about the service. Closed conversation prior to the resolution.",
    "textSections": {
      "DEFAULT_SECTION": "The customer had a query about the service. Closed conversation prior to the resolution."
    }
  }
}

Filter conversations by summary content

When you list conversations in Insights, you can filter them by summary content. See list conversations for general instructions.

Insights supports the following filters for summary content:

// Filter for conversations that have a summary.
latest_summary:"*"

// Filter for conversations that have no summary.
-latest_summary:"*"

// Filter for conversations with a summary that contain a phrase.
latest_summary.text:"match this text"

// Filter for conversations with a summary that do not contain a phrase.
-latest_summary.text:"must not match this text"

View summaries in BigQuery

When you export your Insights data to BigQuery, summary data is also exported. See Export conversations to BigQuery for instructions on how to configure a BigQuery export.

Each conversation's latest summary is available in the latest_summary field:

bq query --use_legacy_sql=false 'SELECT conversationName, latestSummary.text FROM DATASET.TABLE'

All summaries, including the latest and any past summaries, are available as sentence-level annotations:

bq query --use_legacy_sql=false <<EOF
SELECT
  conversationName,
  sen.sentence,
  JSON_QUERY(JSON_VALUE(ant.annotationRecord), '$.text') AS summary_text
FROM
  DATASET.TABLE,
  UNNEST(`sentences`) AS sen,
  UNNEST(`sen.annotations`) AS ant
WHERE ant.type = 'CONVERSATION_SUMMARIZATION_SUGGESTION'
EOF