ListConversations.

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.

Servers

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

ConversationService

Operations

Deletes a tag from a conversation

Request

Path

parentstringrequired

The resource name of the conversation to be untagged.

tagIdstringrequired

The resource id of the tag to be removed from the conversation.

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

Responses

A successful response.

Bodyapplication/json

object(Response of [ConversationService.DeleteConversationTag][])

Response

application/json

{}

ListConversations.

Request

Path

parentstringrequired

Resource name of the parent.

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

Bodyapplication/jsonrequired

pageSizeinteger(int32)

The maximum number of conversations to return. If unspecified, at most 50 conversations will be returned.

pageTokenstring

A page token, received from a previous ListConversations call. Provide this to retrieve the subsequent page.

filterobject(Filter conditions for getting/counting conversations. Within a filter field, repeated conditions are OR. Between different filter fields, conditions are AND. Next ID: 36)

curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations' \
  -H 'Content-Type: application/json' \
  -d '{
    "pageSize": 0,
    "pageToken": "string",
    "filter": {
      "rangeStartTime": "2019-08-24T14:15:22Z",
      "rangeEndTime": "2019-08-24T14:15:22Z",
      "users": [
        {
          "userName": "string",
          "teamName": "string"
        }
      ],
      "usersOrTeamsUsers": [
        "string"
      ],
      "usersOrTeamsTeams": [
        "string"
      ],
      "usersOrGroups": {
        "users": [
          "string"
        ],
        "groups": [
          "string"
        ]
      },
      "platformConversationId": "string",
      "minConversationDuration": "string",
      "maxConversationDuration": "string",
      "messageKeyword": "string",
      "moments": [
        {
          "momentWithAdherence": [
            {
              "momentName": "string",
              "adherence": "ADHERENCE_TYPE_UNSPECIFIED"
            }
          ]
        }
      ],
      "actions": [
        "string"
      ],
      "liveFilter": "LIVE_FILTER_UNSPECIFIED",
      "includeDevUsers": true,
      "commentsFilter": "COMMENTS_FILTER_UNSPECIFIED",
      "languageCode": "string",
      "languageCodes": [
        "string"
      ],
      "usecaseIds": [
        "string"
      ],
      "sources": [
        "SOURCE_UNSPECIFIED"
      ],
      "sharingState": [
        "SHARING_STATE_UNSPECIFIED"
      ],
      "liveAssistFilter": "LIVE_ASSIST_FILTER_UNSPECIFIED",
      "hintNameFilters": [
        {
          "hintNames": [
            "string"
          ]
        }
      ],
      "scorecardTemplateNameFilters": [
        "string"
      ],
      "scorecardStatusFilter": "SCORECARD_STATUS_FILTER_UNSPECIFIED",
      "actionFilters": [
        {
          "actionName": [
            "string"
          ]
        }
      ],
      "audioLinkStatus": "AUDIO_LINK_STATUS_UNSPECIFIED",
      "channel": "CHANNEL_UNSPECIFIED",
      "behaviors": [
        {
          "behaviorWithAdherence": [
            {
              "behaviorName": "string",
              "adherence": "ADHERENCE_TYPE_UNSPECIFIED"
            }
          ]
        }
      ],
      "corruptionStates": [
        "CORRUPTION_STATE_UNSPECIFIED"
      ],
      "conversationCorrelationId": "string",
      "conversationCorrelationOrPlatformId": "string",
      "calibrationStatusFilter": "SCORECARD_STATUS_FILTER_UNSPECIFIED",
      "scorecardSubmitterNameFilters": [
        "string"
      ],
      "persistenceStates": [
        "PERSISTENCE_STATE_UNSPECIFIED"
      ]
    }
  }'

Responses

A successful response.

Bodyapplication/json

conversationsArray of objects(Conversation is a session of chat/call messages. Next ID: 35)read-only

The returned conversations.

metadataobject(Map of conversation resource name to additional metadata)read-only

totalConversationsinteger(int32)read-only

Total number of conversations in the system. Note that this number is limited as defined by: request.pageSize * 10 + 1 i.e. the returned count will at most show the beginning of an 11th page.

filteredConversationsinteger(int32)read-only

Number of conversations matching the provided filters. Note that this number is limited as defined by: request.pageSize * 10 + 1 i.e. the returned count will at most show the beginning of an 11th page.

nextPageTokenstring

Token is used to retrieve the next page.

Response

application/json

{
  "conversations": [
    { … }
  ],
  "metadata": {
    "property1": { … },
    "property2": { … }
  },
  "totalConversations": 0,
  "filteredConversations": 0,
  "nextPageToken": "string"
}

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:

IVR machine where the visitor hangs up before reaching an agent, or just reached the agent.
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"
}

Conversation Service

ConversationService

Deletes a tag from a conversation

Request

Responses

Was this helpful?

ListConversations.

Request

Responses

Was this helpful?

Starts a Conversation.

Request

Responses

Was this helpful?

Conversation Service

ConversationService

Deletes a tag from a conversation

Request

Responses

Was this helpful?

ListConversations.

RequestExpand all

Responses

Was this helpful?

Starts a Conversation.

RequestExpand all

Responses

Was this helpful?

Request

Request