Set a TTL (time-to-live) on conversation data

Overview

There are two ways to set a conversation's expiration time in Insights: using the expire_time field, or using the ttl field. You can use the expire_time field set a timestamp indicating when the conversation will expire, or the ttl field to set a time duration (in seconds) until the conversation will expire. If a conversation has both an expire_time and ttl value, Insights uses the expire_time value.

Conversations set to expire using either the expire_time or ttl field will be deleted 24 hours after the specified expiration time is reached. See the Conversation resource documentation for complete details. This page demonstrates how to set a TTL, both for individual conversations and for all conversations in a given project.

If a conversation is not set to expire, it will remain in Insights indefinitely, though conversations can always be manually deleted.

Create a conversation with a TTL value

The following sample illustrates how to set a TTL value for a single, newly-created conversation using the ttl field in a Conversation resource.

Permissions required for this task

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

contactcenterinsights.conversations.create

REST

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.
MEDIUM: set to either PHONE_CALL or CHAT depending on the data type. If unspecified the default value is PHONE_CALL.
SECONDS: the time-to-live (time until the conversation expires) in seconds and fractions of a second.

HTTP method and URL:

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

Request JSON body:

{
  "data_source": {
    "gcs_source": {
      "transcript_uri": "TRANSCRIPT_URI"
    }
  },
  "medium": "MEDIUM",
  "ttl": {
    "seconds": "SECONDS"
  }
}

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": "555"
        }
      },
      ...
    ]
  },
  "medium": "CHAT",
  "duration": "5.00s",
  "turnCount": 10,
  "startTime": "2021-01-10T10:10:10.123000Z"
  "expireTime":"2021-01-21T10:10:10.123000Z",
}

Python

To authenticate to 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
from google.protobuf import duration_pb2


def create_conversation_with_ttl(
    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 with a TTL value.

    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

    # Construct a TTL.
    ttl = duration_pb2.Duration()
    ttl.seconds = 86400
    conversation.ttl = ttl

    # 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 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 com.google.protobuf.Duration;
import java.io.IOException;

public class CreateConversationWithTtl {

  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";

    createConversationWithTtl(projectId, transcriptUri, audioUri);
  }

  public static Conversation createConversationWithTtl(
      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)
              .setTtl(Duration.newBuilder().setSeconds(86400).build())
              .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 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 createConversationWithTtl() {
  const [conversation] = await client.createConversation({
    parent: client.locationPath(projectId, 'us-central1'),
    conversation: {
      dataSource: {
        gcsSource: {
          transcriptUri: transcriptUri,
          audioUri: audioUri,
        },
      },
      medium: 'CHAT',
      ttl: {
        seconds: 86400,
      },
    },
  });
  console.info(`Created ${conversation.name}`);
}
createConversationWithTtl();

Set a project-level TTL for all incoming conversations

The following code sample demonstrates how to set a project-level TTL using the conversation_ttl field in a Settings resource. This TTL will be applied to all incoming conversations that don't specify a separate expiration time or a different TTL value.

Permissions required for this task

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

contactcenterinsights.settings.update

REST

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

PROJECT_ID: your Google Cloud project ID.
SECONDS: the time-to-live (time until the conversation expires) in seconds and fractions of a second.

HTTP method and URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/settings?updateMask=conversation_ttl

Request JSON body:

{
  "conversation_ttl": {
    "seconds": "SECONDS"
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

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/settings?updateMask=conversation_ttl"

PowerShell (Windows)

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/settings?updateMask=conversation_ttl" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/$PROJECT/locations/us-central1/settings",
  "createTime": "2021-01-20T10:10:10.123000Z",
  "updateTime": "2021-01-20T11:11:11.456000Z",
  "conversationTtl": "86400s"
}

Python

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

from google.api_core import protobuf_helpers
from google.cloud import contact_center_insights_v1
from google.protobuf import duration_pb2


def set_project_ttl(project_id: str) -> None:
    """Sets a project-level TTL for all incoming conversations.

    Args:
        project_id:
            The project identifier. For example, 'my-project'.

    Returns:
        None.
    """
    # Construct a settings resource.
    settings = contact_center_insights_v1.Settings()
    settings.name = (
        contact_center_insights_v1.ContactCenterInsightsClient.settings_path(
            project_id, "us-central1"
        )
    )

    conversation_ttl = duration_pb2.Duration()
    conversation_ttl.seconds = 86400
    settings.conversation_ttl = conversation_ttl

    # Construct an update mask to only update the fields that are set on the settings resource.
    update_mask = protobuf_helpers.field_mask(None, type(settings).pb(settings))

    # Construct an Insights client that will authenticate via Application Default Credentials.
    # See authentication details at https://cloud.google.com/docs/authentication/production.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()

    # Call the Insights client to set a project-level TTL.
    insights_client.update_settings(settings=settings, update_mask=update_mask)

    # Call the Insights client to get the project-level TTL to confirm that it was set.
    new_conversation_ttl = insights_client.get_settings(
        name=settings.name
    ).conversation_ttl
    print(
        "Set TTL for all incoming conversations to {} day".format(
            new_conversation_ttl.days
        )
    )

Java

To authenticate to 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.Settings;
import com.google.cloud.contactcenterinsights.v1.SettingsName;
import com.google.protobuf.Duration;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class SetProjectTtl {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String projectId = "my_project_id";

    setProjectTtl(projectId);
  }

  public static void setProjectTtl(String projectId) 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 settings resource.
      SettingsName name = SettingsName.of(projectId, "us-central1");
      Settings settings =
          Settings.newBuilder()
              .setName(name.toString())
              .setConversationTtl(Duration.newBuilder().setSeconds(86400).build())
              .build();

      // Construct an update mask.
      FieldMask updateMask = FieldMask.newBuilder().addPaths("conversation_ttl").build();

      // Call the Insights client to set a project-level TTL.
      Settings response = client.updateSettings(settings, updateMask);
      System.out.printf("Set TTL for all incoming conversations to 1 day");
    }
  }
}

Node.js

To authenticate to 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 projectId = 'my_project_id';

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

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

async function setProjectTtl() {
  await client.updateSettings({
    settings: {
      name: client.settingsPath(projectId, 'us-central1'),
      conversationTtl: {
        seconds: 86400,
      },
    },
    updateMask: {
      paths: ['conversation_ttl'],
    },
  });
  console.info('Set TTL for all incoming conversations to 1 day');
}
setProjectTtl();