Conversation Service
/
ConversationService
/
CountConversations.

Conversation Service

Our Conversation Service API comprehensively manages the entire lifecycle of conversations—enabling creation, updates (audio persistence, display name, language, sharing, skill, state, and metadata), retrieval, redaction or deletion of messages, tagging, event logging, batch operations, and final closure—providing robust end-to-end conversation management.

Languages
Servers
https://{api-domain}.cresta.com/

ConversationService

Operations

Starts a Conversation.

Request

This RPC is idempotent. If a conversation has already been started, it returns the existing conversation. The existing conversation will not be updated if it's different from the conversation in the request.

TODO(caibin.chen): Document the behavior of "re-starting" once decided.

Path
parentstringrequired

Resource name of the Conversation's parent.

Format: customers/{customer_id}/profiles/{profile_id}

conversationIdstringrequired

The ID of the Conversation to be created.

Query
closeAgentOtherConversationsboolean

Whether the agent's other conversations should be closed or not.

This can be used for the use cases that agents cannot handle multiple conversations simultaneously, e.g. in the voice case.

featureOverride.skipAnnotationsboolean

If set to true, no MomentAnnotation or ActionAnnotation will be generated for the conversation. This implies that no Policy will be evaluated against this conversation.

featureOverride.skipPiiRedationboolean

If set to true, no messages in this conversation will be PII-redacted.

featureOverride.synchronousBackendboolean

If set to true, all message/event/conversation close operations will wait until the backend processing is complete.

featureOverride.useOnboardingEmbeddingIndexboolean

If true, the embedding will be insert to a different index that's specifically used for conversations when onboarding a customer, i.e. indexes prefixed with manual-ingestion-embeddings-msg-multi-tenant-.

featureOverride.skipIndexOnCloseboolean

If set to true, closing the conversation won't trigger the process to index it in ElasticSearch.

featureOverride.skipAutoQaOnCloseboolean

If set to true, closing the conversation won't trigger AutoQA.

featureOverride.blockingCloseOtherConversationboolean

If close_other_conversation is set to true, setting this field to true will allow conversation service to close other conversations in a blocking way before starting the new conversation.

featureOverride.processWhenConversationCloseboolean

This flag only make sense when skip_annotations is set to true. If set to true, all messages & events will be processed by orchestrator upon conversation close. Used by near real time use cases.

featureOverride.skipInsightProcessingboolean

If set to true, this conversation will be excluded from insights processing.

Bodyapplication/jsonrequired

The Conversation to be created. If the Conversation already exists, this is ignored (i.e. it won't update the existing Conversation if values are different).

namestring

Resource name of the conversation.

This field does not need to be populated in the ConversationService.StartConversation request.

agentstring

The resource name of a User resource representing the agent answering the conversation.

agentInfoobject(Additional information about the speaker)
visitorobject(conversationVisitor)

Visitor is the person who contacts the agent in a conversation.

conversationCorrelationIdstring

The correlation ID is used to link multiple conversations. When a new conversation is created because of transferred from one agent to another, this ID can be used to connect the transferred conversations together. If CCasS platforms provide IDs for tracking transferred conversations or segments, use such ID as the value of this field.

skillstring

Skill annotates the type or topic of the conversation. Cresta may use different AI models according to the value of the skill.

In some platforms, agents can claim to be capable of one or more skills. The platform determines the skill requirement for the conversation and route the conversation to the agents that has the corresponding skill.

Clients should populate the skill if it's provided by the platform.

platformInfoobject(ConversationPlatformInfo)

Information of the associated conversation on the integrated platform.

startTimestring(date-time)

The time when this Conversation starts.

Clients can specify it if the platform provides start time for the conversation. If it's not specified, the wall time will be used when the first time ConversationService.StartConversation is called for this conversation.

audioPersistenceStatestring(ConversationAudioPersistenceState)

The state of how the corresponding audio stream is persisted.

  • AUDIO_PERSISTENCE_STATE_UNSPECIFIED: Invalid state.
  • NOT_PERSISTED: The Audio is not persisted. For text conversations, this is always the state. For voice conversations, this is the state before the audio is uploaded.
  • PERSISTED: The Audio is persisted successfully.
  • PERSIST_FAILED: The Audio failed to persist.
Default "AUDIO_PERSISTENCE_STATE_UNSPECIFIED"
Enum"AUDIO_PERSISTENCE_STATE_UNSPECIFIED""NOT_PERSISTED""PERSISTED""PERSIST_FAILED"
audioAnalysisobject(conversationAudioAnalysis)

Audio energy analysis result. Can be used to render wave form.

persistedAudioDurationstring

The duration of the audio.

statestring(The state of the conversation)
  • STATE_UNSPECIFIED: Default value. It's valid to use it in StartConversationRequest and invalid to use it in UpdateConversationStateRequest.
  • LIVE: The conversation is open. Agents and visitors are likely to send new messages to the conversation. Agent assist features are turned on for this conversation.

The conversation's end_time is not populated in this state.

  • CLOSED: The conversation is closed. Agents and visitors are unlikely to send new messages to the conversation. Agent assist features are turned off for this conversation.

The conversation's end_time is populated in this state.

Default "STATE_UNSPECIFIED"
Enum"STATE_UNSPECIFIED""LIVE""CLOSED"
raiseHandStatestring(ConversationRaiseHandState)

The raise hand state of the conversation.

  • RAISE_HAND_STATE_UNSPECIFIED: Unspecified - do not use.
  • RAISE_HAND_ABSENT: There was no raised hand in the conversation.
  • RAISE_HAND_ACTIVE: There is an unanswered raised hand in this conversation. The raised hand maps to an action. (see collaboration service)
  • RAISE_HAND_HANDLED: All raised hands of this conversation have been handled by a manager.
Default "RAISE_HAND_STATE_UNSPECIFIED"
Enum"RAISE_HAND_STATE_UNSPECIFIED""RAISE_HAND_ABSENT""RAISE_HAND_ACTIVE""RAISE_HAND_HANDLED"
languageCodestring

The language code for the ConversationMessage texts in the Conversation.

It must be a valid IETF BCP-47 language codes, such as en-US or de-CH. It must be in the list of supported languages of the parent Profile. Cresta falls back to the Profile's default language if this field is not populated or the conditions above are not met.

This doesn't change the UI language.

channelstring(ConversationChannel)

Conversation channel, e.g. text chat or voice.

  • CHANNEL_UNSPECIFIED: Default value.
  • CHAT: This conversation is from a text chat.
  • VOICE: This conversation is from a voice call.
  • EMAIL: This conversation is from an email thread. Each message is an email in the thread.
Default "CHANNEL_UNSPECIFIED"
Enum"CHANNEL_UNSPECIFIED""CHAT""VOICE""EMAIL"
sourcestring(conversationConversationSource)

The source of the conversation.

A conversation can be created in multiple ways. This field indicates where and how was the conversation created.

  • SOURCE_UNSPECIFIED: This is the default case which means the conversation came from the production traffic between real agents and visitors.
  • STUDIO_SYNTHETIC_ANNOTATION: The conversation was created by Studio when users create a synthetic label.
  • STUDIO_USER_DEFINED: The conversation is a synthetic conversation created by Studio users for purposes like regression testing or simulation.
  • STUDIO_SCRAPED_FROM_PLATFORM: The legacy conversations that Studio scraped from customers' platforms and don't exist in the production storage. This ingestion method has been deprecated.
  • OPERA_SYNTHETIC: The conversation is opera synthetic conversation used for opera simulation It should not be included in agent progression
  • OPERA_SIMULATION: The conversation is opera simulation generated from opera synthetic conversation It should not be included in agent progression
  • BOT: The conversation is created by the bot service. It should be hidden in the director live view but visible in the closed chat view.
  • INGESTION_PIPELINE: (The enum name probably should've been name ONBOARDING_INGESTION, given we'll soon have batch conversation ingestion) The conversation is created by the ingestion pipeline when the customer first onboards. For conversations with this source, we'll use the INGEST_TIME_BASED approach to index its embeddings. For other purposes, it should behave the same as SOURCE_UNSPECIFIED (i.e. live traffic)
  • OPERA_PREVIEW: The conversation is generated for opera preview by copying an existing conversation. It should not be included in agent progression.
  • KA_SIMULATION: The conversation is generated by Knowledge Assistant simulation. It should not be included in agent progression.
  • VA_SIMULATION: The conversation is generated by Virtual Agent simulation. It should not be included in agent progression.
Default "SOURCE_UNSPECIFIED"
Enum"SOURCE_UNSPECIFIED""STUDIO_SYNTHETIC_ANNOTATION""STUDIO_USER_DEFINED""STUDIO_SCRAPED_FROM_PLATFORM""OPERA_SYNTHETIC""OPERA_SIMULATION""BOT""INGESTION_PIPELINE""OPERA_PREVIEW""KA_SIMULATION"
metadataobject

The key and values of the conversation metadata field.

Each key can be mapped to one or more values. If this field is populated in StartConversationRequest for an non-existent Conversation, the value will be stored into the conversation. A ConversationEvent will be created for provided metadata values.

If this field is populated in StartConversationRequest for an existing Conversation, they will be ignored. Values can also be added by [ConversationService.UpsertConversationMetadata][]. See the metadata_values field of [UpsertConversationMetadataRequest][] for more information.

displayNamestring

Display name of the conversation.

sharingStatestring(ConversationSharingState)

Conversation Sharing State.

  • SHARING_STATE_UNSPECIFIED: Default value. All conversations will be created with this sharing state value.
  • SHARING_STATE_SHARED: This conversation is shared with all managers. Conversation of OPERA_SYNTHETIC source can be changed to shared state.
Default "SHARING_STATE_UNSPECIFIED"
Enum"SHARING_STATE_UNSPECIFIED""SHARING_STATE_SHARED"
policyOverrideobject(ConversationPolicyOverride)

Policy override used in the conversation.

usecasestring(The resource name of the use case. Can be assigned explicitly by the client or implicitly by the conversation service. The client is responsible for reassigning the use-case when changing conversation attributes. Format: customers/{customer_id}/profiles/{profile_id}/usecases/{usecase_id})
corruptionStatestring(Indicates the state of the corrupted conversation. This field is used by the upstream ingestion pipeline to mark the conversation as corrupted so that the downstream can take action based on this state. Keep this in sync with `sql-schema/protos/conversation/conversation.proto:CorruptionState`)
  • CORRUPTION_STATE_UNSPECIFIED: Unspecified default value. Either the conversation is not corrupted or the corruption scan is not yet performed for this conversation.
  • CORRUPTED_REINGEST: The conversation is considered as fully corrupted and should be totally removed and re-ingested. This tag is used by the ingestion pipeline (upstream) to mark conversations that are corrupted. The ingestion pipeline (downstream) will remove the conversation and re-ingest it from platform.
  • CORRUPTED_STITCH: The conversation is considered as partially corrupted with missing data. And should be stitched with additional data. This tag is used by the ingestion pipeline (upstream) to mark conversations that are incomplete / partially corrupted. The ingestion pipeline (downstream) will fetch from the platform and stitch the missing part to the existing conversation.
  • SKIPPED_TOO_SHORT: The conversation is too short to be processed. Normally the causes are:
  1. IVR machine where the visitor hangs up before reaching an agent, or just reached the agent.
  2. The actual agent <-> visitor conversation is too short. The end result is either there is no audio at all, or the audio is only a few bytes large. This tag can be populated by either the real-time handling or the offline pipeline. We should skip these conversations when scanning, counting and backfilling for corrupted conversations.
  • CORRUPTED_REDACT: The conversation is failed with transcription and will be fully-redacted to mitigate the risk of PII leakage.
Default "CORRUPTION_STATE_UNSPECIFIED"
Enum"CORRUPTION_STATE_UNSPECIFIED""CORRUPTED_REINGEST""CORRUPTED_STITCH""SKIPPED_TOO_SHORT""CORRUPTED_REDACT"
virtualAgentstring

If this is a conversation with a Virtual Agent, the Virtual Agent ID will be set.

ingestedByJobstring(Only set when this conversation is created or fixed by an ingestion job Format: customers/{customer_id}/profiles/{profile_id}/jobs/{job_id})
transferInfoobject(ConversationTransferInfo)

Information about how this conversation is transferred from the previous conversation.

persistenceStatestring(ConversationPersistenceState)

Indicates the persistence state of the conversation.

  • PERSISTENCE_STATE_UNSPECIFIED: Default value.
  • TO_BE_DELETED: The conversation is marked as to be deleted.
Default "PERSISTENCE_STATE_UNSPECIFIED"
Enum"PERSISTENCE_STATE_UNSPECIFIED""TO_BE_DELETED"
multiLanguageModestring(ConversationMultiLanguageMode)

Indicates how multi-language transcription is handled if the conversation messages are transcribed from audio.

  • MULTI_LANGUAGE_MODE_UNSPECIFIED: Default value. Same as NONE.
  • NONE: No multi-language transcription is applied. The ASR engine uses a single language model to transcribe the audio.
  • LANGUAGE_DETECTION: Use language detection to detect the languages of the audio. When detected language changes, the ASR engine is switched to the language model that's most suitable for the detected language.
  • MULTI_LANGUAGE_TRANSCRIPTION: Use multi-language ASR engine to transcribe the audio .
Default "MULTI_LANGUAGE_MODE_UNSPECIFIED"
Enum"MULTI_LANGUAGE_MODE_UNSPECIFIED""NONE""LANGUAGE_DETECTION""MULTI_LANGUAGE_TRANSCRIPTION"
curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations/{conversationId}:start' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "agent": "string",
    "agentInfo": {
      "displayName": "string",
      "platformSpeakerId": "string"
    },
    "visitor": {
      "platformVisitorId": "string",
      "displayName": "string"
    },
    "conversationCorrelationId": "string",
    "skill": "string",
    "platformInfo": {
      "platformConversationId": "string",
      "platformAccountId": "string",
      "originalEventData": {},
      "platformConversationUri": "string",
      "platformIntegration": "string"
    },
    "startTime": "2019-08-24T14:15:22Z",
    "audioPersistenceState": "AUDIO_PERSISTENCE_STATE_UNSPECIFIED",
    "audioAnalysis": {
      "agentAudioEnergy": [
        0.1
      ],
      "visitorAudioEnergy": [
        0.1
      ]
    },
    "persistedAudioDuration": "string",
    "state": "STATE_UNSPECIFIED",
    "raiseHandState": "RAISE_HAND_STATE_UNSPECIFIED",
    "languageCode": "string",
    "channel": "CHANNEL_UNSPECIFIED",
    "source": "SOURCE_UNSPECIFIED",
    "metadata": {
      "property1": {
        "values": [
          {
            "numberValue": 0.1,
            "stringValue": "string",
            "booleanValue": true
          }
        ],
        "source": "SOURCE_UNSPECIFIED"
      },
      "property2": {
        "values": [
          {
            "numberValue": 0.1,
            "stringValue": "string",
            "booleanValue": true
          }
        ],
        "source": "SOURCE_UNSPECIFIED"
      }
    },
    "displayName": "string",
    "sharingState": "SHARING_STATE_UNSPECIFIED",
    "policyOverride": {
      "policyIds": [
        "string"
      ],
      "respectConversationAgentFilter": true,
      "respectLanguageCodeFilter": true,
      "respectTimeRangeFilter": true,
      "policyHistoryIds": [
        "string"
      ]
    },
    "usecase": "string",
    "corruptionState": "CORRUPTION_STATE_UNSPECIFIED",
    "virtualAgent": "string",
    "ingestedByJob": "string",
    "transferInfo": {
      "previousConversation": "string",
      "participantInteractionType": "PARTICIPANT_INTERACTION_TYPE_UNSPECIFIED"
    },
    "persistenceState": "PERSISTENCE_STATE_UNSPECIFIED",
    "multiLanguageMode": "MULTI_LANGUAGE_MODE_UNSPECIFIED"
  }'

Responses

A successful response.

Bodyapplication/json
conversationobject(Conversation is a session of chat/call messages. Next ID: 35)
outcomestring(StartConversationResponseOutcome)

How is the Conversation started.

  • OUTCOME_UNSPECIFIED: Default value. Won't be used.
  • CREATED: A new Conversation is created.
  • ALREADY_EXISTS: The conversation already exists and is reused.

Note: The existing conversation is not updated to match the request.

Default "OUTCOME_UNSPECIFIED"
Enum"OUTCOME_UNSPECIFIED""CREATED""ALREADY_EXISTS"
Response
application/json
{
  "conversation": {
    "name": "string",
    "agent": "string",
    "participants": [ … ],
    "agentInfo": { … },
    "agentUserName": "string",
    "team": "string",
    "visitor": { … },
    "conversationCorrelationId": "string",
    "skill": "string",
    "platformInfo": { … },
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z",
    "audioPersistenceState": "AUDIO_PERSISTENCE_STATE_UNSPECIFIED",
    "persistedAudioUri": "string",
    "audioAnalysis": { … },
    "persistedAudioDuration": "string",
    "legacyChatId": 0,
    "state": "STATE_UNSPECIFIED",
    "raiseHandState": "RAISE_HAND_STATE_UNSPECIFIED",
    "languageCode": "string",
    "channel": "CHANNEL_UNSPECIFIED",
    "source": "SOURCE_UNSPECIFIED",
    "metadata": { … },
    "displayName": "string",
    "sharingState": "SHARING_STATE_UNSPECIFIED",
    "policyOverride": { … },
    "usecase": "string",
    "createTime": "2019-08-24T14:15:22Z",
    "corruptionState": "CORRUPTION_STATE_UNSPECIFIED",
    "virtualAgent": "string",
    "ingestedByJob": "string",
    "transferInfo": { … },
    "persistenceState": "PERSISTENCE_STATE_UNSPECIFIED",
    "multiLanguageMode": "MULTI_LANGUAGE_MODE_UNSPECIFIED"
  },
  "outcome": "OUTCOME_UNSPECIFIED"
}

CountConversations.

Request

Path
parentstringrequired

Resource name of the parent.

Format: customers/{customer_id}/profiles/{profile_id}

Query
filter.rangeStartTimestring(date-time)

Definition for the start/end range is the conversation start/end time overlaps with the filter start/end time.

Filter for conversation time lower bound, inclusive.

filter.rangeEndTimestring(date-time)

Filter for conversation time upper bound, inclusive.

filter.usersOrTeamsUsersArray of strings

Filter by user resource names. All users AND teams are ORed together. Format: customers/<customer_id>/users/<user_id>.

filter.usersOrTeamsTeamsArray of strings

Filter by team resource names. All users AND teams are ORed together. Format: customers/<customer_id>/teams/<team_id>.

filter.usersOrGroups.usersArray of strings

Filter by user resource names. All users AND groups are ORed together. Format: customers/<customer_id>/users/<user_id>.

filter.usersOrGroups.groupsArray of strings

Filter by group resource names. All users AND groups are ORed together. Format: customers/<customer_id>/groups/<group_id>.

filter.platformConversationIdstring

Filter by platform_conversation_id.

filter.minConversationDurationstring

Filter by min conversation duration, inclusive.

filter.maxConversationDurationstring

Filter by max conversation duration, inclusive.

filter.messageKeywordstring

Filter by keyword appearing in the message. This is a raw string, no regex.

filter.actionsArray of strings

Filter by existence of certain Action Annotations. Format: "customers/{customer_id}/profiles/{profile_id}/actions/{action_id}" Deprecated: use action_filters instead.

filter.liveFilterstring

Filter by whether the conversation is live.

  • LIVE_FILTER_UNSPECIFIED: Invalid State. Do not use.
  • LIVE_ONLY: Only return lives conversations.
  • CLOSED_ONLY: Only return closed conversations.
  • ANY: Do not limit on closed or live conversations. Use this option to check if conversations with specific criteria exist disregarding if they are closed or not. e.g. when not sure if exists by platform ID but may have failed to close the conversation.
Default "LIVE_FILTER_UNSPECIFIED"
Enum"LIVE_FILTER_UNSPECIFIED""LIVE_ONLY""CLOSED_ONLY""ANY"
filter.includeDevUsersboolean

If true, include dev users. Otherwise, do not include dev users.

filter.commentsFilterstring

Filter by comment conditions, e.g. whether conversation has comments.

  • COMMENTS_FILTER_UNSPECIFIED: Invalid State. Do not use.
  • HAS_NO_COMMENTS: Only return conversations without comments.
  • HAS_COMMENTS: Only return conversations with comments.
Default "COMMENTS_FILTER_UNSPECIFIED"
Enum"COMMENTS_FILTER_UNSPECIFIED""HAS_NO_COMMENTS""HAS_COMMENTS"
filter.languageCodestring

Filter by [language_code][Conversation.language_code] of the Conversation. Deprecated: use language_codes instead.

filter.languageCodesArray of strings

Filter by [language_code][Conversation.language_code] of the Conversation.

filter.usecaseIdsArray of strings

Filter by usecase ID.

filter.sourcesArray of strings

Filter by the source of the conversation. If unspecified or empty, only the conversations came from prod traffic will be returned. i.e. synthetic conversations are excluded.

  • SOURCE_UNSPECIFIED: This is the default case which means the conversation came from the production traffic between real agents and visitors.
  • STUDIO_SYNTHETIC_ANNOTATION: The conversation was created by Studio when users create a synthetic label.
  • STUDIO_USER_DEFINED: The conversation is a synthetic conversation created by Studio users for purposes like regression testing or simulation.
  • STUDIO_SCRAPED_FROM_PLATFORM: The legacy conversations that Studio scraped from customers' platforms and don't exist in the production storage. This ingestion method has been deprecated.
  • OPERA_SYNTHETIC: The conversation is opera synthetic conversation used for opera simulation It should not be included in agent progression
  • OPERA_SIMULATION: The conversation is opera simulation generated from opera synthetic conversation It should not be included in agent progression
  • BOT: The conversation is created by the bot service. It should be hidden in the director live view but visible in the closed chat view.
  • INGESTION_PIPELINE: (The enum name probably should've been name ONBOARDING_INGESTION, given we'll soon have batch conversation ingestion) The conversation is created by the ingestion pipeline when the customer first onboards. For conversations with this source, we'll use the INGEST_TIME_BASED approach to index its embeddings. For other purposes, it should behave the same as SOURCE_UNSPECIFIED (i.e. live traffic)
  • OPERA_PREVIEW: The conversation is generated for opera preview by copying an existing conversation. It should not be included in agent progression.
  • KA_SIMULATION: The conversation is generated by Knowledge Assistant simulation. It should not be included in agent progression.
  • VA_SIMULATION: The conversation is generated by Virtual Agent simulation. It should not be included in agent progression.
Items Enum"SOURCE_UNSPECIFIED""STUDIO_SYNTHETIC_ANNOTATION""STUDIO_USER_DEFINED""STUDIO_SCRAPED_FROM_PLATFORM""OPERA_SYNTHETIC""OPERA_SIMULATION""BOT""INGESTION_PIPELINE""OPERA_PREVIEW""KA_SIMULATION"
filter.sharingStateArray of strings

Filter by the sharing state of the conversation. If unspecified, conversations came from any sharing states will be returned. The usecase for this is in Opera Simulator that supports retrieval of sharing synthetic conversation only.

  • SHARING_STATE_UNSPECIFIED: Default value. All conversations will be created with this sharing state value.
  • SHARING_STATE_SHARED: This conversation is shared with all managers. Conversation of OPERA_SYNTHETIC source can be changed to shared state.
Items Enum"SHARING_STATE_UNSPECIFIED""SHARING_STATE_SHARED"
filter.liveAssistFilterstring

Filters on the raised hand / live assist status of the conversation. Should work for both live and closed conversations.

  • LIVE_ASSIST_FILTER_UNSPECIFIED: Invalid state. Do not use.
  • RAISE_HAND_UNANSWERED: Only return covnersations with a raise hand without live assist.
  • RAISE_HAND_ANSWERED: Only return conversations with both raise hand and live assist.
  • LIVE_ASSIST_WITHOUT_RAISE_HAND: Only return conversations with live assist without raise hand.
Default "LIVE_ASSIST_FILTER_UNSPECIFIED"
Enum"LIVE_ASSIST_FILTER_UNSPECIFIED""RAISE_HAND_UNANSWERED""RAISE_HAND_ANSWERED""LIVE_ASSIST_WITHOUT_RAISE_HAND"
filter.scorecardTemplateNameFiltersArray of strings

Filters on scorecard template names. The filters are combined with or, conversations that have any of the specified scorecard template names will be returned. Can only be used with closed conversations.

filter.scorecardStatusFilterstring

Filters on the status of the scorecards.

  • SCORECARD_STATUS_FILTER_UNSPECIFIED: Invalid state. Do not use.
  • MANUALLY_SUBMITTED: Only return conversations with a scorecard that was manually submitted.
  • DRAFT: Only return conversations with a scorecard that is in draft status.
  • AUTO: Only return conversations with a auto scorecard.
Default "SCORECARD_STATUS_FILTER_UNSPECIFIED"
Enum"SCORECARD_STATUS_FILTER_UNSPECIFIED""MANUALLY_SUBMITTED""DRAFT""AUTO"
filter.audioLinkStatusstring

Filters on the audio link status of the conversation.

  • AUDIO_LINK_STATUS_UNSPECIFIED: With or without audio link doesn't matter. Default value.
  • EXIST: Only return conversations with a non-empty (not NULL nor "") combined_audio_link field.
  • EMPTY: Only return conversations with a empty (NULL or "") combined_audio_link field.
Default "AUDIO_LINK_STATUS_UNSPECIFIED"
Enum"AUDIO_LINK_STATUS_UNSPECIFIED""EXIST""EMPTY"
filter.channelstring

Filters the conversations by channel.

  • CHANNEL_UNSPECIFIED: Default value.
  • CHAT: This conversation is from a text chat.
  • VOICE: This conversation is from a voice call.
  • EMAIL: This conversation is from an email thread. Each message is an email in the thread.
Default "CHANNEL_UNSPECIFIED"
Enum"CHANNEL_UNSPECIFIED""CHAT""VOICE""EMAIL"
filter.corruptionStatesArray of strings

Filters the conversations by their corruption states.

Ex: Pass the [CORRUPTION_STATE_UNSPECIFIED] to only get the uncorrupted conversations. Pass [CORRUPTED_REINGEST, SKIPPED_TOO_SHORT] to get conversations that are with either one of the states.

  • CORRUPTION_STATE_UNSPECIFIED: Unspecified default value. Either the conversation is not corrupted or the corruption scan is not yet performed for this conversation.
  • CORRUPTED_REINGEST: The conversation is considered as fully corrupted and should be totally removed and re-ingested. This tag is used by the ingestion pipeline (upstream) to mark conversations that are corrupted. The ingestion pipeline (downstream) will remove the conversation and re-ingest it from platform.
  • CORRUPTED_STITCH: The conversation is considered as partially corrupted with missing data. And should be stitched with additional data. This tag is used by the ingestion pipeline (upstream) to mark conversations that are incomplete / partially corrupted. The ingestion pipeline (downstream) will fetch from the platform and stitch the missing part to the existing conversation.
  • SKIPPED_TOO_SHORT: The conversation is too short to be processed. Normally the causes are:
  1. IVR machine where the visitor hangs up before reaching an agent, or just reached the agent.
  2. The actual agent <-> visitor conversation is too short. The end result is either there is no audio at all, or the audio is only a few bytes large. This tag can be populated by either the real-time handling or the offline pipeline. We should skip these conversations when scanning, counting and backfilling for corrupted conversations.
  • CORRUPTED_REDACT: The conversation is failed with transcription and will be fully-redacted to mitigate the risk of PII leakage.
Items Enum"CORRUPTION_STATE_UNSPECIFIED""CORRUPTED_REINGEST""CORRUPTED_STITCH""SKIPPED_TOO_SHORT""CORRUPTED_REDACT"
filter.conversationCorrelationIdstring

Filter by conversation correlation id.

filter.conversationCorrelationOrPlatformIdstring

Filter by conversation correlation id OR platform id - i.e. if either of those two values has the provided value the conversation is treated as a match.

filter.calibrationStatusFilterstring

Filters on the status of the scorecards.

  • SCORECARD_STATUS_FILTER_UNSPECIFIED: Invalid state. Do not use.
  • MANUALLY_SUBMITTED: Only return conversations with a scorecard that was manually submitted.
  • DRAFT: Only return conversations with a scorecard that is in draft status.
  • AUTO: Only return conversations with a auto scorecard.
Default "SCORECARD_STATUS_FILTER_UNSPECIFIED"
Enum"SCORECARD_STATUS_FILTER_UNSPECIFIED""MANUALLY_SUBMITTED""DRAFT""AUTO"
filter.scorecardSubmitterNameFiltersArray of strings

Filters on the scorecard submitter.

filter.persistenceStatesArray of strings

Filters the conversations by their persistence states. By default, only the conversations with state PERSISTENCE_STATE_UNSPECIFIED will be returned.

Ex: Pass the [TO_BE_DELETED] to only get the conversations has "TO_BE_DELETED". Pass [PERSISTENCE_STATE_UNSPECIFIED, TO_BE_DELETED] to get conversations that are with either one of the states.

  • PERSISTENCE_STATE_UNSPECIFIED: Default value.
  • TO_BE_DELETED: The conversation is marked as to be deleted.
Items Enum"PERSISTENCE_STATE_UNSPECIFIED""TO_BE_DELETED"
aggregateboolean

Whether or not run aggregate functions and return the corresponding results. e.g. average duration of the conversations.

curl -i -X GET \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations:count'

Responses

A successful response.

Bodyapplication/json
countinteger(int32)

The number of conversations which satisfy the filters.

averageDurationstring

The average duration of conversations which satisfy the filters.

Response
application/json
{
  "count": 0,
  "averageDuration": "string"
}

FetchConversationByLegacyID

Request

FetchConversationByLegacyID takes a legacy chat ID and returns the conversation if it exists. The API is used by voice subscription service to provide audio energy analysis for call recording. Eventually, we should use conversation ID instead.

Path
parentstringrequired

Resource name of the parent.

Format: customers/{customer_id}/profiles/{profile_id}

Query
legacyChatIdinteger(int32)required

Legacy primary key from the app.chats table for the conversation.

Deprecated: This field is added for migration purposes. New features should not use this ID.

curl -i -X GET \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations:fetchByLegacyId?legacyChatId=0'

Responses

A successful response.

Bodyapplication/json
conversationobject(Conversation is a session of chat/call messages. Next ID: 35)
Response
application/json
{
  "conversation": {
    "name": "string",
    "agent": "string",
    "participants": [ … ],
    "agentInfo": { … },
    "agentUserName": "string",
    "team": "string",
    "visitor": { … },
    "conversationCorrelationId": "string",
    "skill": "string",
    "platformInfo": { … },
    "startTime": "2019-08-24T14:15:22Z",
    "endTime": "2019-08-24T14:15:22Z",
    "audioPersistenceState": "AUDIO_PERSISTENCE_STATE_UNSPECIFIED",
    "persistedAudioUri": "string",
    "audioAnalysis": { … },
    "persistedAudioDuration": "string",
    "legacyChatId": 0,
    "state": "STATE_UNSPECIFIED",
    "raiseHandState": "RAISE_HAND_STATE_UNSPECIFIED",
    "languageCode": "string",
    "channel": "CHANNEL_UNSPECIFIED",
    "source": "SOURCE_UNSPECIFIED",
    "metadata": { … },
    "displayName": "string",
    "sharingState": "SHARING_STATE_UNSPECIFIED",
    "policyOverride": { … },
    "usecase": "string",
    "createTime": "2019-08-24T14:15:22Z",
    "corruptionState": "CORRUPTION_STATE_UNSPECIFIED",
    "virtualAgent": "string",
    "ingestedByJob": "string",
    "transferInfo": { … },
    "persistenceState": "PERSISTENCE_STATE_UNSPECIFIED",
    "multiLanguageMode": "MULTI_LANGUAGE_MODE_UNSPECIFIED"
  }
}