// Copyright 2026 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.v2beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.V2Beta1";
option go_package = "cloud.google.com/go/dialogflow/apiv2beta1/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "PhoneNumberProto";
option java_package = "com.google.cloud.dialogflow.v2beta1";
option objc_class_prefix = "DF";

// Service for managing
// [PhoneNumbers][google.cloud.dialogflow.v2beta1.PhoneNumber].
service PhoneNumbers {
  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";

  // Returns the list of all phone numbers in the specified project.
  rpc ListPhoneNumbers(ListPhoneNumbersRequest)
      returns (ListPhoneNumbersResponse) {
    option (google.api.http) = {
      get: "/v2beta1/{parent=projects/*}/phoneNumbers"
      additional_bindings {
        get: "/v2beta1/{parent=projects/*/locations/*}/phoneNumbers"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Updates the specified `PhoneNumber`.
  rpc UpdatePhoneNumber(UpdatePhoneNumberRequest) returns (PhoneNumber) {
    option (google.api.http) = {
      patch: "/v2beta1/{phone_number.name=projects/*/phoneNumbers/*}"
      body: "phone_number"
      additional_bindings {
        patch: "/v2beta1/{phone_number.name=projects/*/locations/*/phoneNumbers/*}"
        body: "phone_number"
      }
    };
    option (google.api.method_signature) = "phone_number,update_mask";
  }

  // Requests deletion of a `PhoneNumber`. The `PhoneNumber` is moved into the
  // [DELETE_REQUESTED][google.cloud.dialogflow.v2beta1.PhoneNumber.LifecycleState.DELETE_REQUESTED]
  // state immediately, and is deleted approximately 30 days later. This method
  // may only be called on a `PhoneNumber` in the
  // [ACTIVE][google.cloud.dialogflow.v2beta1.PhoneNumber.LifecycleState.ACTIVE]
  // state.
  rpc DeletePhoneNumber(DeletePhoneNumberRequest) returns (PhoneNumber) {
    option (google.api.http) = {
      delete: "/v2beta1/{name=projects/*/phoneNumbers/*}"
      additional_bindings {
        delete: "/v2beta1/{name=projects/*/locations/*/phoneNumbers/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Cancels the deletion request for a `PhoneNumber`. This method may only be
  // called on a `PhoneNumber` in the
  // [DELETE_REQUESTED][google.cloud.dialogflow.v2beta1.PhoneNumber.LifecycleState.DELETE_REQUESTED]
  // state.
  rpc UndeletePhoneNumber(UndeletePhoneNumberRequest) returns (PhoneNumber) {
    option (google.api.http) = {
      post: "/v2beta1/{name=projects/*/phoneNumbers/*}:undelete"
      body: "*"
      additional_bindings {
        post: "/v2beta1/{name=projects/*/locations/*/phoneNumbers/*}:undelete"
        body: "*"
      }
    };
    option (google.api.method_signature) = "name";
  }
}

// Represents a phone number.
// `PhoneNumber` resources enable phone calls to be answered by Dialogflow
// services and are added to a project through a
// [PhoneNumberOrder][google.cloud.dialogflow.v2beta1.PhoneNumberOrder].
message PhoneNumber {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/PhoneNumber"
    pattern: "projects/{project}/phoneNumbers/{phone_number}"
    pattern: "projects/{project}/locations/{location}/phoneNumbers/{phone_number}"
  };

  // The states that a `PhoneNumber` can be in.
  enum LifecycleState {
    // This value is never used.
    LIFECYCLE_STATE_UNSPECIFIED = 0;

    // Number is active and can receive phone calls.
    ACTIVE = 1;

    // Number is pending deletion, and cannot receive calls.
    DELETE_REQUESTED = 2;
  }

  // List of SIP trunks that are allowed to make calls to this phone number.
  message AllowedSipTrunks {
    // List of SIP trunks that are allowed to make calls to this phone number.
    // If empty, any SIP trunk is allowed.
    repeated string sip_trunks = 1 [(google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/SipTrunk"
    }];

    // Optional. List of GTP carrier IDs allowed to make calls to this phone
    // number. Used for private interconnects where standard SIP trunks aren't
    // applicable.
    repeated string carrier_ids = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. The unique identifier of this phone number.
  // Required for
  // [PhoneNumbers.UpdatePhoneNumber][google.cloud.dialogflow.v2beta1.PhoneNumbers.UpdatePhoneNumber]
  // method. Format: `projects/<Project ID>/phoneNumbers/<PhoneNumber ID>`.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/phoneNumbers/<PhoneNumber ID>`.
  string name = 1 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Phone number in [E.164](https://en.wikipedia.org/wiki/E.164)
  // format. An example of a correctly formatted phone number: +15556767888.
  string phone_number = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The conversation profile calls to this `PhoneNumber` should use.
  // The project ID here should be the same as the one in
  // [name][google.cloud.dialogflow.v2beta1.PhoneNumber.name].
  // Format: `projects/<Project ID>/conversationProfiles/<ConversationProfile
  // ID>`.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/conversationProfiles/<ConversationProfile ID>`.
  string conversation_profile = 3 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The state of the `PhoneNumber`. Defaults to `ACTIVE`.
  // `PhoneNumber` objects set to `DELETE_REQUESTED` always decline incoming
  // calls and can be removed completely within 30 days.
  LifecycleState lifecycle_state = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Restricts inbound calls
  oneof inbound_restriction {
    // Optional. Only allow calls from the specified SIP trunks.
    AllowedSipTrunks allowed_sip_trunks = 7
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Output only. The time at which this resource will be purged.
  google.protobuf.Timestamp purge_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The request message for
// [PhoneNumbers.DeletePhoneNumber][google.cloud.dialogflow.v2beta1.PhoneNumbers.DeletePhoneNumber].
message DeletePhoneNumberRequest {
  // Required. The unique identifier of the `PhoneNumber` to delete.
  // Format: `projects/<Project ID>/phoneNumbers/<PhoneNumber ID>`.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/phoneNumbers/<PhoneNumber ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/PhoneNumber"
    }
  ];
}

// The request message for
// [PhoneNumbers.UndeletePhoneNumber][google.cloud.dialogflow.v2beta1.PhoneNumbers.UndeletePhoneNumber].
message UndeletePhoneNumberRequest {
  // Required. The unique identifier of the `PhoneNumber` to delete.
  // Format: `projects/<Project ID>/phoneNumbers/<PhoneNumber ID>`.
  // Format: `projects/<Project ID>/locations/<Location
  // ID>/phoneNumbers/<PhoneNumber ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/PhoneNumber"
    }
  ];
}

// The request message for
// [PhoneNumbers.ListPhoneNumbers][google.cloud.dialogflow.v2beta1.PhoneNumbers.ListPhoneNumbers].
message ListPhoneNumbersRequest {
  // Required. The project to list all `PhoneNumber` resources from.
  // Format: `projects/<Project ID>`.
  // Format: `projects/<Project ID>/locations/<Location ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/PhoneNumber"
    }
  ];

  // Optional. The maximum number of items to return in a single page.
  // The default value is 100. The maximum value is 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];

  // Optional. Controls whether `PhoneNumber` resources in the
  // [DELETE_REQUESTED][google.cloud.dialogflow.v2beta1.PhoneNumber.LifecycleState.DELETE_REQUESTED]
  // state should be returned. Defaults to false.
  bool show_deleted = 4 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for
// [PhoneNumbers.ListPhoneNumbers][google.cloud.dialogflow.v2beta1.PhoneNumbers.ListPhoneNumbers].
message ListPhoneNumbersResponse {
  // The list of `PhoneNumber` resources. There is a maximum number of items
  // returned based on the page_size field in the request.
  repeated PhoneNumber phone_numbers = 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
// [PhoneNumbers.UpdatePhoneNumber][google.cloud.dialogflow.v2beta1.PhoneNumbers.UpdatePhoneNumber].
message UpdatePhoneNumberRequest {
  // Required. The `PhoneNumber` to update.
  PhoneNumber phone_number = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}