傳送訊息

RBM 代理程式會透過收發訊息與使用者通訊。 如要傳送訊息給使用者，代理程式會將訊息要求傳送至 RCS Business Messaging API。單一要求可包含文字、互動式資訊卡、媒體和 PDF 檔案，以及建議回覆和建議動作。

在特定情況下，RBM 平台會傳回錯誤，協助您管理訊息傳送作業：

• 如果傳送訊息的對象裝置不支援 RCS 或未啟用 RCS，RBM 平台會傳回 404 NOT_FOUND 錯誤。在這種情況下，您可以嘗試透過基礎架構中定義的備用方法與使用者聯絡。
• 如果傳送訊息給 RCS 使用者時，代理程式尚未在該網路推出，或該網路尚未啟用 RCS 流量，RBM 平台會傳回 404 NOT_FOUND 錯誤。
• 如果傳送的訊息包含使用者裝置不支援的功能，RBM 平台會傳回 400 INVALID_ARGUMENT 錯誤，且不會傳送訊息。

建議您在多管道訊息策略中，於合理時間後撤銷訊息，並透過其他管道傳送。如要在預先定義的時間自動撤銷訊息，請設定訊息到期時間。

接收者目前不在線上

如果收件者處於離線狀態，RBM 平台仍會接受訊息並傳送。您會收到 200 OK 回覆，RBM 平台會保留訊息並嘗試重新傳送 30 天。不必要求 RBM 再次傳送訊息。

RBM 會在訊息提交 30 天後刪除所有未傳送的訊息。

視代理程式的使用案例而定，您可能想在 30 天逾時前撤銷未傳送的訊息。撤銷作業可防止離線使用者在連線後收到過時訊息。您可以透過多種方式撤銷訊息：

• 傳送撤銷要求，觸發撤銷程序。
• 設定郵件到期日，系統會在適當時間自動撤銷郵件。

設定郵件到期日

服務專員的訊息是否具有時效性？舉例來說，一次性密碼的有效期限很短。限時優惠到期。預約提醒在預約日期過後就沒有意義。為確保訊息的時效性和相關性，請設定訊息到期時間。這樣一來，離線使用者重新連線時，就不會收到過時的內容。到期時間也是啟動備用訊息策略的好時機，確保使用者及時取得所需資訊。

如要設定訊息到期時間，請在代理程式訊息中指定下列其中一個欄位：

• expireTime：訊息過期的確切時間 (世界標準時間)。
• ttl(存留時間)：訊息到期前的時間長度。

如需格式和值選項，請參閱 AgentMessage。

訊息過期後，RBM 平台會停止嘗試傳送訊息，並自動撤銷訊息。不過，這種做法偶爾會失敗。舉例來說，API 可能會在 RBM 平台傳送訊息的過程中觸發撤銷作業。如要確認過期訊息是否已成功撤銷，RBM 會將通知事件傳送至你的 Webhook。

ttl 和 expireTime 的最大值是訊息提交後 15 天。

雖然沒有最低值 ttl 和 expireTime，但建議在提交訊息後至少等待 10 秒，以大幅降低收到撤銷和傳送通知的機率。

設定訊息流量類型

RBM API 包含 messageTrafficType 欄位，可將訊息分類。雖然服務專員用途仍會定義服務專員行為和適用的業務規則，但 messageTrafficType 可更詳細地分類訊息內容。最終，單一代理程式就能處理多個用途。目前現有的代理程式用途或業務規則不會受到影響。

這個欄位為選填欄位，但建議您現在就設定，以免欄位變成必填時收到錯誤訊息。

如要設定訊息流量類型，請根據每則訊息的內容，指派適當的 messageTrafficType。RBM 支援下列流量類型。

流量類型	訊息內容	代理用途
AUTHENTICATION	驗證訊息。	動態密碼
TRANSACTION	針對使用者現有服務或產品的訊息。例如：確認信、付款收據或預訂詳細資料。	單次或多次使用
PROMOTION	宣傳訊息，例如優惠、折扣、公告或其他宣傳內容。	促銷或多次使用
SERVICEREQUEST	使用者明確要求的服務相關訊息。	動態密碼、交易、宣傳或多用途
ACKNOWLEDGEMENT	用於確認使用者動作的訊息，特別是取消訂閱要求。這表示我們已收到使用者的要求，並正在處理中。	動態密碼、交易、宣傳或多用途

如果未設定流量類型，系統會為代理程式的使用案例指派預設類型。

代理用途	預設流量類型
OTP	AUTHENTICATION
交易	TRANSACTION
宣傳	PROMOTION
多用途	MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

多用途代理程式沒有預設的流量類型。您必須根據每則訊息的內容，為訊息明確設定流量類型。如未替換 MESSAGE_TRAFFIC_TYPE_UNSPECIFIED 值，就會發生錯誤。

郵件大小限制

整個字串化的AgentMessage大小上限為 250 KB。訊息的文字部分有 3072 個字元的長度限制。

透過 RBM 傳送的檔案大小上限為 100 MB。詳情請參閱「媒體和 PDF 檔案」。

重要事項： 美國境內的 RBM 流量：為避免美國境內使用者產生非預期的資料用量，傳送至美國電話號碼的單一 RBM 訊息中，所有媒體和 PDF 附件的總大小不得超過 100 MiB。(1 MiB = 1,048,576 個位元組)。這項限制僅適用於美國電信業者的 RBM 流量。舉例來說，如果服務專員在加拿大和美國等多個國家/地區營運，這項限制只會影響傳送至美國號碼的訊息。

文字

最簡單的訊息是由文字組成。簡訊最適合用來傳達資訊，不需要圖片、複雜的互動或回覆。

範例

下列程式碼會傳送純文字訊息。如需格式和值選項，請參閱 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: '[phone]',
};

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]"
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

基本訊息內容 - 轉換為簡訊

電信業者已推出計費模式，支援將簡訊遷移至 RBM。RBM 訊息最多可包含 160 個 UTF-8 字元，稱為基本訊息。

建構傳送基本訊息的要求時，請注意字元會計為 1 個位元組 (UTF-8)。如果傳送的訊息含有特殊字元 (例如表情符號) 或多位元組字元集，每個字元會計為 2 到 4 個以上的 UTF-8 字元。

在方塊中輸入文字，即可檢查長度：

基本訊息內容和連結預覽畫面

RCS 用戶端可能會實作連結預覽功能。如果純文字 RBM 訊息包含具有 openGraph 標記的網站網址，系統可能會顯示預覽圖片，讓使用者以為內容更豐富。

請注意，RCS 用戶端可能會允許使用者停用連結預覽功能。

用於驗證使用者的一次性密碼

您可以使用 RBM 傳送一次性密碼 (OTP)，透過 SMS Retriever API 自動驗證使用者。目前沒有專用的 API，可讀取透過 RBM 傳送的 OTP。

Android 裝置的運作方式

如果 Android 應用程式已向 SMS Retriever API 註冊，該 API 會監聽格式正確的 RBM 訊息。這則訊息必須包含 OTP 和可識別應用程式的不重複雜湊值。

如果收到的 RBM 訊息格式正確，SMS Retriever API 會像處理簡訊 OTP 一樣處理該訊息。雜湊值與應用程式相符後，系統會擷取一次性密碼並轉送至應用程式，自動驗證使用者身分。

• 使用者驗證的 RBM 簡訊範例：Your code is <OTP> <app hash>.
• 範例：Your code is 123456 M8tue43FGT.

如要進一步瞭解 SMS Retriever 和相關 API，請參閱 SMS Retriever 說明文件。如要進一步瞭解如何使用 SMS Retriever API 註冊應用程式，並自動驗證使用者，請參閱這份流程圖。

iOS 裝置的運作方式

如果是 iOS，系統內建的 OTP 處理功能會自動偵測 RBM OTP，並建議自動填入，就像處理簡訊 OTP 一樣。iOS 應用程式不需要整合特定 API，即可讀取一次性密碼。

媒體和 PDF 檔案

傳送含有圖片、影片、音訊或 PDF 檔案的訊息時，服務專員必須提供可供公眾存取的內容網址，或直接上傳檔案。如果是媒體檔案，你也可以指定縮圖，讓使用者在點選前預覽內容。如果是音訊檔案，系統會使用預設音訊小工具做為預留位置。

重要事項： 為保護使用者隱私權和安全，RBM 平台會先從提供的網址下載並處理媒體和 PDF 檔案，再傳送給使用者。這樣可避免系統透過不重複的網址追蹤代理商。因此，請勿提交大量不重複的網址。無論網址指向相同或不同的檔案，RBM 平台都不支援這類網址。對相同檔案使用相同的網址。

RBM 平台會將檔案快取 60 天，而 API 會傳回檔案 ID，代理程式可將該 ID 納入傳送給使用者的訊息中。60 天後，RBM 會從快取中移除檔案。

如要透過網址指定檔案，最佳做法是將 contentMessage.forceRefresh 設為 false。設定 contentMessage.forceRefresh 為 true 會強制 RBM 從指定網址擷取新內容，即使網址內容已快取也一樣，這會增加使用者的訊息傳送時間。

如需檔案大小建議和限制的最佳做法，請參閱這篇文章。

檔案網址範例

下列程式碼會傳送圖片。如需格式和值選項，請參閱 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: '[phone]',
};

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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, "[phone]");

這段程式碼是 RBM 範例服務專員的摘錄內容。

你也可以先上傳媒體，然後再透過訊息傳送，方法是輕觸 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 JSON


curl -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 JSON


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": {
    "uploadedRbmFile": {
      "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME",
      "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME"
    }
  }
}'

支援的媒體類型

RBM 支援下列媒體類型。縮圖僅支援 image/jpeg、image/jpg、image/gif 和 image/png。

媒體類型	文件類型	擴充功能	支援複合式資訊卡
application/ogg	OGG 音訊	.ogx	否
應用程式/pdf	PDF	.pdf	否
audio/aac	AAC 音訊	.aac	否
audio/mp3	MP3 音訊	.mp3	否
音訊/mpeg	MPEG 音訊	.mpeg	否
音訊/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	是

建議

智慧助理會在建議晶片清單 (最多 11 項建議) 或豐富資訊卡 (最多 4 項建議) 中傳送建議 (建議回覆和建議動作)。

每個建議最多可包含 25 個字元。

建議的回覆

建議的回覆會提供代理程式知道如何回應的內容，引導使用者進行對話。

使用者輕觸建議回覆時，代理程式會收到包含回覆文字和回傳資料的事件。酬載長度上限為 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
    "[phone]",
   suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

建議採取的動作

建議動作會運用裝置的內建功能，引導使用者進行對話。你的代理程式可以建議使用者撥打電話號碼、在地圖上開啟位置、分享位置、開啟網址或建立日曆活動。

您可以選擇為每個建議動作提供備用網址 (最多 2048 個字元)。如果使用者的裝置不支援建議動作，系統會在新瀏覽器視窗中開啟這個網址。

使用者輕觸建議動作時，代理程式會收到包含動作回傳資料的事件。

如需格式和值選項，請參閱 SuggestedAction。

撥號

「撥號」動作會引導使用者撥打代理程式指定的電話號碼。 電話號碼只能包含數字 (0-9)、加號 (+)、星號 (*) 和井號 (#)。系統支援 E.164 國際格式 (例如 [phone])，但並非必要。也就是說，[phone] 和 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": "[phone]"
          }
        }
      }
    ]
  }
}'

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: '[phone]'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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("[phone]");

   // 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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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', '[phone]')
]

# 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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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 = "[phone]"
};

// 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!",
    "[phone]",
    suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

查看地點

「查看位置」動作會在使用者預設的地圖應用程式中顯示位置。您可以透過經緯度指定位置，也可以根據使用者目前的位置提出查詢。你也可以為地圖應用程式中顯示的圖釘設定自訂標籤。

範例

下列程式碼會傳送查看位置資訊動作。如需格式和值選項，請參閱 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
    "[phone]",
    suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

分享位置資訊

使用者可以透過「分享位置資訊」動作，將位置資訊提供給代理程式。使用者可以分享目前位置，也可以從 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
    "[phone]",
    suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

開啟網址

「開啟網址」動作可將使用者導向至代理程式指定的網頁。 根據預設，網頁會在使用者瀏覽器中開啟。如果使用者已為網頁設定預設應用程式，系統會改為開啟該應用程式。在這種情況下，建議動作按鈕上的圖示會是應用程式圖示。

「開啟網址」動作也支援整合式 WebView，詳情請參閱「使用 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"
          }
        }
      }
    ]
  }
}'

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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
    "[phone]",
    suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

使用 WebView 開啟網址

「透過網頁檢視開啟網址」動作會使用預設瀏覽器的算繪引擎，在訊息應用程式中載入指定的網頁。這樣一來，使用者就能與網頁互動，不必離開 RBM 對話。如果使用者的裝置不支援 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!",
      "[phone]",
      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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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!",
    "[phone]",
    suggestions
);

這段程式碼是 RBM 範例服務專員的摘錄內容。

建議方塊清單

服務專員會在訊息中傳送建議選項清單，引導使用者後續採取行動。只有在相關訊息位於對話底部時，才會顯示動態消息清單。對話中的任何後續訊息 (來自使用者或代理程式) 都會覆寫晶片清單。

清單中的方塊是建議回覆和建議動作。

晶片清單最多可包含 11 個建議晶片，每個晶片標籤最多可有 25 個字元。

如需格式和值選項，請參閱 AgentContentMessage。

複合式資訊卡

如要傳送大量相關資訊、媒體或建議，請傳送複合式資訊卡。代理程式可透過豐富資訊卡，在單一訊息中傳送多個資訊單元。

豐富資訊卡可包含下列項目：

• 圖片或影片
• 標題文字
• 說明文字
• 建議回覆和建議動作 (最多 4 個)

豐富資訊卡可包含所有列出的項目，但資訊卡必須至少包含圖片、影片或標題，才算有效。豐富卡片最多可包含四個建議動作和建議回覆。

代理程式可以在複合式資訊卡輪播中，一次傳送多張複合式資訊卡。

動態卡片酬載的大小上限為 250 KB。如需媒體檔案大小建議和限制的最佳做法，請參閱這篇文章。

如要查看複合式資訊卡規格，請參閱「複合式資訊卡」。

資訊卡高度

資訊卡會垂直展開，配合內容調整尺寸。動態卡片的高度下限為 112 DP，上限為 344 DP。如果資訊卡的內容不足以填滿最低高度，資訊卡會展開，並以空白字元填滿額外高度。

互動式資訊卡中的媒體必須符合下列三種高度之一：

• 短：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: '[phone]',
   suggestions: suggestions,
   imageUrl: imageUrl,
   height: 'TALL',
};

// Send rich card to device
rbmApiHelper.sendRichCard(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

這段程式碼是 RBM 範例服務專員的摘錄內容。

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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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, "[phone]");

這段程式碼是 RBM 範例服務專員的摘錄內容。

複合式資訊卡輪轉介面

如要向使用者顯示多個選項供選擇，請使用複合式資訊卡輪播。輪轉介面會將多張豐富資訊卡串連在一起，讓使用者比較項目並個別回應。

輪播內容至少要有兩張，最多十張。輪轉介面中的複合式資訊卡必須符合一般複合式資訊卡的內容和高度規定。如要查看輪轉介面規格，請參閱「豐富資訊卡」。

輪播式豐富資訊卡酬載的大小上限為 250 KB。如需媒體檔案大小建議和限制的最佳做法，請參閱這篇文章。

截斷

與動態資訊卡類似，許多因素 (例如螢幕解析度、像素密度和使用者偏好設定) 都會影響資訊卡向使用者顯示的方式。不過，在輪播中，前幾張資訊卡的高度會決定輪播中所有資訊卡的高度，而資訊卡高度會影響標題、說明和建議的截斷。

如果裝置因顯示限制或資訊卡高度而無法顯示資訊卡的所有元素，RBM 會截斷資訊卡，直到裝置可以顯示為止，並採用下列邏輯：

1. 將說明縮減為一行。
2. 將標題縮減為一行。
3. 從定義清單的結尾開始，省略不適合顯示在資訊卡中的建議。
4. 省略說明。
5. 省略標題。

為避免遭到截斷，請盡可能縮短標題和說明。如果是直向媒體，請使用標題和說明，或其中一項建議。中型媒體最多可使用兩項建議。如果是短片，最多可使用三項建議。 如要顯示四個建議，請勿在資訊卡中加入媒體。

請確保資訊卡內容的大小和長度大致相同，並視需要將較大的資訊卡放在輪播介面的最前面，避免後續的資訊卡遭到截斷。

範例

以下程式碼會傳送複合式資訊卡輪轉介面。如需格式和值選項，請參閱 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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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/kitchen-sink-sample-images/cute-dog.jpg';
let card2Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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: '[phone]',
   cardContents: cardContents,
};

// Send the device the carousel card defined above
rbmApiHelper.sendCarouselCard(params, function(response) {
   console.log(response);
});

這段程式碼是 RBM 範例服務專員的摘錄內容。

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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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, "[phone]");
        } catch(Exception e) {
            e.printStackTrace();
        }

這段程式碼是 RBM 範例服務專員的摘錄內容。

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/kitchen-sink-sample-images/cute-dog.jpg';
card_image_2 = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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('[phone]')

這段程式碼是 RBM 範例服務專員的摘錄內容。

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/kitchen-sink-sample-images/cute-dog.jpg";
string card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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);

這段程式碼是 RBM 範例服務專員的摘錄內容。