// Copyright 2018 Google Inc.
//
// 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/cloud/dialogflow/v2/context.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.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 = "IntentProto";
option java_package = "com.google.cloud.dialogflow.v2";
option objc_class_prefix = "DF";


// An intent represents a mapping between input from a user and an action to
// be taken by your application. When you pass user input to the
// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method, the
// Dialogflow API analyzes the input and searches
// for a matching intent. If no match is found, the Dialogflow API returns a
// fallback intent (`is_fallback` = true).
//
// You can provide additional information for the Dialogflow API to use to
// match user input to an intent by adding the following to your intent.
//
// *   **Contexts** - provide additional context for intent analysis. For
//     example, if an intent is related to an object in your application that
//     plays music, you can provide a context to determine when to match the
//     intent if the user input is “turn it off”.  You can include a context
//     that matches the intent when there is previous user input of
//     "play music", and not when there is previous user input of
//     "turn on the light".
//
// *   **Events** - allow for matching an intent by using an event name
//     instead of user input. Your application can provide an event name and
//     related parameters to the Dialogflow API to match an intent. For
//     example, when your application starts, you can send a welcome event
//     with a user name parameter to the Dialogflow API to match an intent with
//     a personalized welcome message for the user.
//
// *   **Training phrases** - provide examples of user input to train the
//     Dialogflow API agent to better match intents.
//
// For more information about intents, see the
// [Dialogflow documentation](https://dialogflow.com/docs/intents).
service Intents {
  // Returns the list of all intents in the specified agent.
  rpc ListIntents(ListIntentsRequest) returns (ListIntentsResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/agent}/intents"
    };
  }

  // Retrieves the specified intent.
  rpc GetIntent(GetIntentRequest) returns (Intent) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/agent/intents/*}"
    };
  }

  // Creates an intent in the specified agent.
  rpc CreateIntent(CreateIntentRequest) returns (Intent) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/intents"
      body: "intent"
    };
  }

  // Updates the specified intent.
  rpc UpdateIntent(UpdateIntentRequest) returns (Intent) {
    option (google.api.http) = {
      patch: "/v2/{intent.name=projects/*/agent/intents/*}"
      body: "intent"
    };
  }

  // Deletes the specified intent.
  rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v2/{name=projects/*/agent/intents/*}"
    };
  }

  // Updates/Creates multiple intents in the specified agent.
  //
  // Operation <response: [BatchUpdateIntentsResponse][google.cloud.dialogflow.v2.BatchUpdateIntentsResponse]>
  rpc BatchUpdateIntents(BatchUpdateIntentsRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/intents:batchUpdate"
      body: "*"
    };
  }

  // Deletes intents in the specified agent.
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty]>
  rpc BatchDeleteIntents(BatchDeleteIntentsRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/agent}/intents:batchDelete"
      body: "*"
    };
  }
}

// Represents an intent.
// Intents convert a number of user expressions or patterns into an action. An
// action is an extraction of a user command or sentence semantics.
message Intent {
  // Represents an example or template that the agent is trained on.
  message TrainingPhrase {
    // Represents a part of a training phrase.
    message Part {
      // Required. The text corresponding to the example or template,
      // if there are no annotations. For
      // annotated examples, it is the text for one of the example's parts.
      string text = 1;

      // Optional. The entity type name prefixed with `@`. This field is
      // required for the annotated part of the text and applies only to
      // examples.
      string entity_type = 2;

      // Optional. The parameter name for the value extracted from the
      // annotated part of the example.
      string alias = 3;

      // Optional. Indicates whether the text was manually annotated by the
      // developer.
      bool user_defined = 4;
    }

    // Represents different types of training phrases.
    enum Type {
      // Not specified. This value should never be used.
      TYPE_UNSPECIFIED = 0;

      // Examples do not contain @-prefixed entity type names, but example parts
      // can be annotated with entity types.
      EXAMPLE = 1;

      // Templates are not annotated with entity types, but they can contain
      // @-prefixed entity type names as substrings.
      TEMPLATE = 2;
    }

    // Required. The unique identifier of this training phrase.
    string name = 1;

    // Required. The type of the training phrase.
    Type type = 2;

    // Required. The collection of training phrase parts (can be annotated).
    // Fields: `entity_type`, `alias` and `user_defined` should be populated
    // only for the annotated parts of the training phrase.
    repeated Part parts = 3;

    // Optional. Indicates how many times this example or template was added to
    // the intent. Each time a developer adds an existing sample by editing an
    // intent or training, this counter is increased.
    int32 times_added_count = 4;
  }

  // Represents intent parameters.
  message Parameter {
    // The unique identifier of this parameter.
    string name = 1;

    // Required. The name of the parameter.
    string display_name = 2;

    // Optional. The definition of the parameter value. It can be:
    // - a constant string,
    // - a parameter value defined as `$parameter_name`,
    // - an original parameter value defined as `$parameter_name.original`,
    // - a parameter value from some context defined as
    //   `#context_name.parameter_name`.
    string value = 3;

    // Optional. The default value to use when the `value` yields an empty
    // result.
    // Default values can be extracted from contexts by using the following
    // syntax: `#context_name.parameter_name`.
    string default_value = 4;

    // Optional. The name of the entity type, prefixed with `@`, that
    // describes values of the parameter. If the parameter is
    // required, this must be provided.
    string entity_type_display_name = 5;

    // Optional. Indicates whether the parameter is required. That is,
    // whether the intent cannot be completed without collecting the parameter
    // value.
    bool mandatory = 6;

    // Optional. The collection of prompts that the agent can present to the
    // user in order to collect value for the parameter.
    repeated string prompts = 7;

    // Optional. Indicates whether the parameter represents a list of values.
    bool is_list = 8;
  }

  // Corresponds to the `Response` field in the Dialogflow console.
  message Message {
    // The text response message.
    message Text {
      // Optional. The collection of the agent's responses.
      repeated string text = 1;
    }

    // The image response message.
    message Image {
      // Optional. The public URI to an image file.
      string image_uri = 1;

      // Optional. A text description of the image to be used for accessibility,
      // e.g., screen readers.
      string accessibility_text = 2;
    }

    // The quick replies response message.
    message QuickReplies {
      // Optional. The title of the collection of quick replies.
      string title = 1;

      // Optional. The collection of quick replies.
      repeated string quick_replies = 2;
    }

    // The card response message.
    message Card {
      // Optional. Contains information about a button.
      message Button {
        // Optional. The text to show on the button.
        string text = 1;

        // Optional. The text to send back to the Dialogflow API or a URI to
        // open.
        string postback = 2;
      }

      // Optional. The title of the card.
      string title = 1;

      // Optional. The subtitle of the card.
      string subtitle = 2;

      // Optional. The public URI to an image file for the card.
      string image_uri = 3;

      // Optional. The collection of card buttons.
      repeated Button buttons = 4;
    }

    // The simple response message containing speech or text.
    message SimpleResponse {
      // One of text_to_speech or ssml must be provided. The plain text of the
      // speech output. Mutually exclusive with ssml.
      string text_to_speech = 1;

      // One of text_to_speech or ssml must be provided. Structured spoken
      // response to the user in the SSML format. Mutually exclusive with
      // text_to_speech.
      string ssml = 2;

      // Optional. The text to display.
      string display_text = 3;
    }

    // The collection of simple response candidates.
    // This message in `QueryResult.fulfillment_messages` and
    // `WebhookResponse.fulfillment_messages` should contain only one
    // `SimpleResponse`.
    message SimpleResponses {
      // Required. The list of simple responses.
      repeated SimpleResponse simple_responses = 1;
    }

    // The basic card message. Useful for displaying information.
    message BasicCard {
      // The button object that appears at the bottom of a card.
      message Button {
        // Opens the given URI.
        message OpenUriAction {
          // Required. The HTTP or HTTPS scheme URI.
          string uri = 1;
        }

        // Required. The title of the button.
        string title = 1;

        // Required. Action to take when a user taps on the button.
        OpenUriAction open_uri_action = 2;
      }

      // Optional. The title of the card.
      string title = 1;

      // Optional. The subtitle of the card.
      string subtitle = 2;

      // Required, unless image is present. The body text of the card.
      string formatted_text = 3;

      // Optional. The image for the card.
      Image image = 4;

      // Optional. The collection of card buttons.
      repeated Button buttons = 5;
    }

    // The suggestion chip message that the user can tap to quickly post a reply
    // to the conversation.
    message Suggestion {
      // Required. The text shown the in the suggestion chip.
      string title = 1;
    }

    // The collection of suggestions.
    message Suggestions {
      // Required. The list of suggested replies.
      repeated Suggestion suggestions = 1;
    }

    // The suggestion chip message that allows the user to jump out to the app
    // or website associated with this agent.
    message LinkOutSuggestion {
      // Required. The name of the app or site this chip is linking to.
      string destination_name = 1;

      // Required. The URI of the app or site to open when the user taps the
      // suggestion chip.
      string uri = 2;
    }

    // The card for presenting a list of options to select from.
    message ListSelect {
      // An item in the list.
      message Item {
        // Required. Additional information about this option.
        SelectItemInfo info = 1;

        // Required. The title of the list item.
        string title = 2;

        // Optional. The main text describing the item.
        string description = 3;

        // Optional. The image to display.
        Image image = 4;
      }

      // Optional. The overall title of the list.
      string title = 1;

      // Required. List items.
      repeated Item items = 2;
    }

    // The card for presenting a carousel of options to select from.
    message CarouselSelect {
      // An item in the carousel.
      message Item {
        // Required. Additional info about the option item.
        SelectItemInfo info = 1;

        // Required. Title of the carousel item.
        string title = 2;

        // Optional. The body text of the card.
        string description = 3;

        // Optional. The image to display.
        Image image = 4;
      }

      // Required. Carousel items.
      repeated Item items = 1;
    }

    // Additional info about the select item for when it is triggered in a
    // dialog.
    message SelectItemInfo {
      // Required. A unique key that will be sent back to the agent if this
      // response is given.
      string key = 1;

      // Optional. A list of synonyms that can also be used to trigger this
      // item in dialog.
      repeated string synonyms = 2;
    }

    // Represents different platforms that a rich message can be intended for.
    enum Platform {
      // Not specified.
      PLATFORM_UNSPECIFIED = 0;

      // Facebook.
      FACEBOOK = 1;

      // Slack.
      SLACK = 2;

      // Telegram.
      TELEGRAM = 3;

      // Kik.
      KIK = 4;

      // Skype.
      SKYPE = 5;

      // Line.
      LINE = 6;

      // Viber.
      VIBER = 7;

      // Actions on Google.
      // When using Actions on Google, you can choose one of the specific
      // Intent.Message types that mention support for Actions on Google,
      // or you can use the advanced Intent.Message.payload field.
      // The payload field provides access to AoG features not available in the
      // specific message types.
      // If using the Intent.Message.payload field, it should have a structure
      // similar to the JSON message shown here. For more information, see
      // [Actions on Google Webhook
      // Format](https://developers.google.com/actions/dialogflow/webhook)
      // <pre>{
      //   "expectUserResponse": true,
      //   "isSsml": false,
      //   "noInputPrompts": [],
      //   "richResponse": {
      //     "items": [
      //       {
      //         "simpleResponse": {
      //           "displayText": "hi",
      //           "textToSpeech": "hello"
      //         }
      //       }
      //     ],
      //     "suggestions": [
      //       {
      //         "title": "Say this"
      //       },
      //       {
      //         "title": "or this"
      //       }
      //     ]
      //   },
      //   "systemIntent": {
      //     "data": {
      //       "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
      //       "listSelect": {
      //         "items": [
      //           {
      //             "optionInfo": {
      //               "key": "key1",
      //               "synonyms": [
      //                 "key one"
      //               ]
      //             },
      //             "title": "must not be empty, but unique"
      //           },
      //           {
      //             "optionInfo": {
      //               "key": "key2",
      //               "synonyms": [
      //                 "key two"
      //               ]
      //             },
      //             "title": "must not be empty, but unique"
      //           }
      //         ]
      //       }
      //     },
      //     "intent": "actions.intent.OPTION"
      //   }
      // }</pre>
      ACTIONS_ON_GOOGLE = 8;
    }

    // Required. The rich response message.
    oneof message {
      // The text response.
      Text text = 1;

      // The image response.
      Image image = 2;

      // The quick replies response.
      QuickReplies quick_replies = 3;

      // The card response.
      Card card = 4;

      // Returns a response containing a custom, platform-specific payload.
      // See the Intent.Message.Platform type for a description of the
      // structure that may be required for your platform.
      google.protobuf.Struct payload = 5;

      // The voice and text-only responses for Actions on Google.
      SimpleResponses simple_responses = 7;

      // The basic card response for Actions on Google.
      BasicCard basic_card = 8;

      // The suggestion chips for Actions on Google.
      Suggestions suggestions = 9;

      // The link out suggestion chip for Actions on Google.
      LinkOutSuggestion link_out_suggestion = 10;

      // The list card response for Actions on Google.
      ListSelect list_select = 11;

      // The carousel card response for Actions on Google.
      CarouselSelect carousel_select = 12;
    }

    // Optional. The platform that this message is intended for.
    Platform platform = 6;
  }

  // Represents a single followup intent in the chain.
  message FollowupIntentInfo {
    // The unique identifier of the followup intent.
    // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
    string followup_intent_name = 1;

    // The unique identifier of the followup intent parent.
    // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
    string parent_followup_intent_name = 2;
  }

  // Represents the different states that webhooks can be in.
  enum WebhookState {
    // Webhook is disabled in the agent and in the intent.
    WEBHOOK_STATE_UNSPECIFIED = 0;

    // Webhook is enabled in the agent and in the intent.
    WEBHOOK_STATE_ENABLED = 1;

    // Webhook is enabled in the agent and in the intent. Also, each slot
    // filling prompt is forwarded to the webhook.
    WEBHOOK_STATE_ENABLED_FOR_SLOT_FILLING = 2;
  }

  // Required for all methods except `create` (`create` populates the name
  // automatically.
  // The unique identifier of this intent.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  string name = 1;

  // Required. The name of this intent.
  string display_name = 2;

  // Required. Indicates whether webhooks are enabled for the intent.
  WebhookState webhook_state = 6;

  // Optional. The priority of this intent. Higher numbers represent higher
  // priorities. Zero or negative numbers mean that the intent is disabled.
  int32 priority = 3;

  // Optional. Indicates whether this is a fallback intent.
  bool is_fallback = 4;

  // Optional. Indicates whether Machine Learning is disabled for the intent.
  // Note: If `ml_diabled` setting is set to true, then this intent is not
  // taken into account during inference in `ML ONLY` match mode. Also,
  // auto-markup in the UI is turned off.
  bool ml_disabled = 19;

  // Optional. The list of context names required for this intent to be
  // triggered.
  // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`.
  repeated string input_context_names = 7;

  // Optional. The collection of event names that trigger the intent.
  // If the collection of input contexts is not empty, all of the contexts must
  // be present in the active user session for an event to trigger this intent.
  repeated string events = 8;

  // Optional. The collection of examples/templates that the agent is
  // trained on.
  repeated TrainingPhrase training_phrases = 9;

  // Optional. The name of the action associated with the intent.
  string action = 10;

  // Optional. The collection of contexts that are activated when the intent
  // is matched. Context messages in this collection should not set the
  // parameters field. Setting the `lifespan_count` to 0 will reset the context
  // when the intent is matched.
  // Format: `projects/<Project ID>/agent/sessions/-/contexts/<Context ID>`.
  repeated Context output_contexts = 11;

  // Optional. Indicates whether to delete all contexts in the current
  // session when this intent is matched.
  bool reset_contexts = 12;

  // Optional. The collection of parameters associated with the intent.
  repeated Parameter parameters = 13;

  // Optional. The collection of rich messages corresponding to the
  // `Response` field in the Dialogflow console.
  repeated Message messages = 14;

  // Optional. The list of platforms for which the first response will be
  // taken from among the messages assigned to the DEFAULT_PLATFORM.
  repeated Message.Platform default_response_platforms = 15;

  // The unique identifier of the root intent in the chain of followup intents.
  // It identifies the correct followup intents chain for this intent.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  string root_followup_intent_name = 16;

  // The unique identifier of the parent intent in the chain of followup
  // intents.
  // It identifies the parent followup intent.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  string parent_followup_intent_name = 17;

  // Optional. Collection of information about all followup intents that have
  // name of this intent as a root_name.
  repeated FollowupIntentInfo followup_intent_info = 18;
}

// The request message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents].
message ListIntentsRequest {
  // Required. The agent to list all intents from.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Optional. The language to list training phrases, parameters and rich
  // messages for. If not specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;

  // Optional. The resource view to apply to the returned intent.
  IntentView intent_view = 3;

  // Optional. The maximum number of items to return in a single page. By
  // default 100 and at most 1000.
  int32 page_size = 4;

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 5;
}

// The response message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents].
message ListIntentsResponse {
  // The list of agent intents. There will be a maximum number of items
  // returned based on the page_size field in the request.
  repeated Intent intents = 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 [Intents.GetIntent][google.cloud.dialogflow.v2.Intents.GetIntent].
message GetIntentRequest {
  // Required. The name of the intent.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  string name = 1;

  // Optional. The language to retrieve training phrases, parameters and rich
  // messages for. If not specified, the agent's default language is used.
  // [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 2;

  // Optional. The resource view to apply to the returned intent.
  IntentView intent_view = 3;
}

// The request message for [Intents.CreateIntent][google.cloud.dialogflow.v2.Intents.CreateIntent].
message CreateIntentRequest {
  // Required. The agent to create a intent for.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The intent to create.
  Intent intent = 2;

  // Optional. The language of training phrases, parameters and rich messages
  // defined in `intent`. If not specified, the agent's default language is
  // used. [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 3;

  // Optional. The resource view to apply to the returned intent.
  IntentView intent_view = 4;
}

// The request message for [Intents.UpdateIntent][google.cloud.dialogflow.v2.Intents.UpdateIntent].
message UpdateIntentRequest {
  // Required. The intent to update.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  Intent intent = 1;

  // Optional. The language of training phrases, parameters and rich messages
  // defined in `intent`. If not specified, the agent's default language is
  // used. [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 2;

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 3;

  // Optional. The resource view to apply to the returned intent.
  IntentView intent_view = 4;
}

// The request message for [Intents.DeleteIntent][google.cloud.dialogflow.v2.Intents.DeleteIntent].
message DeleteIntentRequest {
  // Required. The name of the intent to delete.
  // Format: `projects/<Project ID>/agent/intents/<Intent ID>`.
  string name = 1;
}

// The request message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2.Intents.BatchUpdateIntents].
message BatchUpdateIntentsRequest {
  // Required. The name of the agent to update or create intents in.
  // Format: `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The source of the intent batch.
  oneof intent_batch {
    // The URI to a Google Cloud Storage file containing intents to update or
    // create. The file format can either be a serialized proto (of IntentBatch
    // type) or JSON object. Note: The URI must start with "gs://".
    string intent_batch_uri = 2;

    // The collection of intents to update or create.
    IntentBatch intent_batch_inline = 3;
  }

  // Optional. The language of training phrases, parameters and rich messages
  // defined in `intents`. If not specified, the agent's default language is
  // used. [More than a dozen
  // languages](https://dialogflow.com/docs/reference/language) are supported.
  // Note: languages must be enabled in the agent, before they can be used.
  string language_code = 4;

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 5;

  // Optional. The resource view to apply to the returned intent.
  IntentView intent_view = 6;
}

// The response message for [Intents.BatchUpdateIntents][google.cloud.dialogflow.v2.Intents.BatchUpdateIntents].
message BatchUpdateIntentsResponse {
  // The collection of updated or created intents.
  repeated Intent intents = 1;
}

// The request message for [Intents.BatchDeleteIntents][google.cloud.dialogflow.v2.Intents.BatchDeleteIntents].
message BatchDeleteIntentsRequest {
  // Required. The name of the agent to delete all entities types for. Format:
  // `projects/<Project ID>/agent`.
  string parent = 1;

  // Required. The collection of intents to delete. Only intent `name` must be
  // filled in.
  repeated Intent intents = 2;
}

// This message is a wrapper around a collection of intents.
message IntentBatch {
  // A collection of intents.
  repeated Intent intents = 1;
}

// Represents the options for views of an intent.
// An intent can be a sizable object. Therefore, we provide a resource view that
// does not return training phrases in the response by default.
enum IntentView {
  // Training phrases field is not populated in the response.
  INTENT_VIEW_UNSPECIFIED = 0;

  // All fields are populated.
  INTENT_VIEW_FULL = 1;
}
