Conversation Service
/
ConversationService
/
BatchUpsertConversationMessages

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

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

BatchUpsertConversationMessages

Request

BatchUpsertConversationMessages creates or updates multiple ConversationMessages. Messages are not required to be upserted in chronological order. Clients can call this method to upsert latest messages first, then previous messages. However, the performance is better if messages are batch upserted in chronological order.

This method can be called concurrently by up to 10 clients with the same messages. This allows clients to upsert duplicate messages from multiple agents monitoring the same conversation.

If any of the messages to be upserted already exist, the existing messages are updated by the following rules:

  • Only text, transcription_info, agent, visitor_info and state may be updated.
  • If agent is empty string or unspecified, it will not override the existing value.
  • If BatchUpsertConversationMessagesRequest.skip_update is true, existing messages won't be updated. Those messages will be ignored instead.
Path
parentstringrequired

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

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

Bodyapplication/jsonrequired
conversationMessagesArray of objects(A message in a Conversation. Next ID: 22)

The conversation messages to upsert. Messages are deduped based on platform chat id.

Empty message is allowed. If sync_status is SYNCHRONIZED, new suggestions will be triggered for the transfer case. Frontend shoud call this method with empty messages and SYNCHRONIZED status after updating conversation agent to make sure the transfer suggestion is triggered. (-- api-linter: core::0233::request-unknown-fields=disabled aip.dev/not-precedent: We don't have non-batch create method. --)

skipUpdateboolean

If set to true, existing messages won't be updated.

syncStatusstring(BatchUpsertConversationMessagesRequestMessageSyncStatus)

Describes the synchronization status between the platform UI and the Cresta backend.

  • MESSAGE_SYNC_STATUS_UNSPECIFIED: This value should not be used. By default, backend will treat it as IN_SYNC.
  • SYNCHRONIZING: This value should be used when the caller knows that there are more messages coming from the platform that have not yet been ingested into the conversation service. Note, the next call must be either in SYNCING or SYNCED status. If the caller knows there's no further messages to be synchronized, then SYNCED should be used directly.
  • SYNCHRONIZED: This value should be used when the caller knows that by the end of this request, the platform and the Cresta backend are in sync. New message after this call should be in status IN_SYNC unless another synchronization is needed.
  • IN_SYNC: This value should be used when the caller believes that the current batch is the latest message from the platform.
Default "MESSAGE_SYNC_STATUS_UNSPECIFIED"
Enum"MESSAGE_SYNC_STATUS_UNSPECIFIED""SYNCHRONIZING""SYNCHRONIZED""IN_SYNC"
curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*/conversations/*}/messages:batchUpsert' \
  -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"
            }
          ]
        }
      }
    ],
    "skipUpdate": true,
    "syncStatus": "MESSAGE_SYNC_STATUS_UNSPECIFIED"
  }'

Responses

A successful response.

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

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

Response
application/json
{}

List all the tags of a conversation.

Request

Path
parentstringrequired

The resource name of the conversation to be listed.

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

Responses

A successful response.

Bodyapplication/json
tagsArray of objects(Tags can be set on conversations to help with filtering and searching. Next id: 14)

The resource name of the tags that are added to the conversation.

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