REST Resource: phones.agentMessages

資源:AgentMessage

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

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

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
欄位
name

string

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

sendTime

string (Timestamp format)

這個欄位是由 RBM 平台所設定。建立服務專員訊息時,請勿加入這類資訊。這個欄位會解析郵件傳送給使用者的時間。

使用 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)

訊息流量類型。

聯集欄位 expiration

expiration 只能是下列其中一項:

expireTime

string (Timestamp format)

(選用步驟) 資源到期時間的時間戳記 (世界標準時間)。如果已設定這個值或 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)

(選用步驟) 僅限輸入。訊息在自動撤銷前可存在多久。

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

AgentContentMessage

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

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

  // Union field content can be only one of the following:
  "text": string,
  "fileName": string,
  "uploadedRbmFile": {
    object (UploadedRbmFile)
  },
  "richCard": {
    object (RichCard)
  },
  "contentInfo": {
    object (ContentInfo)
  }
  // End of list of possible types for union field content.
}
欄位
suggestions[]

object (Suggestion)

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

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

聯集欄位 content。代理程式訊息 content 的內容只能是下列其中一項:
text

string

以 UTF-8 編碼的文字。長度上限為 3072 個字元。

fileName
(deprecated)

string

檔案的專屬名稱。服務專員上傳檔案時,RBM 平台會傳回檔案名稱。已淘汰,請改用下方上傳的 Rbm 檔案

uploadedRbmFile

object (UploadedRbmFile)

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

richCard

object (RichCard)

獨立的複合式資訊卡。

contentInfo

object (ContentInfo)

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

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

UploadedRbmFile

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

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

string

檔案名稱,由 RBM 平台在檔案上傳時傳回。

thumbnailName

string

縮圖名稱,由 RBM 平台在縮圖上傳時傳回。

RichCard

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

JSON 表示法
{

  // Union field card can be only one of the following:
  "carouselCard": {
    object (CarouselCard)
  },
  "standaloneCard": {
    object (StandaloneCard)
  }
  // End of list of possible types for union field card.
}
欄位
聯集欄位 card。單一資訊卡或資訊卡輪轉介面。card 只能是下列其中一項:
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

(選用) 知識卡說明。最多 2000 個半形字元。

media

object (Media)

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

suggestions[]

object (Suggestion)

(選用) 要在資訊卡中顯示的建議清單。最多 4 項建議。

媒體

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

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

  // Union field content can be only one of the following:
  "fileName": string,
  "uploadedRbmFile": {
    object (UploadedRbmFile)
  },
  "contentInfo": {
    object (ContentInfo)
  }
  // End of list of possible types for union field content.
}
欄位
height

enum (Media.Height)

直向版面配置的複合式資訊卡中,媒體的高度。如果是採用水平版面配置的獨立資訊卡,系統不會提供自訂高度,且會忽略這個欄位。

聯集欄位 content。媒體內容 content 只能是下列其中一項:
fileName
(deprecated)

string

檔案的專屬名稱,由 RBM 平台在檔案上傳時傳回。已淘汰,請改用下方上傳的 Rbm 檔案

uploadedRbmFile

object (UploadedRbmFile)

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

contentInfo

object (ContentInfo)

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

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

ContentInfo

包含內容資訊的訊息。

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

string

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

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

thumbnailUrl

string

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

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

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

forceRefresh

boolean

如果設定,即使平台已快取檔案 (和/或縮圖) 副本,RBM 平台仍會從指定網址擷取檔案和縮圖。

Media.Height

媒體高度

列舉
HEIGHT_UNSPECIFIED 不指定。
SHORT 112 DP。
MEDIUM 168 DP。
TALL 264 DP。如果資訊卡寬度設為「小」,互動式資訊卡輪播內容就無法使用這項功能。

建議

豐富資訊卡或建議晶片清單中包含的建議回覆或建議動作。

JSON 表示法
{

  // Union field option can be only one of the following:
  "reply": {
    object (SuggestedReply)
  },
  "action": {
    object (SuggestedAction)
  }
  // End of list of possible types for union field option.
}
欄位
聯集欄位 option。建議回覆或建議動作 option 只能是下列其中一項:
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,

  // Union field action can be only one of the following:
  "dialAction": {
    object (DialAction)
  },
  "viewLocationAction": {
    object (ViewLocationAction)
  },
  "createCalendarEventAction": {
    object (CreateCalendarEventAction)
  },
  "openUrlAction": {
    object (OpenUrlAction)
  },
  "shareLocationAction": {
    object (ShareLocationAction)
  }
  // End of list of possible types for union field action.
}
欄位
text

string

建議動作中顯示的文字。最多 25 個半形字元。

postbackData

string

當使用者輕觸建議動作時,系統會在使用者事件中傳送至服務專員的酬載 (以 base64 編碼)。最多 2048 個字元。

fallbackUrl

string

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

聯集欄位 action。使用者輕觸建議動作 action 時,裝置上啟動的原生動作只能是下列其中一項:
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

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

舉例來說,如果將查詢字串設為「松樹銀行」,系統就會顯示使用者附近的所有松樹銀行分行。將查詢字串設為「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)

網頁檢視模式

description

string

網頁檢視區塊的無障礙說明。

OpenUrlApplication

開啟應用程式的網址類型

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

WebviewViewMode

網頁檢視區塊的檢視模式類型。

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

ShareLocationAction

這個類型沒有任何欄位。

開啟 RCS 應用程式的位置選擇器,讓使用者選擇要傳送給代理程式的位置。

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 欄位,則也必須包含至少一個 titledescriptionsuggestions[] 欄位。

VERTICAL 垂直版面配置。

StandaloneCard.ThumbnailImageAlignment

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

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

MessageTrafficType

支援的訊息流量類型。這個列舉會擴充,以支援其他流量類型。

列舉
MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 預設行為:系統會根據代理程式的用途,決定訊息流量類型。視郵件內容,視需要更新流量類型。如果是多用途代理程式,系統不會提供預設值。流量類型必須手動設定 (例如 TRANSACTION、PROMOTION)。
AUTHENTICATION 適用於 OTP 代理程式使用案例中的驗證訊息。
TRANSACTION 在交易或多用途代理程式應用實例中,用於交易訊息。
PROMOTION 在宣傳或多用途代理程式應用情境中,用於宣傳訊息。
SERVICEREQUEST 使用者同意接收的服務相關訊息。用於 OTP、交易、宣傳或多用途代理程式應用實例。
ACKNOWLEDGEMENT 確認使用者取消訂閱要求的訊息。用於 OTP、交易、宣傳或多用途代理程式應用實例。

方法

create

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

delete

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