REST Resource: spaces.messages

資源:訊息

Google Chat 聊天室中的訊息。

JSON 表示法
{
  "name": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "lastUpdateTime": string,
  "deleteTime": string,
  "text": string,
  "formattedText": string,
  "cards": [
    {
      object (Card)
    }
  ],
  "cardsV2": [
    {
      object (CardWithId)
    }
  ],
  "annotations": [
    {
      object (Annotation)
    }
  ],
  "thread": {
    object (Thread)
  },
  "space": {
    object (Space)
  },
  "fallbackText": string,
  "actionResponse": {
    object (ActionResponse)
  },
  "argumentText": string,
  "slashCommand": {
    object (SlashCommand)
  },
  "attachment": [
    {
      object (Attachment)
    }
  ],
  "matchedUrl": {
    object (MatchedUrl)
  },
  "threadReply": boolean,
  "clientAssignedMessageId": string,
  "emojiReactionSummaries": [
    {
      object (EmojiReactionSummary)
    }
  ],
  "privateMessageViewer": {
    object (User)
  },
  "deletionMetadata": {
    object (DeletionMetadata)
  },
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  },
  "attachedGifs": [
    {
      object (AttachedGif)
    }
  ],
  "accessoryWidgets": [
    {
      object (AccessoryWidget)
    }
  ]
}
欄位
name

string

訊息的資源名稱。

格式︰spaces/{space}/messages/{message}

其中 {space} 是張貼訊息的聊天室 ID,{message} 則是系統為該訊息指派的 ID。例如:spaces/AAAAAAAAAAA/messages/BBBBBBBBBBB.BBBBBBBBBBB

如果您在建立訊息時設定了自訂 ID,即可使用這個 ID 在要求中指定訊息,只要將 {message} 替換成 clientAssignedMessageId 欄位的值即可。例如 spaces/AAAAAAAAAAA/messages/client-custom-name。詳情請參閱為訊息命名

sender

object (User)

僅供輸出。建立訊息的使用者。如果 Chat 應用程式是以使用者身分進行驗證,輸出內容會填入「使用者」nametype

createTime

string (Timestamp format)

選用設定。不可變動。如果是透過 Chat 建立的聊天室,訊息的建立時間。這個欄位只會輸出,但用於匯入模式空格時除外。

針對匯入模式聊天室,請將這個欄位設為訊息在來源中建立時的歷來時間戳記,以保留原本的建立時間。

lastUpdateTime

string (Timestamp format)

僅供輸出。使用者上次編輯訊息的時間。如果訊息從未編輯過,這個欄位就會空白。

deleteTime

string (Timestamp format)

僅供輸出。在 Google Chat 中刪除訊息的時間。如果郵件從未刪除,則這個欄位會留空。

text

string

郵件的純文字內文。圖片、影片或網頁的第一個連結會產生預覽方塊。你也可以使用@號提及 Google Chat 使用者,或提及聊天室中的所有成員。

如要瞭解如何建立簡訊,請參閱傳送簡訊

formattedText

string

僅供輸出。包含郵件 text,且已加上用於通訊格式的標記。這個欄位可能不會擷取 UI 中顯示的所有格式設定,但包含以下內容:

  • 適用於粗體、斜體、刪除線、等寬、等寬區塊和項目符號清單的標記語法

  • 採用 <users/{user}> 格式使用者提及內容

  • 使用 <{url}|{rendered_text}> 格式的自訂超連結,第一個字串是網址,第二個則是轉譯的文字,例如 <http://example.com|custom text>

  • 使用 :{emoji_name}: 格式的自訂表情符號,例如 :smile:。這項做法不適用於萬國碼 (Unicode) 表情符號 (例如使用 U+1F600 代表露齒大笑的表情符號)。

詳情請參閱查看郵件傳送的文字格式

cards[]
(deprecated)

object (Card)

已淘汰:請改用 cardsV2

互動式、格式化和互動式資訊卡,可用於顯示 UI 元素,例如格式化的文字、按鈕和可點擊的圖片。資訊卡通常顯示在郵件的純文字內文下方。cardscardsV2 的大小上限為 32 KB。

cardsV2[]

object (CardWithId)

資訊卡的陣列。

只有即時通訊應用程式可以建立資訊卡。如果您的 Chat 應用程式是以使用者身分進行驗證,則訊息不得包含資訊卡。

如要瞭解卡片及其建立方式,請參閱傳送卡片訊息

使用資訊卡建構工具設計及預覽資訊卡。

開啟資訊卡建構工具

annotations[]

object (Annotation)

僅供輸出。與此訊息中 text 相關聯的註解。

thread

object (Thread)

訊息所屬的討論串。如需相關用法,請參閱發起或回覆訊息串

space

object (Space)

如果 Chat 應用程式是以使用者身分進行驗證,輸出內容就會填入「聊天室」 name

fallbackText

string

訊息資訊卡的純文字說明,在實際卡片無法顯示 (例如行動裝置通知) 時使用。

actionResponse

object (ActionResponse)

僅限輸入。Chat 應用程式可用來設定回應發布方式的參數。

argumentText

string

僅供輸出。訊息的純文字內文,以及所有 Chat 應用程式提及內容的部分已移除。

slashCommand

object (SlashCommand)

僅供輸出。斜線指令資訊 (如適用)。

attachment[]

object (Attachment)

使用者上傳的附件。

matchedUrl

object (MatchedUrl)

僅供輸出。與連結預覽模式相符的 spaces.messages.text 網址。詳情請參閱「預覽連結」。

threadReply

boolean

僅供輸出。如果為 true,則訊息是回覆討論串中的回應。如果選擇 false,聊天室的頂層對話中會顯示訊息為討論串的第一則訊息,或是沒有討論串回覆的訊息。

如果聊天室不支援在討論串中回覆,這個欄位一律為 false

clientAssignedMessageId

string

選用設定。訊息的自訂 ID。您可以使用欄位來辨別訊息,或取得、刪除或更新訊息。如要設定自訂 ID,請在建立訊息時指定 messageId 欄位。詳情請參閱為訊息命名

emojiReactionSummaries[]

object (EmojiReactionSummary)

僅供輸出。訊息的表情符號回應摘要清單。

privateMessageViewer

object (User)

不可變動。建立訊息的輸入內容,否則僅限輸出。可以查看訊息的使用者。設定後,訊息就會是私人訊息,僅供特定使用者和 Chat 應用程式查看。私人訊息不支援連結預覽和附件。

只有 Chat 應用程式可以傳送私人訊息。如果 Chat 應用程式會以使用者身分進行驗證,則訊息不得為私人訊息,必須省略這個欄位。

詳情請參閱「傳送私人訊息給 Google Chat 使用者」。

deletionMetadata

object (DeletionMetadata)

僅供輸出。已刪除訊息的相關資訊。設定 deleteTime 時,訊息會遭到刪除。

quotedMessageMetadata

object (QuotedMessageMetadata)

僅供輸出。Google Chat 使用者在聊天室中引用的訊息相關資訊。Google Chat 使用者可以引用訊息來回覆。

attachedGifs[]

object (AttachedGif)

僅供輸出。訊息附加的 GIF 圖片。

accessoryWidgets[]

object (AccessoryWidget)

郵件底部會顯示一或多個互動式小工具。您可以在含有文字、資訊卡,或同時包含文字和卡片的訊息中加入配件小工具。不適用於含有對話方塊的訊息。詳情請參閱在郵件底部新增互動式小工具

您必須使用應用程式驗證,才能使用配件小工具建立訊息。

CardWithId

Google Chat 訊息中的資訊卡

只有即時通訊應用程式可以建立資訊卡。如果您的 Chat 應用程式是以使用者身分進行驗證,則訊息不得包含資訊卡。

使用資訊卡建構工具設計及預覽資訊卡。

開啟資訊卡建構工具

JSON 表示法
{
  "cardId": string,
  "card": {
    object (Card)
  }
}
欄位
cardId

string

如果訊息含有多張資訊卡,則為必要欄位。訊息中卡片的專屬 ID。

card

object (Card)

資訊卡。大小上限為 32 KB。

註解

僅供輸出。與訊息純文字內文相關聯的註解。如要為簡訊加入基本格式,請參閱「設定簡訊格式」。

純文字訊息內文範例:

Hello @FooBot how are you!"

對應的註解中繼資料:

"annotations":[{
  "type":"USER_MENTION",
  "startIndex":6,
  "length":7,
  "userMention": {
    "user": {
      "name":"users/{user}",
      "displayName":"FooBot",
      "avatarUrl":"https://goo.gl/aeDtrS",
      "type":"BOT"
    },
    "type":"MENTION"
   }
}]
JSON 表示法
{
  "type": enum (AnnotationType),
  "length": integer,
  "startIndex": integer,

  // Union field metadata can be only one of the following:
  "userMention": {
    object (UserMentionMetadata)
  },
  "slashCommand": {
    object (SlashCommandMetadata)
  },
  "richLinkMetadata": {
    object (RichLinkMetadata)
  }
  // End of list of possible types for union field metadata.
}
欄位
type

enum (AnnotationType)

此註解的類型。

length

integer

此註解對應的純文字訊息本文中的子字串長度。

startIndex

integer

此註解對應的純文字訊息內文中的起始索引 (包含 0,含)。

聯集欄位 metadata。註解的其他中繼資料。metadata 只能是下列其中一項:
userMention

object (UserMentionMetadata)

使用者提及的中繼資料。

slashCommand

object (SlashCommandMetadata)

斜線指令的中繼資料。

AnnotationType

註解的類型。

列舉
ANNOTATION_TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
USER_MENTION 提及使用者。
SLASH_COMMAND 系統會叫用斜線指令。

UserMentionMetadata

使用者提及 (@) 的註解中繼資料。

JSON 表示法
{
  "user": {
    object (User)
  },
  "type": enum (Type)
}
欄位
user

object (User)

提及的使用者。

type

enum (Type)

使用者提及的類型。

類型

列舉
TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
ADD 將使用者新增至聊天室。
MENTION 在聊天室中提及使用者。

SlashCommandMetadata

斜線指令 (/) 的註解中繼資料

JSON 表示法
{
  "bot": {
    object (User)
  },
  "type": enum (Type),
  "commandName": string,
  "commandId": string,
  "triggersDialog": boolean
}
欄位
bot

object (User)

叫用指令的 Chat 應用程式。

type

enum (Type)

斜線指令類型,

commandName

string

所叫用的斜線指令名稱。

commandId

string (int64 format)

所叫用斜線指令的指令 ID。

triggersDialog

boolean

表示是否為對話方塊使用斜線指令。

類型

列舉
TYPE_UNSPECIFIED 列舉的預設值。請勿使用。
ADD 將 Chat 應用程式新增至聊天室。
INVOKE 在空間中叫用斜線指令。

RichLinkMetadata

資源的豐富連結。

JSON 表示法
{
  "uri": string,
  "richLinkType": enum (RichLinkType),

  // Union field data can be only one of the following:
  "driveLinkData": {
    object (DriveLinkData)
  }
  // End of list of possible types for union field data.
}
欄位
uri

string

這個連結的 URI。

聯集欄位 data。已連結資源的資料。data 只能是下列其中一項:

RichLinkType

複合式連結類型。我們日後可能會新增更多類型。

列舉
DRIVE_FILE Google 雲端硬碟複合式連結類型。

DriveLinkData

Google 雲端硬碟連結資料。

JSON 表示法
{
  "driveDataRef": {
    object (DriveDataRef)
  },
  "mimeType": string
}
欄位
driveDataRef

object (DriveDataRef)

參照 Google 雲端硬碟檔案的 DriveDataRef

mimeType

string

已連結 Google 雲端硬碟資源的 MIME 類型。

討論串

Google Chat 聊天室中的討論串。如需相關用法,請參閱發起或回覆訊息串

如果您在建立訊息時指定討論串,可以設定 messageReplyOption 欄位來決定找不到相符的討論串時的處理方式。

JSON 表示法
{
  "name": string,
  "threadKey": string
}
欄位
name

string

僅供輸出。執行緒的資源名稱。

範例:spaces/{space}/threads/{thread}

threadKey

string

選用設定。建立或更新討論串的輸入內容。否則系統只會輸出。執行緒的 ID。最多可以支援 4,000 個半形字元。

這個 ID 是設定此 ID 的 Chat 應用程式專屬 ID。舉例來說,如果多個 Chat 應用程式使用相同的執行緒索引鍵建立訊息,訊息會發布至不同的討論串。如要在由使用者或其他 Chat 應用程式建立的討論串中回覆,請改為指定討論串 name 欄位。

ActionResponse

Chat 應用程式可用來設定回應發布方式的參數。

JSON 表示法
{
  "type": enum (ResponseType),
  "url": string,
  "dialogAction": {
    object (DialogAction)
  },
  "updatedWidget": {
    object (UpdatedWidget)
  }
}
欄位
type

enum (ResponseType)

僅限輸入。Chat 應用程式回應的類型。

url

string

僅限輸入。供使用者驗證或設定的網址。(僅適用於 REQUEST_CONFIG 回應類型)。

dialogAction

object (DialogAction)

僅限輸入。與對話方塊相關的互動事件的回應。必須搭配 ResponseType.Dialog 使用。

updatedWidget

object (UpdatedWidget)

僅限輸入。更新小工具的回應。

ResponseType

Chat 應用程式回應的類型。

列舉
TYPE_UNSPECIFIED 系統處理為 NEW_MESSAGE 的預設類型。
NEW_MESSAGE 以新訊息的形式張貼在主題中。
UPDATE_MESSAGE 更新 Chat 應用程式的訊息。只有在訊息傳送者類型為 BOTCARD_CLICKED 事件中,才允許執行這項動作。
UPDATE_USER_MESSAGE_CARDS 更新使用者訊息中的資訊卡。唯有當 MESSAGE 事件含有相符網址的 MESSAGE 事件,或是訊息傳送者類型為 HUMANCARD_CLICKED 事件時,才能夠做為回應。系統會忽略文字。
REQUEST_CONFIG 私下要求使用者提供其他驗證或設定。
DIALOG 顯示對話方塊
UPDATE_WIDGET 小工具文字自動完成選項查詢。

DialogAction

包含對話方塊和要求狀態碼。

JSON 表示法
{
  "actionStatus": {
    object (ActionStatus)
  },

  // Union field action can be only one of the following:
  "dialog": {
    object (Dialog)
  }
  // End of list of possible types for union field action.
}
欄位
actionStatus

object (ActionStatus)

僅限輸入。叫用或提交對話方塊的要求狀態。視需要向使用者顯示狀態和訊息。例如發生錯誤或成功時。

聯集欄位 action

action 只能採用下列其中一種設定:

dialog

object (Dialog)

僅限輸入。要求的對話方塊

對話方塊

對話方塊內文的包裝函式。

JSON 表示法
{
  "body": {
    object (Card)
  }
}
欄位
body

object (Card)

僅限輸入。對話方塊的內文,顯示在強制回應視窗中。Google Chat 應用程式不支援下列卡片實體:DateTimePickerOnChangeAction

ActionStatus

代表要求叫用或提交對話方塊的狀態。

JSON 表示法
{
  "statusCode": enum (Code),
  "userFacingMessage": string
}
欄位
statusCode

enum (Code)

狀態碼。

userFacingMessage

string

傳送使用者要求狀態的訊息。如未設定,系統會傳送根據 statusCode 的一般訊息。

程式碼

gRPC API 的標準錯誤代碼。

有時可能適用多個錯誤代碼。服務應傳回最適用的特定錯誤代碼。例如,如果 OUT_OF_RANGEFAILED_PRECONDITION 代碼都適用,則最好使用前者。同樣的,NOT_FOUNDALREADY_EXISTS 的偏好優先順序也高於 FAILED_PRECONDITION

列舉
OK

非錯誤;於成功時傳回。

HTTP 對應:200 OK

CANCELLED

作業已取消,一般由呼叫者取消。

HTTP 對應:499 用戶端已關閉要求

UNKNOWN

發生不明錯誤。例如,當從另一個位址空間收到的 Status 值屬於在此位址空間中不明的錯誤空間時,就可能傳回此錯誤。由 API 發出但未傳回充分錯誤資訊的錯誤,也可能會轉換為此錯誤。

HTTP 對應:500 內部伺服器錯誤

INVALID_ARGUMENT

用戶端指定了無效的引數。請注意,這與 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 表示無論系統狀態為何 (例如格式錯誤的檔案名稱),都指出這些引數有問題。

HTTP 對應:400 錯誤的要求

DEADLINE_EXCEEDED

期限於作業完成之前過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,來自伺服器的成功回應延遲時間可能已長到足以使期限過期。

HTTP 對應:504 閘道逾時

NOT_FOUND

找不到某些要求的實體 (例如檔案或目錄)。

伺服器開發人員注意事項:如果針對整個類別的使用者拒絕要求,例如逐步推出功能或未記錄的許可清單,則可使用 NOT_FOUND。如果針對某一使用者類別中的部分使用者拒絕要求,例如使用者套用的存取權控管,則必須使用 PERMISSION_DENIED

HTTP 對應:404 找不到

ALREADY_EXISTS

用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。

HTTP 對應:409 衝突

PERMISSION_DENIED

呼叫者沒有執行指定作業的權限。對於因耗用某些資源所導致的拒絕情形,不得使用 PERMISSION_DENIED (請針對這些錯誤改用 RESOURCE_EXHAUSTED)。如果無法識別呼叫者,不得使用 PERMISSION_DENIED (請針對這些錯誤改用 UNAUTHENTICATED)。此錯誤代碼並不表示要求有效,或是要求的實體已存在或是滿足其他先決條件。

HTTP 對應:403 禁止

UNAUTHENTICATED

要求沒有作業的有效驗證憑證。

HTTP 對應:401 未授權

RESOURCE_EXHAUSTED

已耗盡某些資源,或許是每位使用者的配額,或許是完整檔案系統空間不足。

HTTP 對應:429 太多要求

FAILED_PRECONDITION

作業已遭拒絕,因為系統不在執行作業所需的狀態下。例如要刪除的目錄非空白、rmdir 作業套用至非目錄等。

服務實作者可根據以下指南決定 FAILED_PRECONDITIONABORTEDUNAVAILABLE:(a) 如果用戶端只能重試失敗的呼叫,請使用 UNAVAILABLE。(b) 如果用戶端應在更高的層級重試,請使用 ABORTED。舉例來說,當用戶端指定的 test-set 發生錯誤時,用戶端應重新啟動「read-modify-write」序列。(c) 在明確修正系統狀態之前,如果用戶端不應重試,請使用 FAILED_PRECONDITION。舉例來說,如果因目錄非空白而導致「rmdir」失敗,則應傳回 FAILED_PRECONDITION,因為除非從目錄中刪除檔案,否則用戶端不應重試。

HTTP 對應:400 錯誤的要求

ABORTED

作業已取消,原因通常是排序器檢查失敗或交易取消等並行問題。

如要決定採用 FAILED_PRECONDITIONABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:409 衝突

OUT_OF_RANGE

嘗試作業時超過有效範圍,例如搜尋或讀取超過檔案結尾。

INVALID_ARGUMENT 不同,此錯誤表示如果系統狀態變更則可修正的問題。例如,如果要求在不在 [0,2^32-1] 範圍內的偏移值進行讀取,32 位元檔案系統會產生 INVALID_ARGUMENT,但如果要求從超過目前檔案大小的偏移值讀取,則會產生 OUT_OF_RANGE

FAILED_PRECONDITIONOUT_OF_RANGE 之間有一些重疊之處。建議您在適用情況下使用 OUT_OF_RANGE (更具體的錯誤),讓疊代整個聊天室的呼叫者就能輕鬆尋找 OUT_OF_RANGE 錯誤,偵測這些錯誤。

HTTP 對應:400 錯誤的要求

UNIMPLEMENTED

未實作作業或作業在此服務中不受支援/未啟用。

HTTP 對應:501 未實作

INTERNAL

內部錯誤。這表示基礎系統預期的某些不變的情形已被打破。此錯誤代碼保留供嚴重錯誤使用。

HTTP 對應:500 內部伺服器錯誤

UNAVAILABLE

服務目前無法使用。這極有可能是暫時情況,可透過重試輪詢來解決。請注意,重試非冪等作業不一定是安全的。

如要決定採用 FAILED_PRECONDITIONABORTED 還是 UNAVAILABLE,請參閱以上指南。

HTTP 對應:503 服務不可用

DATA_LOSS

無法復原的資料遺失或損毀。

HTTP 對應:500 內部伺服器錯誤

UpdatedWidget

更新小工具的回應。用於提供小工具的自動完成選項。

JSON 表示法
{
  "widget": string,

  // Union field updated_widget can be only one of the following:
  "suggestions": {
    object (SelectionItems)
  }
  // End of list of possible types for union field updated_widget.
}
欄位
widget

string

更新小工具的 ID。此 ID 必須與觸發更新要求的小工具 ID 相符。

聯集欄位 updated_widget

updated_widget 只能採用下列其中一種設定:

suggestions

object (SelectionItems)

小工具自動完成結果清單

SelectionItems

小工具自動完成結果清單。

JSON 表示法
{
  "items": [
    {
      object (SelectionItem)
    }
  ]
}
欄位
items[]

object (SelectionItem)

SelectionItem 物件的陣列。

SlashCommand

Google Chat 中的斜線指令

JSON 表示法
{
  "commandId": string
}
欄位
commandId

string (int64 format)

叫用的斜線指令 ID。

MatchedUrl

Chat 訊息中的相符網址。即時通訊應用程式可預覽相符的網址。詳情請參閱「預覽連結」。

JSON 表示法
{
  "url": string
}
欄位
url

string

僅供輸出。相符的網址。

EmojiReactionSummary

使用特定表情符號回應訊息的使用者人數。

JSON 表示法
{
  "emoji": {
    object (Emoji)
  },
  "reactionCount": integer
}
欄位
emoji

object (Emoji)

與回應相關聯的表情符號。

reactionCount

integer

使用相關表情符號的回應總數。

DeletionMetadata

已刪除訊息的相關資訊。設定 deleteTime 時,訊息會遭到刪除。

JSON 表示法
{
  "deletionType": enum (DeletionType)
}
欄位
deletionType

enum (DeletionType)

指出刪除訊息的使用者。

DeletionType

刪除訊息的使用者及其刪除方式。

列舉
DELETION_TYPE_UNSPECIFIED 未使用這個值。
CREATOR 使用者刪除了自己的訊息。
SPACE_OWNER 聊天室擁有者已刪除訊息。
ADMIN Google Workspace 管理員已刪除這則訊息。
APP_MESSAGE_EXPIRY Chat 應用程式會在訊息到期時刪除自己的訊息。
CREATOR_VIA_APP Chat 應用程式已代表使用者刪除訊息。
SPACE_OWNER_VIA_APP 某個 Chat 應用程式代表聊天室擁有者刪除訊息。

QuotedMessageMetadata

引用訊息的相關資訊。

JSON 表示法
{
  "name": string,
  "lastUpdateTime": string
}
欄位
name

string

僅供輸出。引用訊息的資源名稱。

格式︰spaces/{space}/messages/{message}

lastUpdateTime

string (Timestamp format)

僅供輸出。引用訊息的建立時間,或引用訊息上次更新的時間。

AttachedGif

以網址指定的 GIF 圖片。

JSON 表示法
{
  "uri": string
}
欄位
uri

string

僅供輸出。代管 GIF 圖片的網址。

AccessoryWidget

郵件底部會顯示一或多個互動式小工具。詳情請參閱在郵件底部新增互動式小工具

JSON 表示法
{

  // Union field action can be only one of the following:
  "buttonList": {
    object (ButtonList)
  }
  // End of list of possible types for union field action.
}
欄位

聯集欄位 action

action 只能採用下列其中一種設定:

buttonList

object (ButtonList)

按鈕清單。

方法

create

在 Google Chat 聊天室中建立訊息。

delete

刪除訊息。

get

傳回訊息的詳細資料。

list

列出來電者所屬聊天室中的訊息,包括已封鎖的成員和聊天室的訊息。

patch

更新訊息。

update

更新訊息。