Create and analyze a conversation using the API

Prerequisites

1. Make sure that the Cloud Storage, Speech-to-Text and Insights APIs are enabled on your Google Cloud project.

Overview

Conversations can be viewed in Contact Center AI Insights after a corresponding Conversation object has been created and analyzed. This how-to guide walks you through the process of creating and analyzing a conversation using the REST API. If preferred, you can also perform these actions using the CCAI Insights console.

Stage on Cloud Storage

Permissions required for this task

To perform this task, you must have the following permissions:

• storage.objects.list
• storage.objects.create

The following sections describe how to upload your own conversation data to a Cloud Storage bucket in order to ingest it into CCAI Insights. If you would like to try the API without using your own data, CCAI Insights provides a publicly-available conversation dataset in the following location: gs://cloud-samples-data/ccai/chat_sample.json.

Chat Conversation

1. Upload the conversation's chat transcript as an object in your Cloud Storage bucket. Make a note of the object path, which is formatted as gs://<bucket>/<object>.

   The chat transcript file must be supplied as a JSON-formatted file that matches the CCAI conversation data format.

Voice Conversation

1. Upload the conversation's audio and transcript files as objects in your Cloud Storage bucket. Make a note of the two object paths, which are formatted as gs://<bucket>/<object>. The transcript files must be the returned result of a Cloud Speech-to-Text API transcription. Specifically, it must match the response returned from audio recognition. The response is identical for synchronous recognition and asynchronous recognition across all Speech-to-Text API versions. Other transcription formats are unsupported and will result in an error during conversation analysis.

   Note: Only audio with two channels is supported. More or fewer channels will result in an error during conversation analysis.

Create a conversation

You have the option of creating a conversation using either transcripts of chat conversations or transcripts of phone call audio plus the audio data itself. Creating a conversation that includes the audio data lets you listen to samples of the audio when you use the CCAI Insights console.

Note: If you are creating a conversation using audio data, the transcript files must be the returned result of a Cloud Speech-to-Text API transcription.

Permissions required for this task

To perform this task, you must have the following permissions:

• contactcenterinsights.conversations.create

REST

Refer to the conversations:create API endpoint for complete details. See the Conversation resource reference documentation for more information about configuring the request body. If the languageCode field is not set, CCAI Insights will automatically infer it.

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

• PROJECT_ID: your Google Cloud project ID.
• TRANSCRIPT_URI: the Cloud Storage URI that points to a file containing the conversation transcript.
• AUDIO_URI: the Cloud Storage URI that points to a file containing the conversation audio. Omit this field if you are transcribing transcript data only.
• MEDIUM: set to either PHONE_CALL or CHAT depending on the data type. If unspecified the default value is PHONE_CALL.

Note: All the examples are using the global Contact Center AI Insights instance. Refer to Regionalization for instructions on using regional instances.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations

Request JSON body:

{
  "dataSource": {
    "gcsSource": {
      "transcriptUri": "TRANSCRIPT_URI",
      "audioUri": "AUDIO_URI"
    }
  },
  "medium": "MEDIUM"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID",
  "dataSource": {
    "gcsSource": {
      "transcriptUri": "gs://cloud-samples-data/ccai/chat_sample.json"
    }
  },
  "createTime": "2021-01-20T10:10:10.123000Z",
  "transcript": {
    "transcriptSegments": [
      ...
      {
        "text": "Thanks for confirming",
        "words": [
          {
            "word": "Thanks"
          },
          {
            "word": "for"
          },
          {
            "word": "confirming"
          }
        ],
        "languageCode": "en-US",
        "channelTag": 2,
        "messageTime": "2021-01-10T10:10:15.123000Z",
        "segmentParticipant": {
          "role": "HUMAN_AGENT",
          "userId": "2"
        }
      },
      ...
    ]
  },
  "medium": "CHAT",
  "duration": "5.00s",
  "turnCount": 10,
  "startTime": "2021-01-10T10:10:10.123000Z"
}

Python

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import contact_center_insights_v1


def create_conversation(
    project_id: str,
    transcript_uri: str = "gs://cloud-samples-data/ccai/chat_sample.json",
    audio_uri: str = "gs://cloud-samples-data/ccai/voice_6912.txt",
) -> contact_center_insights_v1.Conversation:
    """Creates a conversation.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.
        transcript_uri:
            The Cloud Storage URI that points to a file that contains the
            conversation transcript. Format is 'gs://{bucket_name}/{file.json}'.
            For example, 'gs://cloud-samples-data/ccai/chat_sample.json'.
        audio_uri:
            The Cloud Storage URI that points to a file that contains the
            conversation audio. Format is 'gs://{bucket_name}/{file.json}'.
            For example, 'gs://cloud-samples-data/ccai/voice_6912.txt'.

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

    # Construct a conversation.
    conversation = contact_center_insights_v1.Conversation()
    conversation.data_source.gcs_source.transcript_uri = transcript_uri
    conversation.data_source.gcs_source.audio_uri = audio_uri
    conversation.medium = contact_center_insights_v1.Conversation.Medium.CHAT

    # Call the Insights client to create a conversation.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    conversation = insights_client.create_conversation(
        parent=parent, conversation=conversation
    )

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

Java

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.Conversation;
import com.google.cloud.contactcenterinsights.v1.ConversationDataSource;
import com.google.cloud.contactcenterinsights.v1.CreateConversationRequest;
import com.google.cloud.contactcenterinsights.v1.GcsSource;
import com.google.cloud.contactcenterinsights.v1.LocationName;
import java.io.IOException;

public class CreateConversation {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my_project_id";
    String transcriptUri = "gs://cloud-samples-data/ccai/chat_sample.json";
    String audioUri = "gs://cloud-samples-data/ccai/voice_6912.txt";

    createConversation(projectId, transcriptUri, audioUri);
  }

  public static Conversation createConversation(
      String projectId, String transcriptUri, String audioUri) 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 parent resource.
      LocationName parent = LocationName.of(projectId, "us-central1");

      // Construct a conversation.
      Conversation conversation =
          Conversation.newBuilder()
              .setDataSource(
                  ConversationDataSource.newBuilder()
                      .setGcsSource(
                          GcsSource.newBuilder()
                              .setTranscriptUri(transcriptUri)
                              .setAudioUri(audioUri)
                              .build())
                      .build())
              .setMedium(Conversation.Medium.CHAT)
              .build();

      // Construct a request.
      CreateConversationRequest request =
          CreateConversationRequest.newBuilder()
              .setParent(parent.toString())
              .setConversation(conversation)
              .build();

      // Call the Insights client to create a conversation.
      Conversation response = client.createConversation(request);
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my_project_id';
// const transcriptUri = 'gs://cloud-samples-data/ccai/chat_sample.json';
// const audioUri = 'gs://cloud-samples-data/ccai/voice_6912.txt';

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

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

async function createConversation() {
  const [conversation] = await client.createConversation({
    parent: client.locationPath(projectId, 'us-central1'),
    conversation: {
      dataSource: {
        gcsSource: {
          transcriptUri: transcriptUri,
          audioUri: audioUri,
        },
      },
      medium: 'CHAT',
    },
  });
  console.info(`Created ${conversation.name}`);
}
createConversation();

Analyze a conversation

Once a Conversation object is created in CCAI Insights, it must be analyzed in order to produce useful results. A single conversation can be analyzed many times, and each separate analysis creates a new Analysis object.

An analysis runs a series of annotators against your conversation data and returns the results in the response. By default, the analysis will run all available annotators. Optionally, you can configure the analysis to run specified annotators only.

An analysis is a long-running operation. Calling the CreateAnalysis method creates an Operation object that represents the long-running process. After the operation is complete, the Operation object contains the result. You can poll the Operation object to check for completion.

Note: If the languageCode field is not set, CCAI Insights will automatically infer it. Only English (all dialects) is supported for analyses.

Create a new analysis

Permissions required for this task

To perform this task, you must have the following permissions:

• contactcenterinsights.analyses.create

REST

Refer to the conversations.analyses:create API endpoint for complete details.

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

• PROJECT_ID: your Google Cloud project ID.
• CONVERSATION_ID: the ID of the conversation you want to analyze. This value was returned in the `createConversation` response.

Note: All the examples are using the global Contact Center AI Insights instance. Refer to Regionalization for instructions on using regional instances.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, 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 an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

To authenticate to CCAI Insights, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

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

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

async function createAnalysis() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
createAnalysis();

(Optional) Configure an analysis

Permissions required for this task

To perform this task, you must have the following permissions:

• contactcenterinsights.analyses.create

REST

Refer to the conversations.analyses:create API endpoint for complete details. Include any annotators that you want to run in the annotatorSelector object and set them to true. Any annotators not included will default to false. If you don't specify any annotators in the annotatorSelector object all annotators will be run.

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

• PROJECT_ID: your Google Cloud project ID.
• ANALYSIS_PERCENTAGE: Percentage of the conversations to randomly analyze.
• PHRASE_MATCHER(s): The fully qualified phrase matcher resource names of the phrase matchers you want to use for the phrase matcher annotator. If left empty, all active phrase matchers will run.
• ISSUE_MODEL(s): The fully qualified resource names of the issue models you want to use for the issue model annotator. Only works if run_issue_model_annotator is true. If left empty, all deployed issue models will run. Currently limited to 1 deployed model.

Note: All the examples are using the global Contact Center AI Insights instance. Refer to Regionalization for instructions on using regional instances.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

Request JSON body:

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Poll the operation

Creating an analysis returns a long-running operation. Long-running methods are asynchronous, and the operation might not be completed when the method returns a response. You can poll the operation to check on its status. See the long-running operations page for details and code samples.