RCS for Business 代理會透過收發訊息與使用者通訊。如要傳送訊息給使用者,代理會向 RCS 企業訊息 API 傳送訊息要求。單一要求可包含文字、複合式資訊卡、媒體和 PDF 檔案、建議回覆和建議的動作。
RCS for Business 平台會在特定情況下傳回錯誤,協助您管理訊息傳送:
- 如果傳送訊息給裝置不支援 RCS 或未啟用 RCS 的使用者,RCS for Business 平台會傳回
404 NOT_FOUND錯誤。在這種情況下,您可以嘗試透過基礎架構中定義的備用方法與使用者聯絡。 - 如果傳送訊息給 RCS 使用者,但對方的網路尚未推出代理,或未啟用 RCS 流量,RCS for Business 平台會傳回
404 NOT_FOUND錯誤。 - 如果傳送的訊息含有使用者裝置不支援的功能,RCS for Business 平台會傳回
400 INVALID_ARGUMENT錯誤,且不會傳送訊息。
在多管道訊息策略中,最好撤銷在合理時間內未送達的訊息,並透過其他管道傳送。如要在預先定義的時間自動撤銷訊息,請設定訊息到期時間。
接收者目前不在線上
如果收件者離線,RCS for Business 平台仍會接受訊息傳送。您會收到 200 OK 回應,RCS for Business 平台會保留訊息,並在 30 天內嘗試重新傳送。不必請 RCS for Business 再次傳送訊息。
RCS for Business 會在提交 30 天後刪除所有未送達的訊息。
視代理的使用案例而定,您可能需要在 30 天逾時前撤銷未送達的訊息。撤銷功能可防止離線使用者在重新上線時收到過時訊息。撤銷訊息的方法有多種:
設定郵件到期日
代理的回覆是否具有時效性?例如,動態密碼的有效時間很短。限時優惠到期。預約提醒在預約日期過後就不再相關。為確保訊息符合時效和相關性,請設定訊息到期時間。這樣一來,離線使用者重新上線時,就不會收到過時內容。到期時間也是叫用備用訊息策略的好時機,可讓使用者及時取得所需資訊。
如要設定訊息到期時間,請在服務專員訊息中指定下列其中一個欄位:
expireTime:訊息到期的確切時間 (世界標準時間)。ttl(存留時間):訊息到期前的時間長度。
如需格式和值選項,請參閱 AgentMessage。
ttl 和 expireTime 的最大值為訊息提交後 15 天。
ttl 和 expireTime 的最小值為提交訊息後六秒。
設定訊息到期日的建議
驗證 (動態密碼) 訊息:將
ttl設為訊息提交後 15 秒以上,可大幅降低傳送和撤銷競爭狀況的機率。交易和宣傳訊息:設定較長的到期時間 (至少 60 秒,或視用途而定,設定幾分鐘到幾小時),因為裝置需要額外時間掃描訊息及下載或處理互動式多媒體內容,且使用者可能會短暫斷線 (例如在電梯或隧道中)。
訊息的存留時間 (TTL)
設定 RCS for Business 訊息的存留時間,即指定訊息的有效和可傳送時間。如果訊息未在這段存留時間內成功傳送至使用者裝置,RCS for Business 平台會自動嘗試撤銷訊息。
啟動訊息撤銷程序時,您會要求 RCS for Business 平台停止嘗試傳送特定訊息。不過,這項操作只會影響日後的傳送嘗試。如果使用者的裝置已成功擷取訊息,則訊息正在處理中,RCS for Business 平台無法從使用者的裝置撤銷訊息。
通知相關資訊如下:
在存留時間內傳送訊息:如果使用者的裝置在存留時間到期前上線並收到訊息,您會收到
DELIVERED通知。由於郵件已成功傳送,因此不會傳送撤銷通知。這是最常見且預期的情況。訊息未在 TTL 到期前送達:如果 TTL 在訊息送達使用者裝置前到期 (例如裝置離線),RCS for Business 平台會嘗試撤銷訊息。您會收到
TTL_EXPIRATION_REVOKED通知,表示郵件已成功從傳送佇列中移除。在這種情況下,使用者不會收到訊息。
處理特殊情況的建議
我們的系統會同時處理 RCS for Business 訊息傳送和存留時間到期作業。因此,在極少數情況下,您可能會看到通知時間不符合預期的極端案例。舉例來說,您可能會同時收到傳送和存留時間通知,也可能兩者都收不到。
以下是處理 RCS for Business 訊息通知的建議做法:
DELIVERED通知:如果您收到郵件的DELIVERED通知,代表郵件已送達使用者。您可以放心忽略該特定訊息的任何後續 TTL 通知。TTL_EXPIRATION_REVOKED通知:如果收到狀態為TTL_EXPIRATION_REVOKED的 TTL 通知,表示 RCS for Business 系統已停止嘗試傳送該訊息。請將這則訊息視為未送達,並視需要採取備用策略。TTL 通知顯示其他狀態:如果 TTL 通知顯示其他狀態,表示撤銷嘗試未有定論。
- 如果是動態密碼 (OTP) 等重要訊息,請啟動備用方法。
- 對於非重要訊息,請決定是否要啟動備用機制。
- 沒有通知:在極少數極端情況下,系統可能無法傳送 TTL 通知,用戶端也可能無法產生傳送通知。這種情況極為罕見。
設定訊息流量類型
RBM API 包含 messageTrafficType 欄位,可用於分類訊息。雖然代理用途仍會定義代理行為和適用的業務規則,但 messageTrafficType 可更詳細地分類訊息內容。最終,單一代理就能處理多種用途。目前不會影響現有的代理用途或業務規則。
這個欄位為選填,但建議您現在就設定,以免欄位變成必填時收到錯誤訊息。
如要設定訊息流量類型,請根據每則訊息的內容,指派適當的 messageTrafficType。下表列出支援的流量類型,以及預期的代理程式用途。這項對應關係是預期用量的建議指南,並非 API 目前強制執行的限制。
| 流量類型 | 訊息內容 | 建議的代理用途 |
|---|---|---|
AUTHENTICATION |
驗證訊息。 | 動態密碼 |
TRANSACTION |
與使用者現有服務或產品相關的訊息。例如確認信、付款收據或預訂詳情。 | 交易或多次使用 |
PROMOTION |
用於優惠、折扣、公告或其他宣傳內容等宣傳訊息。 | 促銷或多次使用 |
SERVICEREQUEST |
使用者明確要求的服務相關訊息。 | 動態密碼、交易、宣傳或多用途 |
ACKNOWLEDGEMENT |
用於確認使用者動作 (特別是取消訂閱要求) 的郵件。這表示我們已收到使用者的要求,正在處理中。 | 動態密碼、交易、宣傳或多用途 |
如未設定流量類型,系統會根據代理的用途指派預設類型。
| 代理用途 | 預設流量類型 |
|---|---|
| OTP | AUTHENTICATION |
| 交易 | TRANSACTION |
| 宣傳 | PROMOTION |
| 多用途 | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
多用途代理沒有預設流量類型。您應根據每則訊息的內容,明確設定流量類型。如果不替換 MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 值,系統仍會接受並傳送訊息,但不會指定流量類型分類。
郵件大小限制
整個字串化 AgentMessage 的大小上限為 250 KB。訊息的文字部分則有 3072 個字元的限制。
為避免使用者意外消耗數據,透過 RCS for Business 傳送的檔案大小上限為 100 MiB,且單一 RCS for Business 訊息中所有媒體和 PDF 附件的總大小不得超過 100 MiB。(1 MiB = 1,048,576 個位元組)。詳情請參閱媒體和 PDF 檔案。
文字
最簡單的訊息是由文字組成。文字訊息最適合用於傳達資訊,不需要視覺效果、複雜的互動或回應。
範例
下列程式碼會傳送純文字訊息。如需格式和值選項,請參閱 phones.agentMessages.create。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
基本訊息內容 - 簡訊轉換
電信業者已推出計費模式,支援將簡訊訊息轉移至 RCS for Business。RCS for Business 訊息最多可包含 160 個 UTF-8 字元,稱為基本訊息。
建構傳送基本訊息的要求時,請注意,每個字元都算 1 個位元組 (UTF-8)。如果訊息含有特殊字元 (例如表情符號或多位元組字元集),每個字元會計為 2 到 4 個 UTF-8 字元或更多。
在方塊中輸入文字,檢查長度:
簡訊內容和連結預覽
RCS 用戶端可能會實作連結預覽功能。如果純文字 RCS for Business 訊息包含含有 openGraph 標記的網站網址,用戶端可以產生預覽畫面 (圖片、標題等),提供更豐富的體驗。例如,請參閱含有網址預覽的基本訊息。
請注意,RCS 用戶端可能會允許使用者停用連結預覽功能。
用於驗證使用者身分的動態密碼
您可以使用 RCS for Business 傳送動態密碼 (OTP),透過 SMS Retriever API 自動驗證使用者。目前沒有專門用來讀取 RCS for Business 動態密碼的 API。
Android 裝置的運作方式
如果 Android 應用程式已註冊 SMS Retriever API,API 會監聽格式正確的 RCS for Business 訊息。這則訊息必須包含動態密碼和用於識別應用程式的不重複雜湊。
收到格式正確的 RCS for Business 訊息時,SMS Retriever API 會像處理簡訊動態密碼一樣處理該訊息。雜湊與應用程式比對成功後,系統會擷取動態密碼並轉送至應用程式,自動驗證使用者。
- 用於驗證使用者身分的 RCS for Business 訊息範例:
Your code is <OTP><app hash>. - 範例:
Your code is 123456 M8tue43FGT.
如要進一步瞭解簡訊擷取器和相關 API,請參閱簡訊擷取器說明文件。如要進一步瞭解已註冊 SMS Retriever API 的應用程式如何自動驗證使用者,請參閱這份流程圖。
iOS 裝置的運作方式
在 iOS 裝置上,系統內建的動態密碼處理功能會自動偵測並建議 RCS for Business 動態密碼,以便自動填入,就像簡訊動態密碼一樣。iOS 應用程式不需要整合特定 API,即可讀取動態密碼。
媒體和 PDF 檔案
傳送含有圖片、影片、音訊或 PDF 檔案的訊息時,服務專員必須提供可公開存取的內容網址,或直接上傳檔案。
可傳送的檔案大小上限為 100 MiB,單一訊息中所有媒體和 PDF 附件的總大小不得超過 100 MiB。
媒體壓縮和轉碼
RCS for Business 平台會自動轉碼及壓縮媒體檔案 (例如圖片和影片),再傳送出去,確保檔案能快速載入,並在不同網路和裝置上正常運作。
壓縮作業會根據輸入媒體的品質進行,而非嚴格依據檔案大小限制。這表示即使檔案大小遠低於 100 MiB 的上限,仍可進行壓縮。轉碼標準會不斷變更,因此沒有固定的檔案大小限制,可決定何時略過轉碼。嘗試不同的媒體格式、尺寸和壓縮率,找出最適合酬載的平衡點。
縮圖規格
如果是媒體檔案,您也可以指定縮圖,讓使用者在點選前預覽內容。如果是音訊檔案,系統會使用預設音訊小工具做為預留位置。
- 縮圖檔案大小上限為 100 kB。為提供最佳使用者體驗,建議大小不超過 50 KB。
- 縮圖的顯示比例應與原始檔案一致。
快取和網址管理
RCS for Business 平台會將檔案快取 60 天,API 則會傳回檔案 ID,供服務專員在傳送給使用者的訊息中加入。60 天後,RCS for Business 會從快取中移除檔案。
透過網址指定檔案時,最佳做法是將 contentMessage.forceRefresh 設為 false。如果將 contentMessage.forceRefresh 設為 true,即使網址內容已快取,RCS for Business 仍會強制從指定網址擷取新內容,這會增加向使用者傳送訊息的時間。
檔案網址範例
下列程式碼會傳送圖片。如需格式和值選項,請參閱 AgentContentMessage。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
或者,您也可以先上傳媒體,再透過 files.create 傳送訊息。
檔案上傳範例
下列程式碼會上傳影片檔案和縮圖檔案,然後在訊息中傳送這兩個檔案。如需格式和值選項,請參閱 files.create 和 AgentContentMessage。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: video/mp4" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"# Capture server-specified video file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: image/jpeg" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"# Capture server-specified image file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "uploadedRbmFile": { "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME", "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME" } } }'
支援的媒體類型
RCS for Business 支援下列媒體類型。縮圖僅支援 image/jpeg、image/jpg、image/gif 和 image/png。
| 媒體類型 | 文件類型 | 額外資訊 | 適用於複合式資訊卡 |
|---|---|---|---|
| application/ogg | OGG 音訊 | .ogx | 否 |
| 應用程式/pdf | 是 (僅限印度的 Google 訊息) | ||
| audio/aac | AAC 音訊 | .aac | 否 |
| audio/mp3 | MP3 音訊 | .mp3 | 否 |
| 音訊/mpeg | MPEG 音訊 | .mpeg | 否 |
| audio/mpg | MPG 音訊 | .mp3 | 否 |
| 音訊/mp4 | MP4 音訊 | .mp4 | 否 |
| audio/mp4-latm | MP4-latm 音訊 | .mp4 | 否 |
| audio/3gpp | 3GPP 音訊 | .3gp | 否 |
| 圖片/jpeg | JPEG | .jpeg、.jpg | 是 |
| 圖片/gif | GIF | .gif | 是 |
| 圖片/png | PNG | .png | 是 |
| video/h263 | H263 影片 | .h263 | 是 |
| video/m4v | M4V 影片 | .m4v | 是 |
| video/mp4 | MP4 影片 | .mp4 | 是 |
| video/mpeg4 | MPEG-4 影片 | .mp4、.m4p | 是 |
| 影片/mpeg | MPEG 影片 | .mpeg | 是 |
| video/webm | WEBM 影片 | .webm | 是 |
建議
代理會透過建議方塊清單或複合式資訊卡傳送建議 (建議回覆和建議的動作)。
建議回覆
建議回覆會提供代理知道如何回應的回覆,引導使用者進行對話。
使用者輕觸建議回覆時,代理會收到包含回覆文字和回傳資料的事件。酬載最多可包含 2048 個字元。
範例
下列程式碼會傳送文字和兩則建議回覆。如需格式和值選項,請參閱 SuggestedReply。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
建議採取的動作
建議的動作會運用裝置的內建功能,引導使用者進行對話。代理可以建議使用者撥打號碼、在地圖上開啟位置、分享位置、開啟網址或建立日曆活動。
您可以視需要為每項建議的動作提供備用網址 (最多 2048 個字元)。如果使用者的裝置不支援建議的動作,這個網址會在新的瀏覽器視窗中開啟。
使用者輕觸建議的動作時,代理會收到包含動作回傳資料的事件。
如需格式和值選項,請參閱 SuggestedAction。
建議顯示
顯示建議的方式有兩種:
- Persistent:顯示在訊息泡泡中的建議動作或回覆,在整個對話過程中保持固定。
- 暫時:顯示在訊息泡泡外的建議,會在對話繼續時消失。
支援的訊息格式
- 永久建議:適用於獨立文字訊息和資訊卡。
- 暫時性建議:適用於獨立文字訊息、媒體訊息和互動式資訊卡。
合併建議
您可以在同一則訊息或資訊卡中,同時使用永久和暫時建議。
- 簡訊:建議預設為暫時性。如要讓這些項目留在對話框中,您必須將其設為永久。
- 複合式資訊卡:預設最多支援四個常駐建議。接著,您可以在資訊卡下方,以「方塊清單」的形式新增暫時建議。
建議限制
一則簡訊最多可包含 11 項建議。您加入的任何永久建議都會計入這項總限制。舉例來說,如果包含 4 個永久建議,最多可以新增 7 個暫時建議。
| 建議類型 | 限制 | 顯示位置 |
|---|---|---|
| 永久 | 最多 4 則 | 訊息泡泡內 |
| 暫時性 | 最多 11 | 對話框外 (以方塊顯示) |
字元限制
每項建議最多 25 個半形字元。
建議的動作的網址透明度
為建立使用者信任感,系統會在「開啟網址」建議的動作的建議按鈕中,以第二行文字顯示基礎網址。這項一致的行為適用於獨立文字訊息、互動式資訊卡和輪轉介面。
支援持續性建議的用戶端
- 支援:Google 訊息 (
20260225.00以上版本)。 - 不支援:
20260225.00之前的 Google 訊息版本、iOS 和 Samsung 訊息。
系統通知中的建議
使用者收到訊息時,Google 訊息會直接在 Android 系統通知中顯示第一個符合條件的建議。使用者可以輕觸這項建議來傳送回覆或觸發動作,不必開啟應用程式。
設計訊息時,請留意下列行為:
- 順序很重要:每則通知只會顯示一項建議。如要盡可能提高參與度,請將優先順序最高的建議回覆或動作放在建議清單的第一個位置。
- 排除的動作:系統通知一律不會顯示「分享位置資訊」動作,使用者必須開啟對話才能分享位置資訊。
撥號
「撥號」動作會引導使用者撥打代理指定的電話號碼。電話號碼只能包含數字 (0-9)、加號 (+)、星號 (*) 和井字號 (#)。系統支援 E.164 國際電話號碼格式 (例如 +14155555555),但並非必要。也就是說,+14155555555 和 1011 都是有效項目。
範例
下列程式碼會傳送撥號動作。如需格式和值選項,請參閱 DialAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
查看位置
「查看位置」動作會在使用者的預設地圖應用程式中顯示位置。您可以透過經緯度或根據使用者目前位置的查詢,指定位置。您也可以為地圖應用程式中顯示的圖釘設定自訂標籤。
範例
下列程式碼會傳送查看位置動作。如需格式和值選項,請參閱 ViewLocationAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
分享位置資訊
「分享位置資訊」動作可讓使用者與代理分享位置資訊。使用者可以分享目前位置,或從 Google 地圖應用程式手動選取位置。
範例
下列程式碼會傳送分享位置資訊動作。如需格式和值選項,請參閱 ShareLocationAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
開啟網址
「開啟網址」動作可讓您將使用者導向代理指定的網頁。根據預設,網頁會在使用者瀏覽器中開啟。您也可以設定在 Webview 中開啟網頁。詳情請參閱「使用 WebView 開啟網址」。
Google 訊息專屬
顯示基礎網址:為提高 A2P 訊息的透明度,Google 訊息會在「開啟網址」建議動作中顯示基礎網址。這項異動會影響標準複合式資訊卡和複合式資訊卡輪轉介面中的建議的動作。
網頁連結的應用程式圖示顯示:如果使用者已為網頁設定預設應用程式,系統會開啟該應用程式,而非瀏覽器或 WebView,且建議按鈕會顯示應用程式圖示。如要在 Google 訊息中顯示應用程式圖示,請提供完整的直接網址。如果使用短網址,則會改為顯示預設的「開啟網址」圖示。
範例
下列程式碼會傳送開啟網址動作。如需格式和值選項,請參閱 OpenUrlAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
使用 WebView 開啟網址
「使用 WebView 開啟網址」動作會使用預設瀏覽器的轉譯引擎,在訊息應用程式中載入指定網頁。這樣一來,使用者不必離開 RCS for Business 對話,就能與網頁互動。如果使用者的裝置不支援網頁檢視,網頁就會改在瀏覽器中開啟。如要啟用 Webview,請參閱 OpenURLApplication。
網頁檢視有三種顯示模式。如需格式和值選項,請參閱 WebviewViewMode。
- 完整:網頁會占滿整個螢幕
- 半螢幕:網頁會占據一半的螢幕
- 高:網頁會占據四分之三的螢幕畫面
範例
下列程式碼會傳送「使用 WebView 開啟網址」動作。如需格式和值選項,請參閱 OpenURLAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com", "application": "WEBVIEW", "webviewViewMode": "FULL", "description": "Accessibility description" } } } ] } }'
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { String URL = "https://www.google.com"; // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // Create suggestion to view webpage in full mode Suggestion viewInFullMode = getUrlActionInWebview(URL, "FULL") suggestions.add(viewInFullMode); // create suggestion to view webpage in half mode Suggestion viewInHalfMode = getUrlActionInWebview(URL, "HALF") suggestions.add(viewInHalfMode); // create suggestion to view webpage in tall mode Suggestion viewInTallMode = getUrlActionInWebview(URL, "TALL") suggestions.add(viewInTallMode); // Send simple text message with the suggested action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); } /** * Creates a suggested action to open URL in webview. * * @return a suggestion object for an open URL in webview action . */ private Suggestion getUrlActionInWebview(String url, String viewMode) { // create an open url action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl(url); openUrlAction.setApplication("WEBVIEW"); openUrlAction.setWebviewViewMode(viewMode); openUrlAction.setDescription("Accessibility description"); // attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setOpenUrlAction(openUrlAction); suggestedAction.setText('display_text'); suggestedAction.setPostbackData('postback_data_123'); // attach the action to a suggestion object Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); return suggestion; }
建立日曆活動
「建立日曆活動」動作會開啟使用者的日曆應用程式,並開始使用指定資訊建立新活動。
必須提供日曆活動名稱。長度上限為 100 個半形字元。日曆活動說明為選填,最多 500 個字元。
範例
下列程式碼會傳送建立日曆活動動作。如需格式和值選項,請參閱 CreateCalendarEventAction。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
建議方塊清單
代理會傳送建議方塊清單和訊息,引導使用者採取後續動作。只有在相關訊息位於對話底部時,才會顯示方塊清單。對話中的任何後續訊息 (無論來自使用者或代理) 都會覆寫方塊清單。
方塊清單最多可包含 11 個建議方塊,每個方塊標籤最多可有 25 個字元。
如需格式和值選項,請參閱 AgentContentMessage。
複合式資訊卡
複合式資訊卡會將媒體、文字和互動式建議整合至單一訊息中。這類資訊卡適合用來呈現相關資訊 (例如產品圖片、名稱和價格),並透過「查看詳細資料」等建議,引導使用者採取明確的後續步驟。
複合式資訊卡可包含下列內容:
這些欄位皆為選填,但複合式資訊卡必須包含欄位 1 至 3 的其中一項。
多張資訊卡可以透過橫向捲動的輪轉介面一起傳送。
請注意,複合式資訊卡的總酬載為 250 KB。
如需完整的技術詳細資料,請參閱複合式資訊卡說明文件。
資訊卡高度
複合式資訊卡會垂直展開,以配合內容。高度下限為 112 DP,上限為 344 DP。如果資訊卡內容不足以填滿資訊卡高度下限,資訊卡會展開,並以空白填滿額外高度。
複合式資訊卡中的媒體必須符合下列三種高度之一:
- Shorts:112 dp
- 中:168 DP
- 高:264 DP
如果媒體不符合資訊卡在所選高度下的尺寸,系統會縮放及裁剪媒體,選擇媒體預覽畫面。
範例
下列程式碼會傳送含有圖片和建議回覆的複合式資訊卡。如需格式和值選項,請參閱 RichCard。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
複合式資訊卡輪轉介面
輪轉介面會將多個複合式資訊卡串連在一起,讓使用者比較項目並個別回應。
輪轉介面最少可包含兩張、最多十張複合式資訊卡。輪轉介面中的複合式資訊卡必須符合複合式資訊卡說明文件所述的一般複合式資訊卡內容和高度規定。如要進一步瞭解輪轉介面版面配置和規格,請參閱輪轉介面說明文件。
範例
下列程式碼會傳送複合式資訊卡輪轉介面。如需格式和值選項,請參閱 RichCard。
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "carouselCard": { "cardWidth": "MEDIUM", "cardContents": [ { "title": "Card #1", "description": "The description for card #1", "suggestions": [ { "reply": { "text": "Card #1", "postbackData": "card_1" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg", "forceRefresh": false } } }, { "title": "Card #2", "description": "The description for card #2", "suggestions": [ { "reply": { "text": "Card #2", "postbackData": "card_2" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg", "forceRefresh": false } } } ] } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Images for the carousel cards let card1Image = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; // Define the card contents for a carousel with two cards, each with one suggested reply let cardContents = [ { title: 'Card #1', description: 'The description for card #1', suggestions: [ { reply: { text: 'Card #1', postbackData: 'card_1', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card1Image, forceRefresh: false, }, }, }, { title: 'Card #2', description: 'The description for card #2', suggestions: [ { reply: { text: 'Card #2', postbackData: 'card_2', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card2Image, forceRefresh: false, }, }, }, ]; // Definition of carousel card let params = { msisdn: '+12223334444', cardContents: cardContents, }; // Send the device the carousel card defined above rbmApiHelper.sendCarouselCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.CardWidth; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); List cardContents = new ArrayList(); // Images for the carousel cards String card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; // Create suggestions for first carousel card List card1Suggestions = new ArrayList(); card1Suggestions.add( new SuggestionHelper("Card #1", "card_1")); cardContents.add( new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, card1Suggestions) .getCardContent(MediaHeight.SHORT) ); // Images for the carousel cards String card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Create suggestions for second carousel card List card2Suggestions = new ArrayList(); card2Suggestions.add( new SuggestionHelper("Card #2", "card_2")); cardContents.add( new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, card2Suggestions) .getCardContent(MediaHeight.SHORT) ); // Send the carousel to the user rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Images for the carousel cards card_image_1 = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; # Suggested replies to be used in the cards suggestions1 = [ messages.SuggestedReply('Card #1', 'reply:card_1') ] suggestions2 = [ messages.SuggestedReply('Card #2', 'reply:card_2') ] # Define the card contents for a carousel with two cards, # each with one suggested reply card_contents = [] card_contents.append(messages.CardContent('Card #1', 'The description for card #1', card_image_1, 'MEDIUM', suggestions1)) card_contents.append(messages.CardContent('Card #2', 'The description for card #2', card_image_2, 'MEDIUM', suggestions2)) # Send the device the carousel card defined above carousel_card = messages.CarouselCard('MEDIUM', card_contents) cluster = messages.MessageCluster().append_message(carousel_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Image references to be used in the carousel cards string card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Suggestion chip lists to be used in carousel cards List<Suggestion> suggestions1 = new List<Suggestion> { new SuggestionHelper("Card #1", "card_1").SuggestedReply() }; List<Suggestion> suggestions2 = new List<Suggestion> { new SuggestionHelper("Card #2", "card_2").SuggestedReply() }; // Create the card content for the carousel List<CardContent> cardContents = new List<CardContent> { // Add items as card content new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, suggestions1).GetCardContent(), new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, suggestions2).GetCardContent() }; // Send the carousel to the user rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);