Conversation Service
/
ConversationService
/
BatchGetConversationMessages

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

BatchCreateConversationEvents

Request

BatchCreateConversationEvents creates multiple ConversationEvents

Path
parentstringrequired

Resource name of the parent.

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

Bodyapplication/jsonrequired
eventsArray of objects(Events. (-- api-linter: core::0233::request-unknown-fields=disabled aip.dev/not-precedent: customized api. --))
skipAnnotationsboolean(If set to true, this API call won't trigger orchestrator to generate moment/action annotations. If not set to true, if the conversation has skip_annotations=true in StartConversationRequest.feature_override, it won't trigger as well. (-- api-linter: core::0233::request-unknown-fields=disabled aip.dev/not-precedent: customized api. --))
curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*/conversations/*}/events:batchCreate' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "name": "string",
        "associatedMessage": "string",
        "associatedActionAnnotation": "string",
        "type": "EVENT_TYPE_UNSPECIFIED",
        "callReason": {
          "selectedMoment": "string"
        },
        "entityFeedback": {
          "isDelete": true,
          "entity": {
            "start": 0,
            "end": 0,
            "entityName": "string",
            "strValue": "string",
            "surfaceMode": "SURFACE_MODE_UNSPECIFIED",
            "postRedactionStart": 0,
            "postRedactionEnd": 0
          }
        },
        "summarizationFeedback": {
          "summary": {
            "summaryItems": [
              {
                "startTurn": 0,
                "endTurn": 0,
                "summaryText": "string",
                "type": "string",
                "summarizationItemValue": {},
                "metadata": {},
                "topicPrefix": "string",
                "skippedModelInference": true
              }
            ]
          }
        },
        "usedSuggestion": {
          "resultId": "string"
        },
        "usedHintSuggestion": {},
        "interactiveVoiceResponse": {
          "stringValue": "string"
        },
        "conversationMetadata": {
          "metadataValues": {
            "property1": {
              "values": [
                {}
              ]
            },
            "property2": {
              "values": [
                {}
              ]
            }
          },
          "source": "SOURCE_UNSPECIFIED"
        },
        "usedHintDocumentChip": {
          "document": "string"
        },
        "usedSearchSuggestion": {
          "resultId": "string",
          "documentName": "string",
          "title": "string",
          "text": "string",
          "confidence": 0.1
        },
        "usedKbSearch": {
          "sessionMetadata": {
            "sessionId": "string",
            "eventSequenceId": 0
          },
          "query": "string",
          "queryType": "QUERY_TYPE_UNSPECIFIED",
          "searchResultCount": 0
        },
        "usedKbDocument": {
          "sessionMetadata": {
            "sessionId": "string",
            "eventSequenceId": 0
          },
          "docType": "KB_DOCUMENT_TYPE_UNSPECIFIED",
          "document": "string",
          "guidedWorkflowData": {
            "name": "string",
            "toStepId": 0,
            "fromName": "string",
            "fromStepId": 0
          },
          "knowledgeSessionId": "string"
        },
        "conversationLanguageChange": {
          "newLanguageCode": "string",
          "oldLanguageCode": "string"
        },
        "usedSummarization": {
          "copyAllNotes": {
            "count": 0
          },
          "editSummarizationNote": {},
          "copySummarizationNote": {}
        },
        "usedNoteTaking": {
          "copyEntity": {
            "entityName": "string"
          },
          "updateEntity": {
            "key": "string",
            "value": "string"
          }
        },
        "conversationTextPasted": {
          "text": "string",
          "agent": {
            "agentName": "string",
            "fullName": "string"
          }
        },
        "kaGenAiReplyFeedback": {
          "type": "FEEDBACK_TYPE_UNSPECIFIED",
          "reason": "string",
          "knowledgeSessionId": "string"
        },
        "kaGenAiReplyCopied": {
          "text": "string",
          "knowledgeSessionId": "string"
        },
        "kaGenAiReplyInserted": {
          "text": "string",
          "knowledgeSessionId": "string"
        },
        "usedSmartCompose": {
          "textLength": 0,
          "usedTextLength": 0
        },
        "kaGenAiExtractedQuestionFeedback": {
          "type": "FEEDBACK_TYPE_UNSPECIFIED",
          "knowledgeSessionId": "string"
        },
        "topicSubmission": {
          "topics": {
            "summaryItems": [
              {
                "startTurn": 0,
                "endTurn": 0,
                "summaryText": "string",
                "type": "string",
                "summarizationItemValue": {},
                "metadata": {},
                "topicPrefix": "string",
                "skippedModelInference": true
              }
            ]
          }
        },
        "createTime": "2019-08-24T14:15:22Z"
      }
    ],
    "skipAnnotations": true
  }'

Responses

A successful response.

Bodyapplication/json
eventsArray of objects(Event is a non-message information in a Conversation. NEXT ID: 26)

Events created.

Response
application/json
{
  "events": [
    { … }
  ]
}

BatchGetConversationMessages

Request

BatchGetConversationMessages gets ConversationMessages based on specified resource names. The requested ConversationMessages may span multiple Conversations.

Path
parentstringrequired

Resource name of the parent Conversation that the requested ConversationMessages belong to. To get messages from multiple conversations, set conversation_id to "-" Format: customers/{customer_id}/profiles/{profile_id}/conversations/{conversation_id}

Query
namesArray of stringsrequired

Resource names of ConversationMessages.

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

Responses

A successful response.

Bodyapplication/json
conversationMessagesArray of objects(A message in a Conversation. Next ID: 22)read-only

Returned ConversationMessages.

Response
application/json
{
  "conversationMessages": [
    { … }
  ]
}

BatchUpdateConversationMessageContents

Request

BatchUpdateConversationMessageContents updates multiple ConversationMessages. Only the following properties of ConversationMessages are updated:

  • text
  • transcription_info
  • state
Path
parentstringrequired

The resource name of the parent Conversation shared by all ConversationMessages being updated.

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

Bodyapplication/jsonrequired
conversationMessagesArray of objects(The conversation messages to update. (-- api-linter: core::0234::request-unknown-fields=disabled aip.dev/not-precedent: We don't have non-batch update method. --))required
conversationMessages[].​namestringrequired

Resource name of the ConversationMessage.

This field must be populated in the ConversationService.BatchUpsertConversationMessages request.

conversationMessages[].​textstring

The plain text content of the message.

If state is INCOMPLETE, the text may change. This can happen when transcribing ongoing audio conversation.

If it's populated in the [BatchUpsertConversationMessagesRequest][], the backend stores the text without any modification. If it's not populated, the backend extract the plain text content from the [text_html][] field. In either case, it's guaranteed that the text field is populated in the output.

When populating this field, clients are responsible to strip any markups or translate platform-specific symbols to Unicode characters when creating or updating the message.

When rendering content of this field, clients MUST HTML-escape the text to avoid HTML injection. Clients should also handle the whitespaces and new lines properly (e.g. by converting to non-breakable space HTML entity or adding p or br tags).

conversationMessages[].​textHtmlstring

The content of the message in HTML format.

If the [text][] field is not populated, this field MUST be populated. In that case, the value of the [text][field] will be inferred by extracting plain texts from this field.

This field is NOT guaranteed to be populated in the response. If it's not populated in the response, clients must fallback to the [text][] field.

The backend will strip unsafe markups from its value. However, clients should still strip unsafe markups before rendering it.

conversationMessages[].​transcriptionInfoobject(conversationTranscriptionInfo)

Detailed information for audio transcription result.

conversationMessages[].​agentstring

The resource name of the User representing the agent that sends the message.

When creating/updating a message with speaker other than AGENT, this field must be left empty.

It can be empty while the speaker is AGENT in either request or response message. If it's empty in the request, the agent that observed this message is not the agent that's speaking. If it's empty in the response, the speaking agent is not using Cresta to specify the agent's resource name.

NOTE: Specifying the ConversationMessage's agent does NOT update the parent Conversation's agent if they are different. Use ConversationService.UpdateConversationAgent to update the Conversation's agent.

conversationMessages[].​speakerstring(conversationConversationMessageSpeakerRole)

Enum for identifying the role of the speaker of this message.

  • ROLE_UNSPECIFIED: Invalid value. Do not use. (-- api-linter: core::0126::unspecified=disabled --)
  • AGENT: The speaker is the agent.
  • VISITOR: The speaker is the visitor.
  • SYSTEM_MESSAGE: The message is sent by the system.
  • BOT: The message is sent by a bot.
Default "ROLE_UNSPECIFIED"
Enum"ROLE_UNSPECIFIED""AGENT""VISITOR""SYSTEM_MESSAGE""BOT"
conversationMessages[].​speakerInfoobject(Additional information about the speaker)
conversationMessages[].​statestring(conversationConversationMessageState)

Message state.

  • STATE_UNSPECIFIED: Invalid State. Do not use.
  • INCOMPLETE: The message is incomplete. For Voice, this means that the Speech-to-text engine is still transcribing the ongoing audio and some transcription may change. Not available for Chat messages.

end_time is not populated under this state.

Incomplete messages won't get PII-redacted.

  • COMPLETE: The message is complete. Chat messages are always on this state. For Voice messages, this state means no ongoing audio will be transcribed into this message and the trascription won't change anymore.

end_time is populated under this state.

Default "STATE_UNSPECIFIED"
Enum"STATE_UNSPECIFIED""INCOMPLETE""COMPLETE"
conversationMessages[].​sequencePositioninteger(int32)

Used for sorting ConversationMessages in the same Conversation. Smaller number means the message was sent earlier.

If its value is not populated in StartConversationRequest, create_time must be populated. Unlike other fields, setting it to default value 0 also populates it.

DEPRECATED: this is included for compatibility purposes. It will be removed in the future when all dependencies are migrated off it. Specify create_time instead.

conversationMessages[].​createTimestring(date-time)

When the message is created.

Clients should populate this value if it can be retrieved from the platform. It should be used for sorting messages in the same conversation in chronological order.

If it's not specified, sequence_position must be specified.

conversationMessages[].​originalEventDataobject

The raw JSON object sent from the platform along with the conversation message. We store it for debugging purposes.

conversationMessages[].​usedSuggestionIdstring(int64)

The ID of the reply suggestion which the agent used to author this conversation message.

Note: this field only applies to agent messages and should only be populated if the agents selected a reply suggestion.

Deprecated: the suggestions is under redesigned and being migrated to actions.

conversationMessages[].​usedCoachSuggestionIdstring(int64)

The ID of the coach made suggestion which the agent used to author this conversation message.

Note: this field only applies to agent messages and should only be populated if the agents selected a coach made suggestion.

Deprecated: the suggestions is under redesigned and being migrated to actions.

conversationMessages[].​redactionobject(conversationRedactionInfo)

Information about PII redaction.

conversationMessages[].​botDataobject(Chatbot related data Next ID: 11)
conversationMessages[].​emailobject(conversationEmailMessage)

EmailMessage is the email-specific data for a conversation message.

curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*/conversations/*}/messages:batchUpdate' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversationMessages": [
      {
        "name": "string",
        "text": "string",
        "textHtml": "string",
        "transcriptionInfo": {
          "transcriptionWords": [
            {
              "word": "string",
              "confidence": 0.1,
              "startOffset": "string",
              "endOffset": "string"
            }
          ],
          "languages": [
            {
              "languageCode": "string",
              "confidence": 0.1
            }
          ],
          "transcribedLanguage": "string"
        },
        "agent": "string",
        "speaker": "ROLE_UNSPECIFIED",
        "speakerInfo": {
          "displayName": "string",
          "platformSpeakerId": "string"
        },
        "state": "STATE_UNSPECIFIED",
        "sequencePosition": 0,
        "createTime": "2019-08-24T14:15:22Z",
        "originalEventData": {},
        "usedSuggestionId": "string",
        "usedCoachSuggestionId": "string",
        "redaction": {
          "ranges": [
            {
              "textStartOffset": 0,
              "textEndOffset": 0,
              "audioStartOffset": "string",
              "audioEndOffset": "string",
              "redactedText": "string"
            }
          ],
          "state": "STATE_UNSPECIFIED",
          "maskedText": "string"
        },
        "botData": {
          "legacyId": "string",
          "legacyConversationMessageId": "string",
          "version": "string",
          "intentName": "string",
          "isSelfServiced": true,
          "isBounced": true,
          "isTransfer": true,
          "isBotMessage": true,
          "isProactive": true,
          "isAutomatedWidgetEvent": true,
          "audioUri": "string"
        },
        "email": {
          "subject": "string",
          "body": "string",
          "bodyFormat": "BODY_FORMAT_UNSPECIFIED",
          "fromParticipant": {
            "platformParticipantId": "string",
            "emailAddress": "string",
            "displayName": "string",
            "speakerRole": "ROLE_UNSPECIFIED",
            "occurrence": {
              "emailFrom": true,
              "emailTo": true,
              "emailCc": true,
              "emailBcc": true,
              "agent": true
            }
          },
          "toParticipants": [
            {
              "platformParticipantId": "string",
              "emailAddress": "string",
              "displayName": "string",
              "speakerRole": "ROLE_UNSPECIFIED",
              "occurrence": {
                "emailFrom": true,
                "emailTo": true,
                "emailCc": true,
                "emailBcc": true,
                "agent": true
              }
            }
          ],
          "ccParticipants": [
            {
              "platformParticipantId": "string",
              "emailAddress": "string",
              "displayName": "string",
              "speakerRole": "ROLE_UNSPECIFIED",
              "occurrence": {
                "emailFrom": true,
                "emailTo": true,
                "emailCc": true,
                "emailBcc": true,
                "agent": true
              }
            }
          ],
          "bccParticipants": [
            {
              "platformParticipantId": "string",
              "emailAddress": "string",
              "displayName": "string",
              "speakerRole": "ROLE_UNSPECIFIED",
              "occurrence": {
                "emailFrom": true,
                "emailTo": true,
                "emailCc": true,
                "emailBcc": true,
                "agent": true
              }
            }
          ],
          "replyTo": "string",
          "attachments": [
            {
              "uri": "string",
              "size": "string",
              "mimeType": "string",
              "displayName": "string",
              "description": "string"
            }
          ]
        }
      }
    ]
  }'

Responses

A successful response.

Bodyapplication/json
object(Response of [ConversationService.BatchUpdateConversationMessages][])

(-- api-linter: core::0234::response-resource-field=disabled aip.dev/not-precedent: We don't return updated the updated messages because the client does not care about it --)

Response
application/json
{}