path: root/third_party/googleapis/google/cloud/dialogflow/v2/conversation.proto

// Copyright 2022 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/participant.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.V2";
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2;dialogflow";
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";
  }
}

// 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];
}