Create and analyze a conversation using the API

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

Prerequisites

  1. Make sure that the Storage, Speech-to-Text and Insights APIs are enabled on your Google Cloud Platform 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.

To learn how to bulk import conversations using client tooling, see the client tooling how-to guide.

Stage on Google Cloud Storage

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 Google 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 Google 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 currently unsupported and 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 allows you to listen to samples of the audio when you use the CCAI Insights Console.

REST & CMD LINE

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 GCP project ID.
  • LOCATION_ID: the location you chose for your Cloud Storage bucket. The only location currently available is us-central1.
  • 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.

HTTP method and URL:

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

Request JSON body:

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

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/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

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


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

/**
 * 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.

Create a new analysis

REST & CMD LINE

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 GCP project ID.
  • LOCATION_ID: the location you chose for your Cloud Storage bucket. The only location currently available is us-central1.
  • CONVERSATION_ID: the ID of the conversation you want to analyze. This value was returned in the `createConversation` response.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/analyses

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/operations/OPERATION_ID"
}

Python

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


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

/**
 * 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

REST & CMD LINE

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 GCP project ID.
  • LOCATION_ID: the location you chose for your Cloud Storage bucket. The only location currently available is us-central1.
  • CONVERSATION_ID: the ID of the conversation you want to analyze. This value was returned in the `createConversation` response.
  • PHRASE_MATCHER_ID(s): The IDs of the phrase matchers you want to use for the phrase matcher annotator. If left empty, all active phrase matchers will run.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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_matcher_ids": PHRASE_MATCHER_ID(S),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
  }
}

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/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.