Conversation Service
/
ConversationService
/
FetchConversationByPlatformID

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

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

Samples Conversation Ids

Request

Samples conversation ids (using consistent hashing) from a given profile in order to, e.g., create training data for AI services. Notes:

  • The sample is deterministic (pseudorandom with a fixed seed dependent on the input request).
Path
parentstringrequired

Profile to sample conversations from.

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

Bodyapplication/jsonrequired
pageSizeinteger(int32)

The maximum number of conversation id to return in one page. If unspecified, at most 10000 conversations will be returned.

pageTokenstring

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

filterobject(SampleConversationsRequestFilter)

Filters for sampling.

samplingMethodstring(SampleConversationsRequestSamplingMethod)

Sampling method.

  • SAMPLING_METHOD_UNSPECIFIED: Unspecified sampling method. Defaults to UNIFORM.
  • UNIFORM: Uniform sampling across conversations. Note that if you specify max_messages in the filter this still indirectly depends on the length of the conversation.
Default "SAMPLING_METHOD_UNSPECIFIED"
Enum"SAMPLING_METHOD_UNSPECIFIED""UNIFORM"
disableMessageCountsboolean

Whether to disable counting the # of messages. Without counting messages, sampling is much much faster.

curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*}/conversations:sample' \
  -H 'Content-Type: application/json' \
  -d '{
    "pageSize": 0,
    "pageToken": "string",
    "filter": {
      "startTime": "2019-08-24T14:15:22Z",
      "endTime": "2019-08-24T14:15:22Z",
      "maxConversationRatio": 0.1,
      "maxConversations": "string",
      "maxMessages": "string"
    },
    "samplingMethod": "SAMPLING_METHOD_UNSPECIFIED",
    "disableMessageCounts": true
  }'

Responses

A successful response.

Bodyapplication/json
sampledConversationsArray of objects(SampleConversationsResponseSampledConversation)

All sampled conversations ordered by start_time.

nextPageTokenstring

Token that is used to retrieve the next page.

parentstring

Profile that conversations were sampled from.

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

pageStartTimestring(date-time)required

Start time of this page (inclusive), i.e., start time of the base set of conversations that was sampled from.

pageEndTimestring(date-time)required

End time of this page (exclusive), i.e., end time of the base set of conversations that was sampled from.

pageConversationCountinteger(int32)

Total base set of conversations that were sampled from for this page.

Response
application/json
{
  "sampledConversations": [
    { … }
  ],
  "nextPageToken": "string",
  "parent": "string",
  "pageStartTime": "2019-08-24T14:15:22Z",
  "pageEndTime": "2019-08-24T14:15:22Z",
  "pageConversationCount": 0
}