Use the API to bulk import conversations

Learn how you can import audio and transcripts with their metadata using the API.

Prerequisites

1. Make sure that the Cloud Storage, Speech-to-Text, Data Loss Prevention, and Insights APIs are enabled on your Google Cloud project.
2. Make sure that your conversation data is staged in a Cloud Storage bucket. See the Cloud Storage documentation for information about creating a bucket.
   1. The Speech-to-Text and Contact Center AI Insights service agents must have access to the objects in your Cloud Storage bucket. The email address for the service agents use the following format, respectively:

      [e-mail]
      [e-mail]

3. If you opt to import conversation metadata, ensure that metadata files are in their own bucket and the metadata filenames match their corresponding conversation filename. For example, a conversation with the Cloud Storage URI gs://transcript-bucket-name/conversation.mp3, should have a corresponding metadata file such as gs://metadata-bucket-name/conversation.json.

Note: The IngestConversations API does not support import of transcripts together with audio. If you have both conversation audio and transcripts, make sure to stage them in separate buckets. Linking audio with transcripts is also not supported by the API, unlike the UploadConversation API.

Import conversation data

Note: Conversations already ingested into CCAI Insights will be skipped in subsequent import attempts.

Note: Only one concurrent bulk import operation is allowed.

Transcripts

Chat transcripts must be supplied as JSON-formatted files that match the CCAI conversation data format.

Voice transcripts can be supplied in the CCAI conversation data format or as the returned speech recognition result of a Speech-to-Text API transcription. The response is identical for synchronous and asynchronous recognition across all Speech-to-Text API versions.

Audio

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Contact Center AI Insights uses Cloud Speech-to-Text batch recognition to transcribe audio. By default, transcription is done for the en-US language using the telephony model. Redaction is not done unless redaction configs are explicitly supplied in the project Settings or in the IngestConversationsRequest.

For detailed information on how to optionally configure transcription and redaction for bulk audio import, refer to the instructions for the single audio import API, which apply here.

Metadata

Conversation metadata files must be supplied as JSON-formatted files in a bucket specified in the gcs_source.metadata_bucket_uri field of the IngestConversationsRequest. CCAI Insights will populate conversation QualityMetadata if found in the file. Additionally, any custom metadata provided in the custom_metadata_keys field of the request will be stored in the conversation labels. Up to 100 labels are supported per conversation.

See the following example of a valid metadata file containing both quality and custom metadata.

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
}

Sample Commands

Permissions required for this task

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

• contactcenterinsights.conversations.create

REST

Refer to the conversations:ingest API endpoint for complete details.

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

• PROJECT_ID: your Google Cloud Platform project ID.
• GCS_BUCKET_URI: the Cloud Storage URI that points to the bucket containing the conversation transcripts. May contain a prefix. For example gs://BUCKET_NAME or gs://BUCKET_NAME/PREFIX. Wildcards are not supported.
• MEDIUM: set to either PHONE_CALL or CHAT depending on the data type. If unspecified the default value is PHONE_CALL.
• AGENT_ID: Optional. Agent Id for the entire bucket.

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:ingest

Request JSON body:

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

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:ingest"

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:ingest" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

Poll the operation

An IngestConversations request returns a long-running operation. Long-running methods are asynchronous, and the operation might not yet 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.

Cancel the operation

Permissions required for this task

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

• contactcenteraiplatform.operations.cancel

REST

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

• PROJECT_ID: your Google Cloud Platform project ID.
• OPERATION_ID: the ID of the conversation you want to analyze. This value was returned when you created the operation.

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/operations/OPERATION_ID:cancel

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

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/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{}