資源:AgentMessage
服務專員傳送給使用者的訊息。
| JSON 表示法 |
|---|
{ "name": string, "sendTime": string, "contentMessage": { object ( |
| 欄位 | |
|---|---|
name |
這個欄位由 RCS for Business 平台設定。建立代理訊息時,請勿加入這個欄位。這個欄位會解析為「phones/{E.164}/agentMessages/{messageId}」,其中 {E.164} 是使用者的電話號碼 (採用 E.164 格式),{messageId} 則是服務專員指派的服務專員訊息 ID。 |
sendTime |
這個欄位由 RCS for Business 平台設定。建立代理訊息時,請勿加入這個欄位。這個欄位會解析訊息傳送給使用者的時間。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
contentMessage |
代理訊息的內容。 |
messageTrafficType |
訊息流量類型。 |
richMessageClassification |
僅供輸出。根據美國帳單模型分類訊息。如要進一步瞭解各分類類型,請參閱美國計費模式指南。這個欄位只會填入美國電話號碼。 |
totalPayloadSizeBytes |
僅供輸出。訊息的總酬載大小 (以位元組為單位)。酬載會計算 RCS for Business 訊息中的所有附件,包括影片、圖片、PDF 等,但不包括訊息文字或建議。目前,這個欄位只會填入美國電話號碼。 |
carrier |
僅供輸出。根據 Google RCS 後端,使用者電話號碼所屬的電信業者資訊。目前,這個欄位只會填入美國電話號碼。 |
| 以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
expireTime |
(選用步驟) 資源到期時間的時間戳記 (世界標準時間)。必須在提交訊息後至少六秒。如果指定的時間戳記在提交後不到六秒,平台會自動調整為六秒。如果時間戳記等於或早於訊息提交時間,系統會傳回 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
ttl |
(選用步驟) 僅供輸入。訊息自動撤銷前的保留時間。最短為六秒。如果指定的時間長度為正值且小於六秒,平台會自動調整為六秒,並在回應的 以秒為單位的時間長度,最多 9 個小數位數,結尾為「 |
| 互斥欄位結束。 | |
AgentContentMessage
代理傳送給使用者的訊息內容。
| JSON 表示法 |
|---|
{ "suggestions": [ { object ( |
| 欄位 | |
|---|---|
suggestions[] |
建議回覆和建議動作清單,會以建議方塊清單的形式顯示在相關聯的代理訊息後方。最多 11 項建議。 只有在相關聯的服務專員訊息是對話中最新訊息 (包括服務專員和使用者訊息) 時,才會顯示方塊。使用者可以輕觸建議回覆,將文字回覆傳送給服務專員,也可以輕觸建議動作,在裝置上啟動原生動作。 建議模式分為兩種:永久和暫時。詳情請參閱「建議」。 |
| 代理訊息的內容。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
text |
以 UTF-8 編碼的文字。最多 3072 個半形字元。 |
fileName |
檔案的專屬名稱。代理上傳檔案時,RCS for Business 平台會傳回檔案名稱。已淘汰,改用下方的 uploadedRbmFile。 |
uploadedRbmFile |
包含上傳至 RCS for Business 伺服器並由該伺服器提供的檔案和縮圖 ID。 |
richCard |
獨立複合式資訊卡。 |
contentInfo |
檔案相關資訊,包括檔案網址和檔案縮圖網址。 RCS for Business 平台會從快取提供內容,但代理可以強制 RCS for Business 平台擷取新版內容並重新整理快取。 |
| 互斥欄位結束。 | |
UploadedRbmFile
包含檔案和縮圖資訊的訊息
| JSON 表示法 |
|---|
{ "fileName": string, "thumbnailName": string } |
| 欄位 | |
|---|---|
fileName |
檔案上傳時,RCS for Business 平台傳回的檔案名稱。 |
thumbnailName |
縮圖名稱,由 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 |
獨立卡片。 |
| 互斥欄位結束。 | |
CarouselCard
資訊卡輪轉介面。
| JSON 表示法 |
|---|
{ "cardWidth": enum ( |
| 欄位 | |
|---|---|
cardWidth |
輪轉介面中資訊卡的寬度。 |
cardContents[] |
輪轉介面中每張資訊卡的內容清單。輪轉介面最少可有 2 張資訊卡,最多 10 張。 |
CarouselCard.CardWidth
輪轉介面中資訊卡的寬度。
| 列舉 | |
|---|---|
CARD_WIDTH_UNSPECIFIED |
不指定。 |
SMALL |
120 DP。 |
MEDIUM |
232 DP。 |
CardContent
資訊卡內容
| JSON 表示法 |
|---|
{ "title": string, "description": string, "media": { object ( |
| 欄位 | |
|---|---|
title |
(選用) 資訊卡標題。長度上限為 200 個半形字元。 |
description |
(選用) 資訊卡說明。最多 2,000 個半形字元。 |
media |
(選用) 要加入資訊卡的媒體 (圖片、GIF、影片、PDF)。 |
suggestions[] |
(選用) 要納入資訊卡的建議清單。最多 4 項建議。 |
媒體
複合式資訊卡中的媒體檔案。
| JSON 表示法 |
|---|
{ "height": enum ( |
| 欄位 | |
|---|---|
height |
垂直版面配置複合式資訊卡中的媒體高度。如果是水平版面配置的獨立資訊卡,請使用 |
contentDescription |
(選用步驟) 描述媒體內容,提供替代文字,方便使用者存取。最多可輸入 200 個純文字字元。 |
| 媒體內容以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
fileName |
檔案的專屬名稱,由 RCS for Business 平台在上傳檔案時傳回。已淘汰,改用下方的 uploadedRbmFile。 |
uploadedRbmFile |
包含上傳至 RCS for Business 伺服器並由該伺服器提供的檔案和縮圖 ID。 |
contentInfo |
檔案相關資訊,包括檔案網址和檔案縮圖網址。 RCS for Business 平台會從快取提供內容,但代理可以強制 RCS for Business 平台擷取新版內容並重新整理快取。 |
| 互斥欄位結束。 | |
ContentInfo
包含內容資訊的訊息。
| JSON 表示法 |
|---|
{ "fileUrl": string, "thumbnailUrl": string, "forceRefresh": boolean } |
| 欄位 | |
|---|---|
fileUrl |
可公開存取的檔案網址。RCS for Business 平台擷取檔案時,會根據 HTTP 標頭中的 content-type 欄位,判斷檔案的 MIME 類型。網址的 HTTP 回應中必須包含正確的 content-type 欄位。建議檔案大小上限為 100 MB。 注意:檔案網址不支援重新導向。如需重新導向,請使用 CreateFileRequest。 |
thumbnailUrl |
(選用,僅適用於圖片、音訊和影片檔案) 縮圖的公開網址。大小上限為 100 kB。 如未提供縮圖網址,RCS for Business 平台會顯示空白的預留位置縮圖,直到使用者裝置下載檔案為止。視使用者的設定而定,檔案可能不會自動下載,使用者可能需要輕觸下載按鈕。 注意:檔案網址不支援重新導向。如需重新導向,請使用 CreateFileRequest。 |
forceRefresh |
如果設定,RCS for Business 平台會從指定網址擷取檔案和縮圖,即使平台已有檔案 (和/或縮圖) 的快取副本也一樣。 |
Media.Height
媒體高度
| 列舉 | |
|---|---|
HEIGHT_UNSPECIFIED |
不指定。 |
SHORT |
112 DP。 |
MEDIUM |
168 DP。 |
TALL |
264 DP。 |
建議
複合式資訊卡或建議方塊清單中的建議回覆或建議動作。
| JSON 表示法 |
|---|
{ "suggestionDisplay": enum ( |
| 欄位 | |
|---|---|
suggestionDisplay |
(選用步驟) 控制建議的顯示行為。僅適用於傳送至 Google 訊息用戶端 (20260225.00 以上版本) 的純文字訊息。這個欄位只能在與純文字訊息相關聯的獨立建議上設定。如果將這個欄位套用至互動式資訊卡中的建議,或含有檔案傳輸的獨立建議,伺服器會拒絕訊息。這項設定只會序列化 Google 訊息,其他用戶端 (例如 iOS 或 Samsung) 會忽略這項設定。 |
| 建議回覆或建議動作。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
reply |
使用者可以輕觸建議回覆,將文字回覆傳送給服務專員。 |
action |
使用者可以輕觸建議動作,在裝置上啟動對應的原生動作。 |
| 互斥欄位結束。 | |
SuggestedReply
輕觸後,系統會將文字回覆傳回給代理。
| JSON 表示法 |
|---|
{ "text": string, "postbackData": string } |
| 欄位 | |
|---|---|
text |
建議回覆中顯示的文字,使用者輕觸後會傳回給服務專員。長度上限為 25 個半形字元。 |
postbackData |
使用者輕觸建議回覆時,代理在使用者事件中收到的 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 ( |
| 欄位 | |
|---|---|
text |
建議動作中顯示的文字。長度上限為 25 個半形字元。 |
postbackData |
使用者輕觸建議動作時,系統會產生使用者事件,並將酬載 (以 Base64 編碼) 傳送給服務專員。最多 2048 個字元。 |
fallbackUrl |
(選用) 如果用戶端不支援建議動作,則使用備用網址。備用網址會在新的瀏覽器視窗中開啟。必須是 RFC 3986 定義的有效 URI。最多 2048 個字元。 |
| 使用者輕觸建議動作時,裝置上啟動的原生動作。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
dialAction |
開啟使用者的預設撥號應用程式,並填入服務專員指定的電話號碼。 |
viewLocationAction |
開啟使用者的預設地圖應用程式,並選取服務專員指定的地點,或根據服務專員指定的查詢,搜尋使用者所在位置附近的地點。 |
createCalendarEventAction |
開啟使用者的預設日曆應用程式,並啟動新的日曆活動流程,預填代理指定的事件資料。 |
openUrlAction |
開啟使用者的預設網路瀏覽器應用程式,並前往指定網址。如果使用者安裝的應用程式已註冊為網址的預設處理常式,系統會改為開啟該應用程式,並在建議動作 UI 中使用其圖示。 |
shareLocationAction |
開啟 RCS 應用程式的位置選擇器,讓使用者選擇要傳送給服務專員的位置。 |
| 互斥欄位結束。 | |
DialAction
開啟使用者的預設撥號應用程式,並填入服務專員指定的電話號碼。
| JSON 表示法 |
|---|
{ "phoneNumber": string } |
| 欄位 | |
|---|---|
phoneNumber |
電話號碼,格式為 E.164,例如 +12223334444。 |
ViewLocationAction
開啟使用者的預設地圖應用程式,並選取服務專員指定的地點,或根據服務專員指定的查詢,搜尋使用者所在位置附近的地點。
| JSON 表示法 |
|---|
{
"latLong": {
object ( |
| 欄位 | |
|---|---|
latLong |
(選用) 指定位置的經緯度。 |
label |
(選用) 在 latLong 放置的圖釘標籤。 |
query |
(選用) 代理程式可以指定查詢字串,而非指定 latLong (和選用的標籤)。如果預設地圖應用程式支援搜尋功能 (包括 Google 地圖),輕觸這項建議動作會以使用者目前位置為中心,搜尋地點。如果查詢內容夠具體,代理就能用來選取世界上的任何地點。 舉例來說,如果將查詢字串設為「Growing Tree Bank」,系統就會顯示使用者附近的所有 Growing Tree Bank 據點。如果將查詢字串設為「1600 Amphitheater Parkway, Mountain View, CA 94043」,無論使用者位於何處,系統都會選取該特定地址。 |
LatLng
代表經緯度組合的物件。這個物件會同時指出經度和緯度的度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。
| JSON 表示法 |
|---|
{ "latitude": number, "longitude": number } |
| 欄位 | |
|---|---|
latitude |
緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。 |
longitude |
經度度數,必須介於 [-180.0, +180.0] 的範圍之間。 |
CreateCalendarEventAction
開啟使用者的預設日曆應用程式,並啟動新的日曆活動流程,預填代理指定的事件資料。
| JSON 表示法 |
|---|
{ "startTime": string, "endTime": string, "title": string, "description": string } |
| 欄位 | |
|---|---|
startTime |
活動開始時間。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
endTime |
活動結束時間。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
title |
活動名稱。最多 100 個字元。 |
description |
事件說明。最多 500 個字元。 |
OpenUrlAction
開啟使用者的預設網路瀏覽器應用程式,並前往指定網址。如果使用者安裝的應用程式已註冊為網址的預設處理常式,系統會改為開啟該應用程式,並在建議動作 UI 中使用其圖示。
| JSON 表示法 |
|---|
{ "url": string, "application": enum ( |
| 欄位 | |
|---|---|
url |
要開啟的網址。2025 年 11 月 1 日起,網址配置必須是 https:// 或 http://。屆時,使用其他配置 (例如 tel:、mailto:、sms:) 的 API 要求都會遭到拒絕,並傳回 400 Bad Request 錯誤。網址必須是 RFC 3986 定義的有效 URI。最多 2048 個字元。 |
application |
網址開啟應用程式、瀏覽器或網頁檢視。如要確認使用者的裝置是否支援 WebView 模式,請先執行功能檢查。詳情請參閱說明文件:https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities。 |
webviewViewMode |
WebView 的檢視模式。 |
description |
網頁檢視的無障礙說明。 |
OpenUrlApplication
網址開啟應用程式的類型
| 列舉 | |
|---|---|
OPEN_URL_APPLICATION_UNSPECIFIED |
未指定,將使用瀏覽器開啟。 |
BROWSER |
使用瀏覽器開啟網址。 |
WEBVIEW |
在整合式網頁檢視視窗中開啟網址 |
WebviewViewMode
網頁檢視畫面的檢視模式類型。
| 列舉 | |
|---|---|
WEBVIEW_VIEW_MODE_UNSPECIFIED |
不指定。如要使用 WebView,必須指定檢視模式。 |
FULL |
必須使用全螢幕疊加層,並在狀態列中標示聊天機器人對話。 |
HALF |
需要半螢幕疊加層。 |
TALL |
需要四分之三螢幕重疊。 |
Suggestion.SuggestionDisplay
獨立文字建議的顯示行為。
| 列舉 | |
|---|---|
SUGGESTION_DISPLAY_UNSPECIFIED |
用戶端會執行預設顯示行為:
|
PERSISTENT |
即使對話中加入新訊息,建議仍會持續顯示在訊息泡泡中。 |
StandaloneCard
獨立卡片
| JSON 表示法 |
|---|
{ "cardOrientation": enum ( |
| 欄位 | |
|---|---|
cardOrientation |
卡片方向。 |
thumbnailImageAlignment |
水平版面配置獨立資訊卡的圖片預覽對齊方式。 |
cardContent |
資訊卡內容。 |
StandaloneCard.CardOrientation
卡片方向。
| 列舉 | |
|---|---|
CARD_ORIENTATION_UNSPECIFIED |
不指定。 |
HORIZONTAL |
水平版面配置。 如果橫向複合式資訊卡 |
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 ( |
| 欄位 | |
|---|---|
classificationType |
|
segmentCount |
訊息文字的 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 訊息。 |
方法 |
|
|---|---|
|
將訊息從代理傳送給使用者。 |
|
撤銷已傳送但尚未送達的服務專員訊息。 |