conversation.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.dialogflow.v2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/dialogflow/v2/conversation_profile.proto";
import "google/cloud/dialogflow/v2/participant.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.V2";
option go_package = "cloud.google.com/go/dialogflow/apiv2/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "ConversationProto";
option java_package = "com.google.cloud.dialogflow.v2";
option objc_class_prefix = "DF";

// Service for managing
// [Conversations][google.cloud.dialogflow.v2.Conversation].
service Conversations {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/dialogflow";

  // Creates a new conversation. Conversations are auto-completed after 24
  // hours.
  //
  // Conversation Lifecycle:
  // There are two stages during a conversation: Automated Agent Stage and
  // Assist Stage.
  //
  // For Automated Agent Stage, there will be a dialogflow agent responding to
  // user queries.
  //
  // For Assist Stage, there's no dialogflow agent responding to user queries.
  // But we will provide suggestions which are generated from conversation.
  //
  // If
  // [Conversation.conversation_profile][google.cloud.dialogflow.v2.Conversation.conversation_profile]
  // is configured for a dialogflow agent, conversation will start from
  // `Automated Agent Stage`, otherwise, it will start from `Assist Stage`. And
  // during `Automated Agent Stage`, once an
  // [Intent][google.cloud.dialogflow.v2.Intent] with
  // [Intent.live_agent_handoff][google.cloud.dialogflow.v2.Intent.live_agent_handoff]
  // is triggered, conversation will transfer to Assist Stage.
  rpc CreateConversation(CreateConversationRequest) returns (Conversation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*}/conversations"
      body: "conversation"
      additional_bindings {
        post: "/v2/{parent=projects/*/locations/*}/conversations"
        body: "conversation"
      }
    };
    option (google.api.method_signature) = "parent,conversation";
  }

  // Returns the list of all conversations in the specified project.
  rpc ListConversations(ListConversationsRequest)
      returns (ListConversationsResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*}/conversations"
      additional_bindings {
        get: "/v2/{parent=projects/*/locations/*}/conversations"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieves the specific conversation.
  rpc GetConversation(GetConversationRequest) returns (Conversation) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/conversations/*}"
      additional_bindings {
        get: "/v2/{name=projects/*/locations/*/conversations/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Completes the specified conversation. Finished conversations are purged
  // from the database after 30 days.
  rpc CompleteConversation(CompleteConversationRequest) returns (Conversation) {
    option (google.api.http) = {
      post: "/v2/{name=projects/*/conversations/*}:complete"
      body: "*"
      additional_bindings {
        post: "/v2/{name=projects/*/locations/*/conversations/*}:complete"
        body: "*"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Lists messages that belong to a given conversation.
  // `messages` are ordered by `create_time` in descending order. To fetch
  // updates without duplication, send request with filter
  // `create_time_epoch_microseconds >
  // [first item's create_time of previous request]` and empty page_token.
  rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/conversations/*}/messages"
      additional_bindings {
        get: "/v2/{parent=projects/*/locations/*/conversations/*}/messages"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Suggests summary for a conversation based on specific historical messages.
  // The range of the messages to be used for summary can be specified in the
  // request.
  rpc SuggestConversationSummary(SuggestConversationSummaryRequest)
      returns (SuggestConversationSummaryResponse) {
    option (google.api.http) = {
      post: "/v2/{conversation=projects/*/conversations/*}/suggestions:suggestConversationSummary"
      body: "*"
      additional_bindings {
        post: "/v2/{conversation=projects/*/locations/*/conversations/*}/suggestions:suggestConversationSummary"
        body: "*"
      }
    };
    option (google.api.method_signature) = "conversation";
  }

  // Generates and returns a summary for a conversation that does not have a
  // resource created for it.
  rpc GenerateStatelessSummary(GenerateStatelessSummaryRequest)
      returns (GenerateStatelessSummaryResponse) {
    option (google.api.http) = {
      post: "/v2/{stateless_conversation.parent=projects/*}/suggestions:generateStatelessSummary"
      body: "*"
      additional_bindings {
        post: "/v2/{stateless_conversation.parent=projects/*/locations/*}/suggestions:generateStatelessSummary"
        body: "*"
      }
    };
  }
}

// Represents a conversation.
// A conversation is an interaction between an agent, including live agents
// and Dialogflow agents, and a support customer. Conversations can
// include phone calls and text-based chat sessions.
message Conversation {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/Conversation"
    pattern: "projects/{project}/conversations/{conversation}"
    pattern: "projects/{project}/locations/{location}/conversations/{conversation}"
  };

  // Enumeration of the completion status of the conversation.
  enum LifecycleState {
    // Unknown.
    LIFECYCLE_STATE_UNSPECIFIED = 0;

    // Conversation is currently open for media analysis.
    IN_PROGRESS = 1;

    // Conversation has been completed.
    COMPLETED = 2;
  }

  // Enumeration of the different conversation stages a conversation can be in.
  // Reference:
  // https://cloud.google.com/dialogflow/priv/docs/contact-center/basics#stages
  enum ConversationStage {
    // Unknown. Should never be used after a conversation is successfully
    // created.
    CONVERSATION_STAGE_UNSPECIFIED = 0;

    // The conversation should return virtual agent responses into the
    // conversation.
    VIRTUAL_AGENT_STAGE = 1;

    // The conversation should not provide responses, just listen and provide
    // suggestions.
    HUMAN_ASSIST_STAGE = 2;
  }

  // Output only. The unique identifier of this conversation.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>`.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The current state of the Conversation.
  LifecycleState lifecycle_state = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The Conversation Profile to be used to configure this
  // Conversation. This field cannot be updated.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversationProfiles/<Conversation Profile ID>`.
  string conversation_profile = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/ConversationProfile"
    }
  ];

  // Output only. It will not be empty if the conversation is to be connected
  // over telephony.
  ConversationPhoneNumber phone_number = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the conversation was started.
  google.protobuf.Timestamp start_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the conversation was finished.
  google.protobuf.Timestamp end_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // The stage of a conversation. It indicates whether the virtual agent or a
  // human agent is handling the conversation.
  //
  // If the conversation is created with the conversation profile that has
  // Dialogflow config set, defaults to
  // [ConversationStage.VIRTUAL_AGENT_STAGE][google.cloud.dialogflow.v2.Conversation.ConversationStage.VIRTUAL_AGENT_STAGE];
  // Otherwise, defaults to
  // [ConversationStage.HUMAN_ASSIST_STAGE][google.cloud.dialogflow.v2.Conversation.ConversationStage.HUMAN_ASSIST_STAGE].
  //
  // If the conversation is created with the conversation profile that has
  // Dialogflow config set but explicitly sets conversation_stage to
  // [ConversationStage.HUMAN_ASSIST_STAGE][google.cloud.dialogflow.v2.Conversation.ConversationStage.HUMAN_ASSIST_STAGE],
  // it skips
  // [ConversationStage.VIRTUAL_AGENT_STAGE][google.cloud.dialogflow.v2.Conversation.ConversationStage.VIRTUAL_AGENT_STAGE]
  // stage and directly goes to
  // [ConversationStage.HUMAN_ASSIST_STAGE][google.cloud.dialogflow.v2.Conversation.ConversationStage.HUMAN_ASSIST_STAGE].
  ConversationStage conversation_stage = 7;
}

// The request message for
// [Conversations.CreateConversation][google.cloud.dialogflow.v2.Conversations.CreateConversation].
message CreateConversationRequest {
  // Required. Resource identifier of the project creating the conversation.
  // Format: `projects/<Project ID>/locations/<Location ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Conversation"
    }
  ];

  // Required. The conversation to create.
  Conversation conversation = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Identifier of the conversation. Generally it's auto generated by
  // Google. Only set it if you cannot wait for the response to return a
  // auto-generated one to you.
  //
  // The conversation ID must be compliant with the regression fomula
  // "[a-zA-Z][a-zA-Z0-9_-]*" with the characters length in range of [3,64].
  // If the field is provided, the caller is resposible for
  // 1. the uniqueness of the ID, otherwise the request will be rejected.
  // 2. the consistency for whether to use custom ID or not under a project to
  // better ensure uniqueness.
  string conversation_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The request message for
// [Conversations.ListConversations][google.cloud.dialogflow.v2.Conversations.ListConversations].
message ListConversationsRequest {
  // Required. The project from which to list all conversation.
  // Format: `projects/<Project ID>/locations/<Location ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Conversation"
    }
  ];

  // Optional. The maximum number of items to return in a single page. By
  // default 100 and at most 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // A filter expression that filters conversations listed in the response. In
  // general, the expression must specify the field name, a comparison operator,
  // and the value to use for filtering:
  // <ul>
  //   <li>The value must be a string, a number, or a boolean.</li>
  //   <li>The comparison operator must be either `=`,`!=`, `>`, or `<`.</li>
  //   <li>To filter on multiple expressions, separate the
  //       expressions with `AND` or `OR` (omitting both implies `AND`).</li>
  //   <li>For clarity, expressions can be enclosed in parentheses.</li>
  // </ul>
  // Only `lifecycle_state` can be filtered on in this way. For example,
  // the following expression only returns `COMPLETED` conversations:
  //
  // `lifecycle_state = "COMPLETED"`
  //
  // For more information about filtering, see
  // [API Filtering](https://aip.dev/160).
  string filter = 4;
}

// The response message for
// [Conversations.ListConversations][google.cloud.dialogflow.v2.Conversations.ListConversations].
message ListConversationsResponse {
  // The list of conversations. There will be a maximum number of items
  // returned based on the page_size field in the request.
  repeated Conversation conversations = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

// The request message for
// [Conversations.GetConversation][google.cloud.dialogflow.v2.Conversations.GetConversation].
message GetConversationRequest {
  // Required. The name of the conversation. Format:
  // `projects/<Project ID>/locations/<Location ID>/conversations/<Conversation
  // ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Conversation"
    }
  ];
}

// The request message for
// [Conversations.CompleteConversation][google.cloud.dialogflow.v2.Conversations.CompleteConversation].
message CompleteConversationRequest {
  // Required. Resource identifier of the conversation to close.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Conversation"
    }
  ];
}

// The request message for
// [Conversations.ListMessages][google.cloud.dialogflow.v2.Conversations.ListMessages].
message ListMessagesRequest {
  // Required. The name of the conversation to list messages for.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Message"
    }
  ];

  // Optional. Filter on message fields. Currently predicates on `create_time`
  // and `create_time_epoch_microseconds` are supported. `create_time` only
  // support milliseconds accuracy. E.g.,
  // `create_time_epoch_microseconds > 1551790877964485` or
  // `create_time > 2017-01-15T01:30:15.01Z`.
  //
  // For more information about filtering, see
  // [API Filtering](https://aip.dev/160).
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum number of items to return in a single page. By
  // default 100 and at most 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for
// [Conversations.ListMessages][google.cloud.dialogflow.v2.Conversations.ListMessages].
message ListMessagesResponse {
  // The list of messages. There will be a maximum number of items
  // returned based on the page_size field in the request.
  // `messages` is sorted by `create_time` in descending order.
  repeated Message messages = 1;

  // Token to retrieve the next page of results, or empty if there are
  // no more results in the list.
  string next_page_token = 2;
}

// Represents a phone number for telephony integration. It allows for connecting
// a particular conversation over telephony.
message ConversationPhoneNumber {
  // Output only. The phone number to connect to this conversation.
  string phone_number = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for
// [Conversations.SuggestConversationSummary][google.cloud.dialogflow.v2.Conversations.SuggestConversationSummary].
message SuggestConversationSummaryRequest {
  // Required. The conversation to fetch suggestion for.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>`.
  string conversation = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Conversation"
    }
  ];

  // The name of the latest conversation message used as context for
  // compiling suggestion. If empty, the latest message of the conversation will
  // be used.
  //
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>/messages/<Message ID>`.
  string latest_message = 3 [(google.api.resource_reference) = {
    type: "dialogflow.googleapis.com/Message"
  }];

  // Max number of messages prior to and including
  // [latest_message] to use as context when compiling the
  // suggestion. By default 500 and at most 1000.
  int32 context_size = 4;

  // Parameters for a human assist query. Only used for POC/demo purpose.
  AssistQueryParameters assist_query_params = 5;
}

// The response message for
// [Conversations.SuggestConversationSummary][google.cloud.dialogflow.v2.Conversations.SuggestConversationSummary].
message SuggestConversationSummaryResponse {
  // Generated summary for a conversation.
  message Summary {
    // The summary content that is concatenated into one string.
    string text = 1;

    // The summary content that is divided into sections. The key is the
    // section's name and the value is the section's content. There is no
    // specific format for the key or value.
    map<string, string> text_sections = 4;

    // The name of the answer record. Format:
    // "projects/<Project ID>/answerRecords/<Answer Record ID>"
    string answer_record = 3 [(google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/AnswerRecord"
    }];
  }

  // Generated summary.
  Summary summary = 1;

  // The name of the latest conversation message used as context for
  // compiling suggestion.
  //
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversations/<Conversation ID>/messages/<Message ID>`.
  string latest_message = 2 [(google.api.resource_reference) = {
    type: "dialogflow.googleapis.com/Message"
  }];

  // Number of messages prior to and including
  // [last_conversation_message][] used to compile the suggestion. It may be
  // smaller than the [SuggestSummaryRequest.context_size][] field in the
  // request if there weren't that many messages in the conversation.
  int32 context_size = 3;
}

// The request message for
// [Conversations.GenerateStatelessSummary][google.cloud.dialogflow.v2.Conversations.GenerateStatelessSummary].
message GenerateStatelessSummaryRequest {
  // The minimum amount of information required to generate a Summary without
  // having a Conversation resource created.
  message MinimalConversation {
    // Required. The messages that the Summary will be generated from. It is
    // expected that this message content is already redacted and does not
    // contain any PII. Required fields: {content, language_code, participant,
    // participant_role} Optional fields: {send_time} If send_time is not
    // provided, then the messages must be provided in chronological order.
    repeated Message messages = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The parent resource to charge for the Summary's generation.
    // Format: `projects/<Project ID>/locations/<Location ID>`.
    string parent = 2 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {
        type: "locations.googleapis.com/Location"
      }
    ];
  }

  // Required. The conversation to suggest a summary for.
  MinimalConversation stateless_conversation = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. A ConversationProfile containing information required for Summary
  // generation.
  // Required fields: {language_code, security_settings}
  // Optional fields: {agent_assistant_config}
  ConversationProfile conversation_profile = 2
      [(google.api.field_behavior) = REQUIRED];

  // The name of the latest conversation message used as context for
  // generating a Summary. If empty, the latest message of the conversation will
  // be used. The format is specific to the user and the names of the messages
  // provided.
  string latest_message = 3 [(google.api.resource_reference) = {
    type: "dialogflow.googleapis.com/Message"
  }];

  // Max number of messages prior to and including
  // [latest_message] to use as context when compiling the
  // suggestion. By default 500 and at most 1000.
  int32 max_context_size = 4;
}

// The response message for
// [Conversations.GenerateStatelessSummary][google.cloud.dialogflow.v2.Conversations.GenerateStatelessSummary].
message GenerateStatelessSummaryResponse {
  // Generated summary for a conversation.
  message Summary {
    // The summary content that is concatenated into one string.
    string text = 1;

    // The summary content that is divided into sections. The key is the
    // section's name and the value is the section's content. There is no
    // specific format for the key or value.
    map<string, string> text_sections = 2;
  }

  // Generated summary.
  Summary summary = 1;

  // The name of the latest conversation message used as context for
  // compiling suggestion. The format is specific to the user and the names of
  // the messages provided.
  string latest_message = 2 [(google.api.resource_reference) = {
    type: "dialogflow.googleapis.com/Message"
  }];

  // Number of messages prior to and including
  // [last_conversation_message][] used to compile the suggestion. It may be
  // smaller than the [GenerateStatelessSummaryRequest.context_size][] field in
  // the request if there weren't that many messages in the conversation.
  int32 context_size = 3;
}