FetchConversationByLegacyID

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

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:

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.

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

FetchConversationByPlatformID

Request

Path

parentstringrequired

Resource name of the parent.

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

Query

platformConversationIdstringrequired

The platform conversation ID.

platformAccountIdstringrequired

The platform account ID, which could be populated using the user ID in order to support transfer-call use case. See: https://github.com/cresta/go-servers/blob/7070ef9edc98d7ca3ca6bb4fa2d0b4a97b33d97a/voice-integration/gowalter/internal/voicesession/ingestedvoicesession.go#L276-L280.

curl -i -X GET \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations:fetchByPlatformId?platformAccountId=string&platformConversationId=string'

Responses

A successful response.

Bodyapplication/json

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

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

The returned conversations, which are sorted by start_time in the ascending order.

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"
  },
  "conversations": [
    { … }
  ]
}

Conversation Service

ConversationService

CountConversations.

Request

Responses

Was this helpful?

FetchConversationByLegacyID

Request

Responses

Was this helpful?

FetchConversationByPlatformID

Request

Responses

Was this helpful?