事件

事件是代理程式可以傳送及接收的通知。事件類型分為三種：

伺服器產生的事件

RBM 平台會傳送事件，通知代理程式伺服器層級的更新，例如訊息到期。

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

代理啟用狀態已變更

RBM 平台會在代理程式的發布狀態每次變更時，傳送 AgentLaunchEvent。舉例來說，如果代理商的狀態在電信業者核准後從 PENDING 變更為 LAUNCHED，您會收到 AgentLaunchEvent 事件，指出這項變更。系統會針對所有 RBM 代理程式，以及所有電信業者啟動狀態變更，傳送這些事件。

Webhook 設定

你可以使用合作夥伴層級或服務專員層級的 Webhook 接收這些通知。

必要條件

事件酬載結構

AgentLaunchEvent 會以 Pub/Sub 訊息的形式傳送。範例如下：

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

事件酬載中的 AgentLaunchEvent.LaunchState 欄位會指出代理程式的新啟動狀態。可能的值包括：

值 代理程式啟動狀態 詳細資料
UNLAUNCHED 未發布 可編輯。
PENDING 待處理 要求已送交電信業者審查。
LAUNCHED 已推出 允許在特定電信業者上傳送訊息。
REJECTED 遭特定貨運公司拒絕 註解中會說明拒絕原因。
SUSPENDED 在特定貨運公司遭停權 註解中會說明停權原因。

資料欄位包含以 Base64 編碼的 JSON 物件，內含啟動狀態詳細資料。以下是解碼後的 JSON 範例：

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

下表列出代理程式啟動狀態和觸發動作：

舊的發布狀態 新的發布狀態 觸發變更
PENDING LAUNCHED 待服務專員核准。
PENDING REJECTED 已拒絕待處理的代理人。
LAUNCHED SUSPENDED 已暫停發布的代理程式。
SUSPENDED LAUNCHED 已重新啟用遭停權的代理人。
SUSPENDED TERMINATED 已終止暫停的代理程式。
TERMINATED LAUNCHED 已啟動終止的服務專員。

訊息已過期；撤銷成功

訊息已過期，並已成功撤銷。這個事件很適合做為備用訊息策略的觸發條件。

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

訊息已過期；撤銷失敗

訊息已過期，但未遭撤銷。

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

我們無法保證訊息一定會送達。

  • 如果訊息已送達，Webhook 會收到 DELIVERED 事件。
  • 如果郵件未送達，請使用撤銷 API 傳送撤銷要求。

如果訊息具有時效性 (例如一次性密碼或詐欺警示)，即使會導致使用者收到重複訊息，最好還是透過簡訊等其他管道傳送。

使用者產生的事件

與使用者訊息和功能檢查一樣，代理程式會以 JSON 格式接收使用者事件。

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

使用者收到服務專員訊息

這個事件表示郵件已傳送。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

使用者閱讀服務專員訊息

這項事件表示郵件已開啟或確認。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

使用者開始輸入文字

這項事件表示使用者正在輸入內容。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

使用者傳送簡訊

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

使用者傳送檔案

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

使用者輕觸建議回覆

使用者輕觸建議回覆時，代理程式會收到含有回覆的後送資料和文字的事件。

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

使用者輕觸建議的動作

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

使用者取消訂閱對話

如果使用者不想再收到商家發送的非必要訊息 (例如促銷活動)，可以在 Google 訊息中取消訂閱 RBM 對話。

UNSUBSCRIBE 事件表示使用者已取消訂閱與服務專員和商家 (服務專員代表的商家) 的對話。以下是 JSON 酬載的範例：

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

運作方式

  • 你隨時可以透過對話選單取消訂閱。如果是宣傳和多用途的智慧助理，在一定數量的未讀訊息後，這個選項也會直接顯示在對話中 (具體規則因國家/地區而異)。

  • 選取「取消訂閱」會同時觸發兩項動作：Google 訊息會將特定國家/地區的關鍵字 (例如「STOP」) 傳送給服務專員，而 RBM 平台則會將 UNSUBSCRIBE 事件傳送至網路鉤子。

    關鍵字取決於使用者電話號碼的國家/地區代碼 (由兩個字母組成)。下表列出各支援國家/地區的關鍵字。

    國家/地區 (國家/地區代碼) 取消訂閱關鍵字
    美國 (US)、印度 (IN)、英國 (GB)、德國 (DE) 停止
    西班牙 (ES)、墨西哥 (MX) BAJA
    法國 (FR) 停止
    巴西 (BR) parar

  • 使用者取消訂閱後，對話仍會保留在收件匣中，除非檢舉為垃圾訊息，否則不會移至「已封鎖的垃圾訊息」資料夾。

  • 為找出違反政策和業務規則的行為，Google 會在使用者取消訂閱後監控訊息模式。

業務規則

  • 身為管理這項對話的 RBM 合作夥伴，您有責任遵守使用者的取消訂閱要求。
  • 如果無法在訊息串中取消訂閱，請立即傳送確認訊息，並附上網站或應用程式的直接連結，方便使用者管理訂閱偏好設定。
  • 使用者取消訂閱後，您不得再傳送非必要訊息。
  • 仍可傳送重要訊息。包括：
    • 驗證資訊，例如動態密碼 (OTP)
    • 使用者要求並同意接收的特定服務通知
    • 確認使用者取消訂閱的要求，並提供相關資訊，方便他們進一步管理通訊偏好設定

範例

如果使用者取消訂閱用途為多用途的航空公司代理程式，您必須停止傳送行銷訊息。不過，如果使用者明確同意接收特定航班的最新動態，您就可以傳送航班最新動態。

取消訂閱原因

使用者取消訂閱服務專員時，可以從下列選項中選取原因：

  • 我並未訂閱
  • 訊息過多
  • 沒興趣了
  • 垃圾內容
  • 其他

目前我們不會將取消訂閱原因提供給合作夥伴或電信業者。

使用者重新訂閱對話

使用者可以在 Google 訊息中重新訂閱先前取消訂閱的對話。

SUBSCRIBE 事件表示使用者想接收來自代理程式的訊息，包括促銷活動等非必要內容。以下是 JSON 酬載範例：

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

運作方式

  • 使用者可以透過對話選單和對話內連結，使用「訂閱」選項重新訂閱已取消訂閱的對話。

  • 選取「訂閱」會同時觸發兩項動作：Google 訊息會將國家/地區專屬的關鍵字 (例如「開始」) 傳送給代理程式，而 RBM 平台會將 SUBSCRIBE 事件傳送至網路鉤子。

    具體關鍵字取決於使用者電話號碼的國家/地區代碼 (由兩個字母組成)。下表列出各支援國家/地區的關鍵字。

    國家/地區 (國家/地區代碼) 訂閱關鍵字
    美國 (US)、印度 (IN)、英國 (GB)、德國 (DE) 開始
    西班牙 (ES)、墨西哥 (MX) ALTA
    法國 (FR) Démarrer
    巴西 (BR) começar

業務規則

  • 身為管理這項對話的 RBM 合作夥伴，您有責任遵守使用者的重新訂閱要求。
  • 重新訂閱適用於所有類型的訊息，包括宣傳等非必要內容。
  • 如果使用者取消訂閱後傳送訊息給商家，系統可能會將此視為重新訂閱要求。
  • 如果使用者在訊息管道以外的地方重新訂閱 (例如在您的網站上)，RBM 合作夥伴有責任更新使用者的狀態，並據此繼續傳送訊息。

代理程式產生的事件

服務專員會傳送事件來模擬人類互動，並向使用者保證服務專員正在處理他們的訊息。使用者會在對話中收到事件通知。

如需格式和值選項，請參閱 phones.agentEvents。

服務專員傳送 READ 事件

使用者會看到這項事件，瞭解特定訊息的已讀回執。讓使用者知道 RBM 平台已傳送訊息，且代理程式正在處理。

下列程式碼會針對含有相符 messageId 的訊息傳送 READ 事件。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_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 "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 這段程式碼摘錄自 RBM 範例服務專員。

Java

import com.google.rbm.RbmApiHelper;
…

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

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 這段程式碼摘錄自 RBM 範例服務專員。

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 這段程式碼摘錄自 RBM 範例服務專員。

C#

using RCSBusinessMessaging;
…

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

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 這段程式碼摘錄自 RBM 範例服務專員。

代理程式會傳送 IS_TYPING 事件

使用者會看到輸入指標，得知代理程式正在撰寫訊息。打字指標會在短時間 (約 20 秒) 後失效，或在使用者裝置收到客服專員的新訊息時失效。您的代理程式可以傳送多個 IS_TYPING 事件，重設輸入指標的到期計時器。

下列程式碼會傳送 IS_TYPING 事件。

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_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 "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 這段程式碼摘錄自 RBM 範例服務專員。

Java

import com.google.rbm.RbmApiHelper;
…

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

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 這段程式碼摘錄自 RBM 範例服務專員。

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 這段程式碼摘錄自 RBM 範例服務專員。

C#

using RCSBusinessMessaging;
…

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

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 這段程式碼摘錄自 RBM 範例服務專員。
上一頁
接收郵件
下一頁
功能檢查