googleapis/google/chat/v1/annotation.proto

// Copyright 2025 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.chat.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/chat/v1/attachment.proto";
import "google/chat/v1/reaction.proto";
import "google/chat/v1/user.proto";

option csharp_namespace = "Google.Apps.Chat.V1";
option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
option java_multiple_files = true;
option java_outer_classname = "AnnotationProto";
option java_package = "com.google.chat.v1";
option objc_class_prefix = "DYNAPIProto";
option php_namespace = "Google\\Apps\\Chat\\V1";
option ruby_package = "Google::Apps::Chat::V1";

// Output only. Annotations can be associated with the plain-text body of the
// message or with chips that link to Google Workspace resources like Google
// Docs or Sheets with `start_index` and `length` of 0. To add basic formatting
// to a text message, see [Format text
// messages](https://developers.google.com/workspace/chat/format-messages).
//
// Example plain-text message body:
// ```
// Hello @FooBot how are you!"
// ```
//
// The corresponding annotations metadata:
// ```
// "annotations":[{
//   "type":"USER_MENTION",
//   "startIndex":6,
//   "length":7,
//   "userMention": {
//     "user": {
//       "name":"users/{user}",
//       "displayName":"FooBot",
//       "avatarUrl":"https://goo.gl/aeDtrS",
//       "type":"BOT"
//     },
//     "type":"MENTION"
//    }
// }]
// ```
message Annotation {
  // The type of this annotation.
  AnnotationType type = 1;

  // Start index (0-based, inclusive) in the plain-text message body this
  // annotation corresponds to.
  optional int32 start_index = 2;

  // Length of the substring in the plain-text message body this annotation
  // corresponds to. If not present, indicates a length of 0.
  int32 length = 3;

  // Additional metadata about the annotation.
  oneof metadata {
    // The metadata of user mention.
    UserMentionMetadata user_mention = 4;

    // The metadata for a slash command.
    SlashCommandMetadata slash_command = 5;

    // The metadata for a rich link.
    RichLinkMetadata rich_link_metadata = 6;

    // The metadata for a custom emoji.
    CustomEmojiMetadata custom_emoji_metadata = 7;
  }
}

// Annotation metadata for user mentions (@).
message UserMentionMetadata {
  enum Type {
    // Default value for the enum. Don't use.
    TYPE_UNSPECIFIED = 0;

    // Add user to space.
    ADD = 1;

    // Mention user in space.
    MENTION = 2;
  }

  // The user mentioned.
  User user = 1;

  // The type of user mention.
  Type type = 2;
}

// Annotation metadata for slash commands (/).
message SlashCommandMetadata {
  enum Type {
    // Default value for the enum. Don't use.
    TYPE_UNSPECIFIED = 0;

    // Add Chat app to space.
    ADD = 1;

    // Invoke slash command in space.
    INVOKE = 2;
  }

  // The Chat app whose command was invoked.
  User bot = 1;

  // The type of slash command.
  Type type = 2;

  // The name of the invoked slash command.
  string command_name = 3;

  // The command ID of the invoked slash command.
  int64 command_id = 4;

  // Indicates whether the slash command is for a dialog.
  bool triggers_dialog = 5;
}

// A rich link to a resource. Rich links can be associated with the plain-text
// body of the message or represent chips that link to Google Workspace
// resources like Google Docs or Sheets with `start_index` and `length`
// of 0.
message RichLinkMetadata {
  // The rich link type. More types might be added in the future.
  enum RichLinkType {
    // Default value for the enum. Don't use.
    RICH_LINK_TYPE_UNSPECIFIED = 0;

    // A Google Drive rich link type.
    DRIVE_FILE = 1;

    // A Chat space rich link type. For example, a space smart chip.
    CHAT_SPACE = 2;

    // A Gmail message rich link type. Specifically, a Gmail chip from [Share to
    // Chat](https://support.google.com/chat?p=chat_gmail). The API only
    // supports reading messages with GMAIL_MESSAGE rich links.
    GMAIL_MESSAGE = 3;

    // A Meet message rich link type. For example, a Meet chip.
    MEET_SPACE = 4;

    // A Calendar message rich link type. For example, a Calendar chip.
    CALENDAR_EVENT = 5;
  }

  // The URI of this link.
  string uri = 1;

  // The rich link type.
  RichLinkType rich_link_type = 2;

  // Data for the linked resource.
  oneof data {
    // Data for a drive link.
    DriveLinkData drive_link_data = 3;

    // Data for a chat space link.
    ChatSpaceLinkData chat_space_link_data = 4;

    // Data for a Meet space link.
    MeetSpaceLinkData meet_space_link_data = 5;

    // Data for a Calendar event link.
    CalendarEventLinkData calendar_event_link_data = 6;
  }
}

// Annotation metadata for custom emoji.
message CustomEmojiMetadata {
  // The custom emoji.
  CustomEmoji custom_emoji = 1;
}

// Data for Google Drive links.
message DriveLinkData {
  // A
  // [DriveDataRef](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.attachments#drivedataref)
  // which references a Google Drive file.
  DriveDataRef drive_data_ref = 1;

  // The mime type of the linked Google Drive resource.
  string mime_type = 2;
}

// Data for Chat space links.
message ChatSpaceLinkData {
  // The space of the linked Chat space resource.
  //
  // Format: `spaces/{space}`
  string space = 1
      [(google.api.resource_reference) = { type: "chat.googleapis.com/Space" }];

  // The thread of the linked Chat space resource.
  //
  // Format: `spaces/{space}/threads/{thread}`
  string thread = 2 [
    (google.api.resource_reference) = { type: "chat.googleapis.com/Thread" }
  ];

  // The message of the linked Chat space resource.
  //
  // Format: `spaces/{space}/messages/{message}`
  string message = 3 [
    (google.api.resource_reference) = { type: "chat.googleapis.com/Message" }
  ];
}

// Data for Meet space links.
message MeetSpaceLinkData {
  // The type of the Meet space.
  enum Type {
    // Default value for the enum. Don't use.
    TYPE_UNSPECIFIED = 0;

    // The Meet space is a meeting.
    MEETING = 1;

    // The Meet space is a huddle.
    HUDDLE = 2;
  }

  // The status of the huddle
  enum HuddleStatus {
    // Default value for the enum. Don't use.
    HUDDLE_STATUS_UNSPECIFIED = 0;

    // The huddle has started.
    STARTED = 1;

    // The huddle has ended. In this case the Meet space URI and identifiers
    // will no longer be valid.
    ENDED = 2;

    // The huddle has been missed. In this case the Meet space URI and
    // identifiers will no longer be valid.
    MISSED = 3;
  }

  // Meeting code of the linked Meet space.
  string meeting_code = 1;

  // Indicates the type of the Meet space.
  Type type = 2;

  // Optional. Output only. If the Meet is a Huddle, indicates the status of the
  // huddle. Otherwise, this is unset.
  HuddleStatus huddle_status = 3 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];
}

// Data for Calendar event links.
message CalendarEventLinkData {
  // The [Calendar
  // identifier](https://developers.google.com/workspace/calendar/api/v3/reference/calendars)
  // of the linked Calendar.
  string calendar_id = 1;

  // The [Event
  // identifier](https://developers.google.com/workspace/calendar/api/v3/reference/events)
  // of the linked Calendar event.
  string event_id = 2;
}

// Type of the annotation.
enum AnnotationType {
  // Default value for the enum. Don't use.
  ANNOTATION_TYPE_UNSPECIFIED = 0;

  // A user is mentioned.
  USER_MENTION = 1;

  // A slash command is invoked.
  SLASH_COMMAND = 2;

  // A rich link annotation.
  RICH_LINK = 3;

  // A custom emoji annotation.
  CUSTOM_EMOJI = 4;
}