REST Resource: phones.agentMessages

資源:AgentMessage

服務專員傳送給使用者的訊息。

JSON 表示法
{
  "name": string,
  "sendTime": string,
  "contentMessage": {
    object (AgentContentMessage)
  },
  "messageTrafficType": enum (MessageTrafficType),
  "richMessageClassification": {
    object (RichMessageClassification)
  },
  "totalPayloadSizeBytes": string,
  "carrier": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "expireTime": string,
  "ttl": string
  // End of mutually exclusive fields.
}
欄位
name

string

這個欄位由 RCS for Business 平台設定。建立代理訊息時,請勿加入這個欄位。這個欄位會解析為「phones/{E.164}/agentMessages/{messageId}」,其中 {E.164} 是使用者的電話號碼 (採用 E.164 格式),{messageId} 則是服務專員指派的服務專員訊息 ID。

sendTime

string (Timestamp format)

這個欄位由 RCS for Business 平台設定。建立代理訊息時,請勿加入這個欄位。這個欄位會解析訊息傳送給使用者的時間。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

contentMessage

object (AgentContentMessage)

代理訊息的內容。

messageTrafficType

enum (MessageTrafficType)

訊息流量類型。

richMessageClassification

object (RichMessageClassification)

僅供輸出。根據美國帳單模型分類訊息。如要進一步瞭解各分類類型,請參閱美國計費模式指南。這個欄位只會填入美國電話號碼。

totalPayloadSizeBytes

string (int64 format)

僅供輸出。訊息的總酬載大小 (以位元組為單位)。酬載會計算 RCS for Business 訊息中的所有附件,包括影片、圖片、PDF 等,但不包括訊息文字或建議。目前,這個欄位只會填入美國電話號碼。

carrier

string

僅供輸出。根據 Google RCS 後端,使用者電話號碼所屬的電信業者資訊。目前,這個欄位只會填入美國電話號碼。

以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
expireTime

string (Timestamp format)

(選用步驟) 資源到期時間的時間戳記 (世界標準時間)。必須在提交訊息後至少六秒。如果指定的時間戳記在提交後不到六秒,平台會自動調整為六秒。如果時間戳記等於或早於訊息提交時間,系統會傳回 400 INVALID_ARGUMENT 錯誤。如果要求中設定了 expireTime 或 ttl,系統會在輸出內容中傳回這個值,並反映對該值的任何調整。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

ttl

string (Duration format)

(選用步驟) 僅供輸入。訊息自動撤銷前的保留時間。最短為六秒。如果指定的時間長度為正值且小於六秒,平台會自動調整為六秒,並在回應的 expireTime 欄位中反映調整後的值。任何非正數時間長度 (零或以下) 都會傳回 400 INVALID_ARGUMENT 錯誤。

以秒為單位的時間長度,最多 9 個小數位數,結尾為「s」。例如:"3.5s"。

互斥欄位結束。

AgentContentMessage

代理傳送給使用者的訊息內容。

JSON 表示法
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ],

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "text": string,
  "fileName": string,
  "uploadedRbmFile": {
    object (UploadedRbmFile)
  },
  "richCard": {
    object (RichCard)
  },
  "contentInfo": {
    object (ContentInfo)
  }
  // End of mutually exclusive fields.
}
欄位
suggestions[]

object (Suggestion)

建議回覆和建議動作清單,會以建議方塊清單的形式顯示在相關聯的代理訊息後方。最多 11 項建議。

只有在相關聯的服務專員訊息是對話中最新訊息 (包括服務專員和使用者訊息) 時,才會顯示方塊。使用者可以輕觸建議回覆,將文字回覆傳送給服務專員,也可以輕觸建議動作,在裝置上啟動原生動作。

建議模式分為兩種:永久和暫時。詳情請參閱「建議」。

代理訊息的內容。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
text

string

以 UTF-8 編碼的文字。最多 3072 個半形字元。

fileName
(deprecated)

string

檔案的專屬名稱。代理上傳檔案時,RCS for Business 平台會傳回檔案名稱。已淘汰,改用下方的 uploadedRbmFile。

uploadedRbmFile

object (UploadedRbmFile)

包含上傳至 RCS for Business 伺服器並由該伺服器提供的檔案和縮圖 ID。

richCard

object (RichCard)

獨立複合式資訊卡。

contentInfo

object (ContentInfo)

檔案相關資訊,包括檔案網址和檔案縮圖網址。

RCS for Business 平台會從快取提供內容,但代理可以強制 RCS for Business 平台擷取新版內容並重新整理快取。

互斥欄位結束。

UploadedRbmFile

包含檔案和縮圖資訊的訊息

JSON 表示法
{
  "fileName": string,
  "thumbnailName": string
}
欄位
fileName

string

檔案上傳時,RCS for Business 平台傳回的檔案名稱。

thumbnailName

string

縮圖名稱,由 RCS for Business 平台在上傳縮圖時傳回。

RichCard

服務專員傳送給使用者的獨立複合式資訊卡或輪轉複合式資訊卡。

JSON 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "carouselCard": {
    object (CarouselCard)
  },
  "standaloneCard": {
    object (StandaloneCard)
  }
  // End of mutually exclusive fields.
}
欄位
獨立資訊卡或資訊卡輪轉介面。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
carouselCard

object (CarouselCard)

資訊卡輪轉介面。

standaloneCard

object (StandaloneCard)

獨立卡片。

互斥欄位結束。

CarouselCard

資訊卡輪轉介面。

JSON 表示法
{
  "cardWidth": enum (CarouselCard.CardWidth),
  "cardContents": [
    {
      object (CardContent)
    }
  ]
}
欄位
cardWidth

enum (CarouselCard.CardWidth)

輪轉介面中資訊卡的寬度。

cardContents[]

object (CardContent)

輪轉介面中每張資訊卡的內容清單。輪轉介面最少可有 2 張資訊卡,最多 10 張。

CarouselCard.CardWidth

輪轉介面中資訊卡的寬度。

列舉
CARD_WIDTH_UNSPECIFIED 不指定。
SMALL 120 DP。
MEDIUM 232 DP。

CardContent

資訊卡內容

JSON 表示法
{
  "title": string,
  "description": string,
  "media": {
    object (Media)
  },
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
欄位
title

string

(選用) 資訊卡標題。長度上限為 200 個半形字元。

description

string

(選用) 資訊卡說明。最多 2,000 個半形字元。

media

object (Media)

(選用) 要加入資訊卡的媒體 (圖片、GIF、影片、PDF)。

suggestions[]

object (Suggestion)

(選用) 要納入資訊卡的建議清單。最多 4 項建議。

媒體

複合式資訊卡中的媒體檔案。

JSON 表示法
{
  "height": enum (Media.Height),
  "contentDescription": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "fileName": string,
  "uploadedRbmFile": {
    object (UploadedRbmFile)
  },
  "contentInfo": {
    object (ContentInfo)
  }
  // End of mutually exclusive fields.
}
欄位
height

enum (Media.Height)

垂直版面配置複合式資訊卡中的媒體高度。如果是水平版面配置的獨立資訊卡,請使用 TALL 而非 HEIGHT_UNSPECIFIED,以確保與 iOS 相容。

contentDescription

string

(選用步驟) 描述媒體內容,提供替代文字,方便使用者存取。最多可輸入 200 個純文字字元。

媒體內容以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
fileName
(deprecated)

string

檔案的專屬名稱,由 RCS for Business 平台在上傳檔案時傳回。已淘汰,改用下方的 uploadedRbmFile。

uploadedRbmFile

object (UploadedRbmFile)

包含上傳至 RCS for Business 伺服器並由該伺服器提供的檔案和縮圖 ID。

contentInfo

object (ContentInfo)

檔案相關資訊,包括檔案網址和檔案縮圖網址。

RCS for Business 平台會從快取提供內容,但代理可以強制 RCS for Business 平台擷取新版內容並重新整理快取。

互斥欄位結束。

ContentInfo

包含內容資訊的訊息。

JSON 表示法
{
  "fileUrl": string,
  "thumbnailUrl": string,
  "forceRefresh": boolean
}
欄位
fileUrl

string

可公開存取的檔案網址。RCS for Business 平台擷取檔案時,會根據 HTTP 標頭中的 content-type 欄位,判斷檔案的 MIME 類型。網址的 HTTP 回應中必須包含正確的 content-type 欄位。建議檔案大小上限為 100 MB。

注意:檔案網址不支援重新導向。如需重新導向,請使用 CreateFileRequest。

thumbnailUrl

string

(選用,僅適用於圖片、音訊和影片檔案) 縮圖的公開網址。大小上限為 100 kB。

如未提供縮圖網址,RCS for Business 平台會顯示空白的預留位置縮圖,直到使用者裝置下載檔案為止。視使用者的設定而定,檔案可能不會自動下載,使用者可能需要輕觸下載按鈕。

注意:檔案網址不支援重新導向。如需重新導向,請使用 CreateFileRequest。

forceRefresh

boolean

如果設定,RCS for Business 平台會從指定網址擷取檔案和縮圖,即使平台已有檔案 (和/或縮圖) 的快取副本也一樣。

Media.Height

媒體高度

列舉
HEIGHT_UNSPECIFIED 不指定。
SHORT 112 DP。
MEDIUM 168 DP。
TALL 264 DP。

建議

複合式資訊卡或建議方塊清單中的建議回覆或建議動作。

JSON 表示法
{
  "suggestionDisplay": enum (Suggestion.SuggestionDisplay),

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "reply": {
    object (SuggestedReply)
  },
  "action": {
    object (SuggestedAction)
  }
  // End of mutually exclusive fields.
}
欄位
suggestionDisplay

enum (Suggestion.SuggestionDisplay)

(選用步驟) 控制建議的顯示行為。僅適用於傳送至 Google 訊息用戶端 (20260225.00 以上版本) 的純文字訊息。這個欄位只能在與純文字訊息相關聯的獨立建議上設定。如果將這個欄位套用至互動式資訊卡中的建議,或含有檔案傳輸的獨立建議,伺服器會拒絕訊息。這項設定只會序列化 Google 訊息,其他用戶端 (例如 iOS 或 Samsung) 會忽略這項設定。

建議回覆或建議動作。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
reply

object (SuggestedReply)

使用者可以輕觸建議回覆,將文字回覆傳送給服務專員。

action

object (SuggestedAction)

使用者可以輕觸建議動作,在裝置上啟動對應的原生動作。

互斥欄位結束。

SuggestedReply

輕觸後,系統會將文字回覆傳回給代理。

JSON 表示法
{
  "text": string,
  "postbackData": string
}
欄位
text

string

建議回覆中顯示的文字,使用者輕觸後會傳回給服務專員。長度上限為 25 個半形字元。

postbackData

string

使用者輕觸建議回覆時,代理在使用者事件中收到的 Base64 編碼酬載。

SuggestedAction

輕觸後,會在裝置上啟動對應的原生動作。

JSON 表示法
{
  "text": string,
  "postbackData": string,
  "fallbackUrl": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "dialAction": {
    object (DialAction)
  },
  "viewLocationAction": {
    object (ViewLocationAction)
  },
  "createCalendarEventAction": {
    object (CreateCalendarEventAction)
  },
  "openUrlAction": {
    object (OpenUrlAction)
  },
  "shareLocationAction": {
    object (ShareLocationAction)
  }
  // End of mutually exclusive fields.
}
欄位
text

string

建議動作中顯示的文字。長度上限為 25 個半形字元。

postbackData

string

使用者輕觸建議動作時,系統會產生使用者事件,並將酬載 (以 Base64 編碼) 傳送給服務專員。最多 2048 個字元。

fallbackUrl

string

(選用) 如果用戶端不支援建議動作,則使用備用網址。備用網址會在新的瀏覽器視窗中開啟。必須是 RFC 3986 定義的有效 URI。最多 2048 個字元。

使用者輕觸建議動作時,裝置上啟動的原生動作。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
dialAction

object (DialAction)

開啟使用者的預設撥號應用程式,並填入服務專員指定的電話號碼。

viewLocationAction

object (ViewLocationAction)

開啟使用者的預設地圖應用程式,並選取服務專員指定的地點,或根據服務專員指定的查詢,搜尋使用者所在位置附近的地點。

createCalendarEventAction

object (CreateCalendarEventAction)

開啟使用者的預設日曆應用程式,並啟動新的日曆活動流程,預填代理指定的事件資料。

openUrlAction

object (OpenUrlAction)

開啟使用者的預設網路瀏覽器應用程式,並前往指定網址。如果使用者安裝的應用程式已註冊為網址的預設處理常式,系統會改為開啟該應用程式,並在建議動作 UI 中使用其圖示。

shareLocationAction

object (ShareLocationAction)

開啟 RCS 應用程式的位置選擇器,讓使用者選擇要傳送給服務專員的位置。

互斥欄位結束。

DialAction

開啟使用者的預設撥號應用程式,並填入服務專員指定的電話號碼。

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

string

電話號碼,格式為 E.164,例如 +12223334444。

ViewLocationAction

開啟使用者的預設地圖應用程式,並選取服務專員指定的地點,或根據服務專員指定的查詢,搜尋使用者所在位置附近的地點。

JSON 表示法
{
  "latLong": {
    object (LatLng)
  },
  "label": string,
  "query": string
}
欄位
latLong

object (LatLng)

(選用) 指定位置的經緯度。

label

string

(選用) 在 latLong 放置的圖釘標籤。

query

string

(選用) 代理程式可以指定查詢字串,而非指定 latLong (和選用的標籤)。如果預設地圖應用程式支援搜尋功能 (包括 Google 地圖),輕觸這項建議動作會以使用者目前位置為中心,搜尋地點。如果查詢內容夠具體,代理就能用來選取世界上的任何地點。

舉例來說,如果將查詢字串設為「Growing Tree Bank」,系統就會顯示使用者附近的所有 Growing Tree Bank 據點。如果將查詢字串設為「1600 Amphitheater Parkway, Mountain View, CA 94043」,無論使用者位於何處,系統都會選取該特定地址。

LatLng

代表經緯度組合的物件。這個物件會同時指出經度和緯度的度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。

JSON 表示法
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。

longitude

number

經度度數,必須介於 [-180.0, +180.0] 的範圍之間。

CreateCalendarEventAction

開啟使用者的預設日曆應用程式,並啟動新的日曆活動流程,預填代理指定的事件資料。

JSON 表示法
{
  "startTime": string,
  "endTime": string,
  "title": string,
  "description": string
}
欄位
startTime

string (Timestamp format)

活動開始時間。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

endTime

string (Timestamp format)

活動結束時間。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

title

string

活動名稱。最多 100 個字元。

description

string

事件說明。最多 500 個字元。

OpenUrlAction

開啟使用者的預設網路瀏覽器應用程式,並前往指定網址。如果使用者安裝的應用程式已註冊為網址的預設處理常式,系統會改為開啟該應用程式,並在建議動作 UI 中使用其圖示。

JSON 表示法
{
  "url": string,
  "application": enum (OpenUrlApplication),
  "webviewViewMode": enum (WebviewViewMode),
  "description": string
}
欄位
url

string

要開啟的網址。2025 年 11 月 1 日起,網址配置必須是 https:// 或 http://。屆時,使用其他配置 (例如 tel:、mailto:、sms:) 的 API 要求都會遭到拒絕,並傳回 400 Bad Request 錯誤。網址必須是 RFC 3986 定義的有效 URI。最多 2048 個字元。

application

enum (OpenUrlApplication)

網址開啟應用程式、瀏覽器或網頁檢視。如要確認使用者的裝置是否支援 WebView 模式,請先執行功能檢查。詳情請參閱說明文件:https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities。

webviewViewMode

enum (WebviewViewMode)

WebView 的檢視模式。

description

string

網頁檢視的無障礙說明。

OpenUrlApplication

網址開啟應用程式的類型

列舉
OPEN_URL_APPLICATION_UNSPECIFIED 未指定,將使用瀏覽器開啟。
BROWSER 使用瀏覽器開啟網址。
WEBVIEW 在整合式網頁檢視視窗中開啟網址

WebviewViewMode

網頁檢視畫面的檢視模式類型。

列舉
WEBVIEW_VIEW_MODE_UNSPECIFIED 不指定。如要使用 WebView,必須指定檢視模式。
FULL 必須使用全螢幕疊加層,並在狀態列中標示聊天機器人對話。
HALF 需要半螢幕疊加層。
TALL 需要四分之三螢幕重疊。

ShareLocationAction

這個類型沒有任何欄位。

開啟 RCS 應用程式的位置選擇器,讓使用者選擇要傳回給服務專員的位置。

Suggestion.SuggestionDisplay

獨立文字建議的顯示行為。

列舉
SUGGESTION_DISPLAY_UNSPECIFIED

用戶端會執行預設顯示行為:

  • Google 訊息 (獨立純文字訊息):傳送或接收新訊息後,建議就會消失。
  • iOS 獨立純文字訊息:使用者輕觸建議後,建議才會消失。
  • 所有複合式資訊卡用戶端:建議一律會持續顯示;在複合式資訊卡上設定 suggestionDisplay 會導致 400 錯誤。
PERSISTENT 即使對話中加入新訊息,建議仍會持續顯示在訊息泡泡中。

StandaloneCard

獨立卡片

JSON 表示法
{
  "cardOrientation": enum (StandaloneCard.CardOrientation),
  "thumbnailImageAlignment": enum (StandaloneCard.ThumbnailImageAlignment),
  "cardContent": {
    object (CardContent)
  }
}
欄位
cardOrientation

enum (StandaloneCard.CardOrientation)

卡片方向。

thumbnailImageAlignment

enum (StandaloneCard.ThumbnailImageAlignment)

水平版面配置獨立資訊卡的圖片預覽對齊方式。

cardContent

object (CardContent)

資訊卡內容。

StandaloneCard.CardOrientation

卡片方向。

列舉
CARD_ORIENTATION_UNSPECIFIED 不指定。
HORIZONTAL

水平版面配置。

如果橫向複合式資訊卡 object(CardContent) 包含 media 欄位,則必須至少包含 title、description 或 suggestions[] 欄位。

VERTICAL 直式版面配置。

StandaloneCard.ThumbnailImageAlignment

水平版面配置獨立資訊卡的圖片預覽對齊方式。

列舉
THUMBNAIL_IMAGE_ALIGNMENT_UNSPECIFIED 不指定。
LEFT 檔案預覽畫面靠左對齊。
RIGHT 檔案預覽畫面靠右對齊。

MessageTrafficType

支援的訊息流量類型。列舉將會擴充,以支援其他流量類型。請注意,雖然代理用途可提供要使用的流量類型指引,但 API 不會強制執行其關係。

列舉
MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 預設行為:訊息流量類型取決於代理的使用情境。請根據訊息內容,視需要更新流量類型。多用途代理則沒有預設值。流量類型應手動設定 (例如 TRANSACTION、PROMOTION)。
AUTHENTICATION 驗證訊息 (建議用於動態密碼代理程式)。
TRANSACTION 用於交易訊息 (建議用於交易或多用途服務專員)。
PROMOTION 宣傳訊息 (建議用於宣傳或多用途服務專員)。
SERVICEREQUEST 用於傳送使用者同意接收的服務相關訊息 (建議用於動態密碼、交易、宣傳或多用途服務專員)。
ACKNOWLEDGEMENT 用於確認使用者取消訂閱要求的訊息 (建議用於動態密碼、交易、宣傳或多用途服務專員)。

RichMessageClassification

僅適用於美國帳單:用於計費的訊息分類詳細資料。

JSON 表示法
{
  "classificationType": enum (RichMessageClassificationType),
  "segmentCount": integer
}
欄位
classificationType

enum (RichMessageClassificationType)

segmentCount

integer

訊息文字的 160 位元組區隔數量,一律無條件進位。

計算方式僅依據文字內容的 UTF-8 位元組總長度,不含建議回覆或動作的資料。

舉例來說,長度為 300 個位元組的簡訊,其 segmentCount 為 2。

這個欄位只會填入 RICH_MESSAGE 類型。

RichMessageClassificationType

僅限美國帳單:指定訊息的帳單分類。

重要事項:美國電信業者會設定本頁所述可計費訊息類型的價格。美國電信業者也會決定開發人員傳送 RCS for Business 訊息的最終費用。如需其他定價或帳單資訊,請洽詢相關電信業者代表。

列舉
RICH_MESSAGE_CLASSIFICATION_TYPE_UNSPECIFIED 未指定
RICH_MESSAGE 符合下列條件時,訊息會歸類為「RICH」:1. 不含複合式資訊卡。2. 不含檔案附件。3. 其中包含的任何建議動作都必須是撥號動作,或是不使用 WebView 的開啟網址動作。
RICH_MEDIA_MESSAGE 不符合 RICH_MESSAGE 條件的訊息。包括含有複合式資訊卡、媒體檔案或任何建議動作 (「撥號」或「在瀏覽器中開啟網址」除外) 的訊息。
SUGGESTED_ACTION_CLICK 代表使用者輕觸建議動作 (而非建議回覆)。這項分類僅適用於使用者動作,且只會顯示在 Webhook 的 UserMessage 酬載中。不適用於 A2P 訊息。

方法

create

將訊息從代理傳送給使用者。

delete

撤銷已傳送但尚未送達的服務專員訊息。