接收事件

代理會收到 RBM 平台傳送的 Webhook 事件,通知你使用者互動和平台層級更新。

這些事件會依來源分類:

  • 使用者事件:從使用者裝置傳送至服務專員的通知,表示與服務專員互動。
  • 平台事件:RBM 平台傳送的通知,說明代理啟動狀態變更和訊息到期。

如要進一步瞭解代理傳送至使用者裝置的狀態事件,請參閱「傳送事件」。

如要進一步瞭解如何處理使用者訊息 (例如文字、檔案、位置等),請參閱「接收訊息」。

使用者事件

使用者事件是來自使用者裝置的通知,用於回報訊息狀態或訂閱項目變更 (例如使用者在 Google 訊息中取消訂閱或重新訂閱)。

如需完整的格式和值選項,請參閱 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",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

使用者取消訂閱對話

這個事件表示使用者已取消訂閱,不再接收代理和所代表商家傳送的非必要訊息,例如促銷活動。使用者在 Google 訊息中取消訂閱 RBM 對話時,就會觸發這個事件。

以下是 JSON 酬載範例:

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

取消訂閱的運作方式

  • 即時通訊選單中一律會顯示「取消訂閱」選項。如果是宣傳和多用途代理,當未讀訊息累積一定數量後,這個選項也會直接顯示在即時通訊中 (具體規則因國家/地區而異)。
  • 選取「取消訂閱」會同時觸發兩項動作:Google 訊息會傳送國家/地區專屬關鍵字 (例如「STOP」) 給服務專員,而 RBM 平台會傳送 UNSUBSCRIBE 事件給 Webhook。

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

    國家/地區 (國家/地區代碼) 取消訂閱關鍵字
    美國 (US)、印度 (IN)、英國 (GB)、德國 (DE)、荷蘭 (NL) 停止
    西班牙 (ES)、墨西哥 (MX) BAJA
    法國 (FR) STOP
    巴西 (BR) parar
  • 使用者取消訂閱後,對話仍會保留在收件匣中,除非回報為垃圾訊息,才會移至「已封鎖的垃圾訊息」資料夾。

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

業務規則

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

範例

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

取消訂閱原因

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

  • 訊息過多
  • 我從未訂閱這則訊息
  • 沒興趣了
  • 這看起來像是詐騙
  • 其他

為減少選擇偏誤,系統會隨機排列前四個選項,使用者每次造訪時,這個順序都會保持一致,而「其他」則固定在底部。

系統會匯總取消訂閱原因,並顯示在「Analytics 總覽」中,協助您瞭解使用者取消訂閱的原因。

使用者重新訂閱對話

這個事件表示使用者想再次接收代理傳送的訊息,包括促銷活動等非必要內容。使用者在 Google 訊息中重新訂閱先前取消訂閱的對話,即可觸發這項事件。

以下是 JSON 酬載範例:

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

重新訂閱的運作方式

  • 「訂閱」選項可透過即時通訊選單和對話內連結存取,使用者可重新訂閱先前取消訂閱的對話。
  • 選取「訂閱」會同時觸發兩項動作:Google 訊息會將國家/地區專屬關鍵字 (例如「START」) 傳送給代理,而 RBM 平台會將 SUBSCRIBE 事件傳送至 Webhook。具體關鍵字取決於使用者電話號碼的雙字母國家/地區代碼。下表列出各個支援國家/地區的關鍵字。

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

業務規則

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

平台事件

RBM 平台會傳送平台事件,通知代理程式啟動狀態變更或訊息到期。

代理啟動狀態已變更

每當代理的推出狀態有所變更,RBM 平台就會傳送 AgentLaunchEvent。例如,當代理的狀態從 PENDING 變更為 LAUNCHED 時。事件會以 Pub/Sub 訊息的形式傳送。如要區分這個事件與其他事件,請檢查 message.attributes.type 路徑的值是否為 agent_launch_event。

Webhook 設定

您可以使用合作夥伴層級或代理層級的 Webhook 接收這些通知。

必要條件

  • 設定 Webhook 以接收 RBM 訊息 (必須完成這項設定,才能接收使用者訊息和使用者事件)。
  • 如要區分使用者事件和代理程式啟動狀態事件,請檢查 message.attributes.type 路徑的值是否為 agent_launch_event。

事件酬載結構

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 欄位會指出代理的新啟動狀態。可能的值如下:

值 代理啟動狀態 詳細資料
PENDING 待處理 要求已送交貨運公司審查。
LAUNCHED 已推出 允許在特定電信業者網路上傳送訊息。
REJECTED 遭特定電信業者拒絕 拒絕原因會註明在留言中。
SUSPENDED 在特定電信業者上遭停權 停權原因會註明在註解中。
UNLAUNCHED 未推出 如果服務專員已從所有電信業者下架,則可編輯。

資料欄位包含以 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 UNLAUNCHED 終止代理。
REJECTED LAUNCHED 核准先前遭拒的推出要求。

合作夥伴啟動的推出狀態變更

以下是允許的轉換,通常由合作夥伴處理:

舊啟動狀態 新推出狀態 觸發動作
UNSPECIFIED PENDING 送交審查。
PENDING UNLAUNCHED 取消待處理的啟動要求。
UNLAUNCHED PENDING 送交審查。
REJECTED PENDING 重新送審。
SUSPENDED PENDING 重新送審。

訊息已過期,撤銷成功

這項事件表示訊息的存留時間 (TTL) 已過,且訊息已成功撤銷。這時適合觸發備用訊息策略。

如需完整的格式和值選項,請參閱 ServerEvent 參考資料。

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

訊息已過期,無法撤銷

這個事件表示訊息的存留時間已過,但未成功撤銷。

如需完整的格式和值選項,請參閱 ServerEvent 參考資料。

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

不保證訊息一定會送達。

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

如果訊息具有時效性 (例如動態密碼或詐欺警示),建議透過簡訊等替代管道傳送訊息,即使這會導致使用者收到重複訊息也沒關係。