Conversation Service
/
ConversationService
/
AddStarTagToConversation

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

Closes a Conversation.

Request

If the Conversation does not exist, it returns a NOT_FOUND (404) error.

DEPRECATED: Use UpdateConversationState instead.

Path
namestringrequired

Resource name of the Conversation to be closed.

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

Bodyapplication/jsonrequired
object

Request of [ConversationService.CloseConversation][].

curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{name=customers/*/profiles/*/conversations/*}:close' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

A successful response.

Bodyapplication/json
object(conversationCloseConversationResponse)

Response of [ConversationService.CloseConversation][].

Response
application/json
{}

AddStarTagToConversation

Request

Adds a star tag to a conversation. This service behaves like AddConversationTag but it creates star tag automatically if the star tag for a user is not set.

Path
parentstringrequired

The resource name of the conversation to be starred.

Bodyapplication/jsonrequired
object(Request of [ConversationService.AddConversationStarTag][])
curl -i -X POST \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*/conversations/*}/addConversationStarTag' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

A successful response.

Bodyapplication/json
object(Response of [ConversationService.AddConversationStarTag][])
Response
application/json
{}

ListConversationEvents.

Request

ListConversationEvents lists ConversationEvents under a conversation.

Path
parentstringrequired

Resource name of the parent.

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

Query
pageSizeinteger(int32)

The maximum number of conversationEvents to return. If unspecified, at most 100 conversationEvents will be returned.

pageTokenstring

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

filter.typesArray of strings

List of event types to return.

  • EVENT_TYPE_UNSPECIFIED: Unspecified.
  • CALL_REASON_SELECTION: Call reason selection.
  • ENTITY_FEEDBACK: Entity feedback.
  • SUMMARIZATION_FEEDBACK: Summarization feedback.
  • USED_SUGGESTION: Used Suggestion. Specifically, Agent clicks a Suggestion and sends as a message with optional update.
  • USED_HINT_SUGGESTION: Used Hint Suggestion. Specfically, Agent clicks a Hint's suggestion text and send as a message with optional update. Note it's different from USED_SUGGESTION as the source of text is different: one is Hint, the other is Suggestion.
  • INTERACTIVE_VOICE_RESPONSE: The voice customer provides the visitor's pre-conversation input in interactive voice response (IVR) data. This event is expected to be added at the start of the conversation.
  • CONVERSATION_START: Will be inserted into the system by conversation service upon conversation start.
  • CONVERSATION_METADATA: New metadata is added to the conversation. The event only consists the new metadata values, not existing ones.
  • USED_HINT_DOCUMENT_CHIP: Event to log usage of the hint document chip when the agent clicks a hint's document chip.
  • USED_SEARCH_SUGGESTION: Event to log usage of a search suggestion. Specifically, an agent clicks a search suggestion, sends it as a message with optional update.
  • CONVERSATION_HOLD: The conversation has been put on hold. (We also reuse hold for pause session and pause audio)
  • CONVERSATION_UNHOLD: The conversation has been unheld from on hold. (We also reuse unhold for resume session and resume audio)
  • USED_KB_SEARCH: Event to log usage of the KB search feature.

Currently, the definition of "usage" is a KB search is issued and a response is returned.

A KB search could be triggered by multiple cases, for examples:

  • User manually types in the a keyword and hits ENTER.
  • User clicks on a search suggestion.
  • User clicks on the KB recommend chip.
  • etc.
  • USED_KB_DOCUMENT: Event to log usage of a particular KB document.

Currently, the definition of "usage" is a KB document is opened or a navigation is done inside the document.

This event should be logged whenever a KB document is opened. It could be opend by multiple cases, for examples:

  • User clicks on a KB document search result.
  • User clicks on a KB recommend chip.
  • User clicks on a KB document hint chip.
  • etc.

This event should be logged as well whenever a Guided Workflow step changes.

Note: this event is different from the USED_HINT_DOCUMENT_CHIP. A user clicks on the hint document chip might also cause a KB document be opened and considered used. But not all KB document opens are from hint document chip.

  • CONVERSATION_LANGUAGE_CHANGE: Conversation language change.
  • USED_SUMMARIZATION: Event to log usage of summarization.

This event should be logged with corresponding details whenever:

  • All summarization notes are copied
  • A summarization note is copied
  • A summarization note is edited
  • USED_NOTE_TAKING: Event to log usage of note taking.

This event should be logged with corresponding details whenever:

  • An automatic note taking entity is copied.
  • An automatic note taking entity is updated.
  • CONVERSATION_TEXT_PASTED: Event when agent pastes text from somewhere outside of cresta happens.
  • KA_GEN_AI_REPLY_FEEDBACK: Event to log feedback on a Knowledge Assist GenAI reply.
  • KA_GEN_AI_REPLY_COPIED: Event to log when the agent copies a Knowledge Assist GenAI reply.
  • KA_GEN_AI_REPLY_INSERTED: Event to log when the agent inserts a Knowledge Assist GenAI reply.
  • USED_SMART_COMPOSE: Starting from 07/18/2024, for the conversation events below, we only write events into clickhouse only. And we will gradually migrate the existing events to clickhouse as needed.

Used smart compose. This event is logged when an agent inserts a smart compose text predicted by model. This can be triggered in 2 scenarios:

    1. the agent inserts the full smart compose text;
    1. the agent inserts one single word from the full smart compext text. Note: each insertion (full text or single word) will be tracked as one used smart compose event.
  • KA_GEN_AI_EXTRACTED_QUESTION_FEEDBACK: Event to log feedback on a Knowledge Assist GenAI extracted question.
  • TOPIC_SUBMISSION: Topics submitted to CRM.
Items Enum"EVENT_TYPE_UNSPECIFIED""CALL_REASON_SELECTION""ENTITY_FEEDBACK""SUMMARIZATION_FEEDBACK""USED_SUGGESTION""USED_HINT_SUGGESTION""INTERACTIVE_VOICE_RESPONSE""CONVERSATION_START""CONVERSATION_METADATA""USED_HINT_DOCUMENT_CHIP"
curl -i -X GET \
  'https://{api-domain}.cresta.com/v1/{parent=customers/*/profiles/*/conversations/*}/conversationEvents'

Responses

A successful response.

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

The returned conversationEvents.

nextPageTokenstring

Token is used to retrieve the next page.

Response
application/json
{
  "conversationEvents": [
    { … }
  ],
  "nextPageToken": "string"
}