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 shows you how to enable the summarization annotator.

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

Unlike other analysis annotators, the summarization annotator is disabled by default. Enable it by setting AnnotatorSelector.run_summarization_annotator to true.

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

Prerequisites

Enable the Dialogflow API and Conversational 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. When you create an analysis, summarization is enabled and configured using the annotator selector.

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

You can use one of the following models to create a conversation summary:

  • BASELINE: Creates a summary.
  • BASELINE_MODEL_V2_0: Uses default sections (situation, action, and resolution).
  • generator: Uses 5 predefined sections with the ability to add more.

Use the baseline summarization model

You can use a baseline model without any further setup or customization. SummarizationConfig lists the baseline models available for use.

Follow these steps 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 generator summarization model

Agent Assist also offers LLM-powered summarization with custom sections with the generator model. You can use a generator model with predefined sections, or you can define custom sections.

Follow these steps to automatically generate summaries using the LLM-powered generator model.

  1. Follow the Agent Assist instructions to create a summarization generator
  2. Set run_summarization_annotator to true.
  3. Set summarization_config to generator.

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: {generator: '"projects/PROJECT_ID/locations/global/generators/generator_id"}}}' \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/

View summarization results

If you use the baseline or a custom model, creating the analysis returns 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 is populated in the response.

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

Subsequent analyses add new runtime annotations, and the latest summary is 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 is used for every analysis unless that analysis contains its own annotator selector. Be aware that each analysis incurs 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 is 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:

  • With a summary: latest_summary:"*"
  • No summary: -latest_summary:"*"
  • With a summary that has a phrase: latest_summary.text:"match this text"
  • With a summary with no 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. For instructions on how to configure a BigQuery export, see Export conversations to BigQuery.

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