REST Resource: projects.locations.conversations

Resource: Conversation

The conversation resource.

JSON representation
{
  "name": string,
  "dataSource": {
    object (ConversationDataSource)
  },
  "createTime": string,
  "updateTime": string,
  "startTime": string,
  "languageCode": string,
  "agentId": string,
  "labels": {
    string: string,
    ...
  },
  "transcript": {
    object (Transcript)
  },
  "medium": enum (Medium),
  "duration": string,
  "turnCount": integer,
  "latestAnalysis": {
    object (Analysis)
  },
  "runtimeAnnotations": [
    {
      object (RuntimeAnnotation)
    }
  ],
  "dialogflowIntents": {
    string: {
      object (DialogflowIntent)
    },
    ...
  },
  "callMetadata": {
    object (CallMetadata)
  },

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Fields
name

string

Immutable. The resource name of the conversation. Format: projects/{project}/locations/{location}/conversations/{conversation}

dataSource

object (ConversationDataSource)

The source of the audio and transcription for the conversation.

createTime

string (Timestamp format)

Output only. The time at which the conversation was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. The most recent time at which the conversation was updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

startTime

string (Timestamp format)

The time at which the conversation started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

languageCode

string

A user-specified language code for the conversation.

agentId

string

An opaque, user-specified string representing the human agent who handled the conversation.

labels

map (key: string, value: string)

A map for the user to specify any custom fields. A maximum of 20 labels per conversation is allowed, with a maximum of 256 characters per entry.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

transcript

object (Transcript)

Output only. The conversation transcript.

medium

enum (Medium)

Immutable. The conversation medium, if unspecified will default to PHONE_CALL.

duration

string (Duration format)

Output only. The duration of the conversation.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

turnCount

integer

Output only. The number of turns in the conversation.

latestAnalysis

object (Analysis)

Output only. The conversation's latest analysis, if one exists.

runtimeAnnotations[]

object (RuntimeAnnotation)

Output only. The annotations that were generated during the customer and agent interaction.

dialogflowIntents

map (key: string, value: object (DialogflowIntent))

Output only. All the matched Dialogflow intents in the call. The key corresponds to a Dialogflow intent, format: projects/{project}/agent/{agent}/intents/{intent}

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

callMetadata

object (CallMetadata)

Call-specific metadata.

Union field expiration. A time to live expiration setting, can be either a specified timestamp or a duration from the time that the conversation creation request was received. Conversations with an expiration set will be removed up to 24 hours after the specified time. expiration can be only one of the following:
expireTime

string (Timestamp format)

The time at which this conversation should expire. After this time, the conversation data and any associated analyses will be deleted.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

ttl

string (Duration format)

Input only. The TTL for this resource. If specified, then this TTL will be used to calculate the expire time.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

CallMetadata

Call-specific metadata.

JSON representation
{
  "customerChannel": integer,
  "agentChannel": integer
}
Fields
customerChannel

integer

The audio channel that contains the customer.

agentChannel

integer

The audio channel that contains the agent.

ConversationDataSource

The conversation source, which is a combination of transcript and audio.

JSON representation
{

  // Union field source can be only one of the following:
  "gcsSource": {
    object (GcsSource)
  },
  "dialogflowSource": {
    object (DialogflowSource)
  }
  // End of list of possible types for union field source.
}
Fields
Union field source. The source of the conversation. source can be only one of the following:
gcsSource

object (GcsSource)

A Cloud Storage location specification for the audio and transcript.

dialogflowSource

object (DialogflowSource)

The source when the conversation comes from Dialogflow.

GcsSource

A Cloud Storage source of conversation data.

JSON representation
{
  "audioUri": string,
  "transcriptUri": string
}
Fields
audioUri

string

Cloud Storage URI that points to a file that contains the conversation audio.

transcriptUri

string

Immutable. Cloud Storage URI that points to a file that contains the conversation transcript.

DialogflowSource

A Dialogflow source of conversation data.

JSON representation
{
  "dialogflowConversation": string,
  "audioUri": string
}
Fields
dialogflowConversation

string

Output only. The name of the Dialogflow conversation that this conversation resource is derived from. Format: projects/{project}/locations/{location}/conversations/{conversation}

audioUri

string

Cloud Storage URI that points to a file that contains the conversation audio.

Transcript

A message representing the transcript of a conversation.

JSON representation
{
  "transcriptSegments": [
    {
      object (TranscriptSegment)
    }
  ]
}
Fields
transcriptSegments[]

object (TranscriptSegment)

A list of sequential transcript segments that comprise the conversation.

TranscriptSegment

A segment of a full transcript.

JSON representation
{
  "messageTime": string,
  "text": string,
  "confidence": number,
  "words": [
    {
      object (WordInfo)
    }
  ],
  "languageCode": string,
  "channelTag": integer,
  "segmentParticipant": {
    object (ConversationParticipant)
  },
  "dialogflowSegmentMetadata": {
    object (DialogflowSegmentMetadata)
  },
  "sentiment": {
    object (SentimentData)
  }
}
Fields
messageTime

string (Timestamp format)

The time that the message occurred, if provided.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

text

string

The text of this segment.

confidence

number

A confidence estimate between 0.0 and 1.0 of the fidelity of this segment. A default value of 0.0 indicates that the value is unset.

words[]

object (WordInfo)

A list of the word-specific information for each word in the segment.

languageCode

string

The language code of this segment as a BCP-47 language tag. Example: "en-US".

channelTag

integer

For conversations derived from multi-channel audio, this is the channel number corresponding to the audio from that channel. For audioChannelCount = N, its output values can range from '1' to 'N'. A channel tag of 0 indicates that the audio is mono.

segmentParticipant

object (ConversationParticipant)

The participant of this segment.

dialogflowSegmentMetadata

object (DialogflowSegmentMetadata)

CCAI metadata relating to the current transcript segment.

sentiment

object (SentimentData)

The sentiment for this transcript segment.

WordInfo

Word-level info for words in a transcript.

JSON representation
{
  "startOffset": string,
  "endOffset": string,
  "word": string,
  "confidence": number
}
Fields
startOffset

string (Duration format)

Time offset of the start of this word relative to the beginning of the total conversation.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

endOffset

string (Duration format)

Time offset of the end of this word relative to the beginning of the total conversation.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

word

string

The word itself. Includes punctuation marks that surround the word.

confidence

number

A confidence estimate between 0.0 and 1.0 of the fidelity of this word. A default value of 0.0 indicates that the value is unset.

ConversationParticipant

The call participant speaking for a given utterance.

JSON representation
{
  "dialogflowParticipant": string,
  "obfuscatedExternalUserId": string,
  "role": enum (Role),

  // Union field participant can be only one of the following:
  "dialogflowParticipantName": string,
  "userId": string
  // End of list of possible types for union field participant.
}
Fields
dialogflowParticipant
(deprecated)

string

Deprecated. Use dialogflowParticipantName instead. The name of the Dialogflow participant. Format: projects/{project}/locations/{location}/conversations/{conversation}/participants/{participant}

obfuscatedExternalUserId

string

Obfuscated user ID from Dialogflow.

role

enum (Role)

The role of the participant.

Union field participant.

participant can be only one of the following:

dialogflowParticipantName

string

The name of the participant provided by Dialogflow. Format: projects/{project}/locations/{location}/conversations/{conversation}/participants/{participant}

userId

string

A user-specified ID representing the participant.

DialogflowSegmentMetadata

Metadata from Dialogflow relating to the current transcript segment.

JSON representation
{
  "smartReplyAllowlistCovered": boolean
}
Fields
smartReplyAllowlistCovered

boolean

Whether the transcript segment was covered under the configured smart reply allowlist in Agent Assist.

RuntimeAnnotation

An annotation that was generated during the customer and agent interaction.

JSON representation
{
  "annotationId": string,
  "createTime": string,
  "startBoundary": {
    object (AnnotationBoundary)
  },
  "endBoundary": {
    object (AnnotationBoundary)
  },
  "answerFeedback": {
    object (AnswerFeedback)
  },

  // Union field data can be only one of the following:
  "articleSuggestion": {
    object (ArticleSuggestionData)
  },
  "faqAnswer": {
    object (FaqAnswerData)
  },
  "smartReply": {
    object (SmartReplyData)
  },
  "smartComposeSuggestion": {
    object (SmartComposeSuggestionData)
  },
  "dialogflowInteraction": {
    object (DialogflowInteractionData)
  }
  // End of list of possible types for union field data.
}
Fields
annotationId

string

The unique identifier of the annotation. Format: projects/{project}/locations/{location}/conversationDatasets/{dataset}/conversationDataItems/{data_item}/conversationAnnotations/{annotation}

createTime

string (Timestamp format)

The time at which this annotation was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

startBoundary

object (AnnotationBoundary)

The boundary in the conversation where the annotation starts, inclusive.

endBoundary

object (AnnotationBoundary)

The boundary in the conversation where the annotation ends, inclusive.

answerFeedback

object (AnswerFeedback)

The feedback that the customer has about the answer in data.

Union field data. The data in the annotation. data can be only one of the following:
articleSuggestion

object (ArticleSuggestionData)

Agent Assist Article Suggestion data.

faqAnswer

object (FaqAnswerData)

Agent Assist FAQ answer data.

smartReply

object (SmartReplyData)

Agent Assist Smart Reply data.

smartComposeSuggestion

object (SmartComposeSuggestionData)

Agent Assist Smart Compose suggestion data.

dialogflowInteraction

object (DialogflowInteractionData)

Dialogflow interaction data.

ArticleSuggestionData

Agent Assist Article Suggestion data.

JSON representation
{
  "title": string,
  "uri": string,
  "confidenceScore": number,
  "metadata": {
    string: string,
    ...
  },
  "queryRecord": string,
  "source": string
}
Fields
title

string

Article title.

uri

string

Article URI.

confidenceScore

number

The system's confidence score that this article is a good match for this conversation, ranging from 0.0 (completely uncertain) to 1.0 (completely certain).

metadata

map (key: string, value: string)

Map that contains metadata about the Article Suggestion and the document that it originates from.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

queryRecord

string

Name of the query record. Format: projects/{project}/locations/{location}/queryRecords/{queryRecord}

source

string

The knowledge document that this answer was extracted from. Format: projects/{project}/knowledgeBases/{knowledge_base}/documents/{document}

FaqAnswerData

Agent Assist frequently-asked-question answer data.

JSON representation
{
  "answer": string,
  "confidenceScore": number,
  "question": string,
  "metadata": {
    string: string,
    ...
  },
  "queryRecord": string,
  "source": string
}
Fields
answer

string

The piece of text from the source knowledge base document.

confidenceScore

number

The system's confidence score that this answer is a good match for this conversation, ranging from 0.0 (completely uncertain) to 1.0 (completely certain).

question

string

The corresponding FAQ question.

metadata

map (key: string, value: string)

Map that contains metadata about the FAQ answer and the document that it originates from.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

queryRecord

string

Name of the query record. Format: projects/{project}/locations/{location}/queryRecords/{queryRecord}.

source

string

The knowledge document that this answer was extracted from. Format: projects/{project}/knowledgeBases/{knowledge_base}/documents/{document}.

SmartReplyData

Agent Assist Smart Reply data.

JSON representation
{
  "reply": string,
  "confidenceScore": number,
  "metadata": {
    string: string,
    ...
  },
  "queryRecord": string
}
Fields
reply

string

The content of the reply.

confidenceScore

number

The system's confidence score that this reply is a good match for this conversation, ranging from 0.0 (completely uncertain) to 1.0 (completely certain).

metadata

map (key: string, value: string)

Map that contains metadata about the Smart Reply and the document from which it originates.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

queryRecord

string

Name of the query record. Format: projects/{project}/locations/{location}/queryRecords/{queryRecord}

SmartComposeSuggestionData

Agent Assist Smart Compose suggestion data.

JSON representation
{
  "suggestion": string,
  "confidenceScore": number,
  "metadata": {
    string: string,
    ...
  },
  "queryRecord": string
}
Fields
suggestion

string

The content of the suggestion.

confidenceScore

number

The system's confidence score that this suggestion is a good match for this conversation, ranging from 0.0 (completely uncertain) to 1.0 (completely certain).

metadata

map (key: string, value: string)

Map that contains metadata about the Smart Compose suggestion and the document from which it originates.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

queryRecord

string

Name of the query record. Format: projects/{project}/locations/{location}/queryRecords/{queryRecord}

DialogflowInteractionData

Dialogflow interaction data.

JSON representation
{
  "dialogflowIntentId": string,
  "confidence": number
}
Fields
dialogflowIntentId

string

The Dialogflow intent resource path. Format: projects/{project}/agent/{agent}/intents/{intent}

confidence

number

The confidence of the match ranging from 0.0 (completely uncertain) to 1.0 (completely certain).

AnswerFeedback

The feedback that the customer has about a certain answer in the conversation.

JSON representation
{
  "correctnessLevel": enum (CorrectnessLevel),
  "clicked": boolean,
  "displayed": boolean
}
Fields
correctnessLevel

enum (CorrectnessLevel)

The correctness level of an answer.

clicked

boolean

Indicates whether an answer or item was clicked by the human agent.

displayed

boolean

Indicates whether an answer or item was displayed to the human agent in the agent desktop UI.

CorrectnessLevel

The correctness level of an answer.

Enums
CORRECTNESS_LEVEL_UNSPECIFIED Correctness level unspecified.
NOT_CORRECT Answer is totally wrong.
PARTIALLY_CORRECT Answer is partially correct.
FULLY_CORRECT Answer is fully correct.

DialogflowIntent

The data for a Dialogflow intent. Represents a detected intent in the conversation, e.g. MAKES_PROMISE.

JSON representation
{
  "displayName": string
}
Fields
displayName

string

The human-readable name of the intent.

Methods

calculateStats

Gets conversation statistics.

create

Creates a conversation.

delete

Deletes a conversation.

get

Gets a conversation.

list

Lists conversations.

patch

Updates a conversation.