代理會收到 RBM 平台傳送的 Webhook 事件,通知你使用者互動和平台層級更新。
這些事件會依來源分類:
如要進一步瞭解代理傳送至使用者裝置的狀態事件,請參閱「傳送事件」。
如要進一步瞭解如何處理使用者訊息 (例如文字、檔案、位置等),請參閱「接收訊息」。
使用者事件
使用者事件是來自使用者裝置的通知,用於回報訊息狀態或訂閱項目變更 (例如使用者在 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 傳送撤銷要求。
如果訊息具有時效性 (例如動態密碼或詐欺警示),建議透過簡訊等替代管道傳送訊息,即使這會導致使用者收到重複訊息也沒關係。