登入開始免費試用
Meta Tech Provider

WhatsApp user_preferences Webhook:客戶停止或恢復行銷訊息時

user_preferences Webhook 會告知企業,WhatsApp 用戶透過「優惠及公告」設定停止或恢復接收其行銷訊息。每個事件包含類別 marketing_messages、值 stop 或 resume、一句詳情描述、用戶的 wa_id 與 BSUID,以及 Unix 時間戳。同一設定中的「感興趣」與「不感興趣」回饋不會觸發此 Webhook。

easyCoexistence 透過 Coexistence 將你的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,讓你的 AI 與自動化功能可在你保留於應用程式中的號碼上運作。

2

偏好設定可取的值:stop 與 resume,兩者均屬 marketing_messages 類別。

131050

向已停止接收貴企業行銷訊息的用戶發送行銷訊息範本時,失敗狀態所用的代碼。

Default callback

Meta 發送 user_preferences 的途徑:WhatsApp Business Account 或號碼無法覆寫此欄位。

whatsapp_business_management

應用程式接收 messages 與 calls 以外的 Webhook 所需權限,當中包括 user_preferences。

什麼會觸發 user_preferences Webhook?

客戶在 WhatsApp 開啟「優惠及公告」,並選擇停止接收(或日後恢復接收)貴企業的行銷訊息時,會觸發 user_preferences Webhook。只有這兩項操作會觸發。同一設定亦讓客戶標記「感興趣」或「不感興趣」,此回饋不會發送任何 Webhook;然而,「不感興趣」可能會降低你與該客戶之間每位用戶的行銷訊息上限,並會彈出第二個畫面,提供完全停止行銷訊息的選項。只有其後客戶點選停止,user_preferences 才會被觸發。

負載包含哪些內容?

負載在欄位名稱 user_preferences 下,包含一個 user_preferences 陣列,並與 contacts 陣列並列。此處的時間戳為整數,而狀態 Webhook 則以字串發送。若客戶使用用戶名稱且未能分享電話號碼,則省略 wa_id;若貴企業未啟用企業範圍用戶 ID,則省略 user_id;除非已啟用父 BSUID,否則省略 parent_user_id。以下是 Meta 恢復接收的示例:

Meta's example: a customer resumes marketing messages
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824"
              }
            ],
            "user_preferences": [
              {
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824",
                "detail": "User requested to resume marketing messages",
                "category": "marketing_messages",
                "value": "resume",
                "timestamp": 1731705721
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

收到停止後,你的系統應如何處理?

將此項記錄於該客戶名下,並在收到恢復事件之前,將其排除於所有行銷訊息發送之外。detail 欄位可能顯示「User requested to stop marketing messages」或「User requested to resume marketing messages」,但程式碼應讀取 value。

  • 以 BSUID 及電話號碼儲存此偏好設定,因為某次事件中兩者任一均可能缺失。
  • 將該客戶排除於行銷訊息範本發送之外,反正 Meta 亦會以 131050 拒絕發送。
  • 僅按客戶個別套用:Meta 從不在父 BSUID 層級套用偏好設定。
  • 恢復接收時,解除排除,並按 Meta 的同意加入政策要求,保留你自己的同意加入紀錄。

若 user_preferences 從未送達你的伺服器,該怎麼辦?

即使 Webhook 缺失,Meta 仍會執行停止,所以你損失的只是一次發送失敗,而非違反政策。當你向已停止接收的用戶發送行銷訊息範本時,API 會接受請求,但不會發送訊息,並觸發狀態 Webhook,其 status 為 failed、code 為 131050,標題為「Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business」。請將此失敗視同停止事件處理:記錄下來,並抑制之後對該客戶的行銷訊息發送。

透過 easyCoexistence 連接的號碼,這項機制如何運作?

user_preferences 不屬於 Meta 允許覆寫發送目的地的欄位,因此 Meta 只會將其送往訂閱該帳戶的應用程式預設回調。對於透過 easyCoexistence 連接的號碼,該應用程式為 easyCoexistence 所有,而它目前並未訂閱 user_preferences,因此此事件不會送達直接目的地或 Forward URL。131050 失敗狀態則會送達,因為它經由 messages 欄位傳送。

若你的 AI 使用 send_template 發送行銷訊息範本,請在你自己的系統中保留停止名單並先行核對:easyCoexistence 並不保存此名單。

常見錯誤

  • 將「不感興趣」當作停止。它不會發送 Webhook,亦不會停止發送,但可能會降低該客戶的每位用戶行銷訊息上限。
  • 只以 wa_id 作為偏好設定的索引鍵。對於使用用戶名稱且無法分享號碼的客戶,此欄位會被省略;請同時儲存 BSUID。
  • 將停止套用至父 BSUID 下的所有人。Meta 按用戶個別套用偏好設定,從不在父層級套用。
  • 收到 131050 後重試,而非將其記錄為停止。每次重試都會以相同方式失敗。
使用 EasyCoexistence 完成這項設定

透過它發送的行銷訊息範本,會經由你自己的 WhatsApp Business Account 發出;而用於回報已停止接收用戶的失敗狀態,則會直接或以已簽署轉發的方式送達你的伺服器。每個已連接號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,並設有 3 天免費試用。

常見問題

停止接收是否也會阻止回覆客戶自己發出的訊息?

Meta 的文件將停止描述為涵蓋行銷訊息,而其回傳的錯誤亦指明行銷訊息。回覆主動發訊息給你的客戶,屬服務訊息,是另一個類別。

封鎖企業是否會觸發 user_preferences?

不會。Webhook 只會在「優惠及公告」設定中的停止與恢復時觸發。封鎖是獨立操作,不會在此欄位中回報。

恢復接收是否等同於同意加入?

這表示客戶選擇再次接收你的行銷訊息。根據 Meta 政策,你自身的同意加入責任依然適用,因此請保留該客戶何時、以何種方式同意接收你的訊息的紀錄。

我應訂閱哪個 Webhook 欄位?

請在應用程式控制台的 WhatsApp > 設定中,於訂閱 WhatsApp Business Account 的應用程式上訂閱 user_preferences。它與 messages 為獨立欄位,並需要 whatsapp_business_management 權限。

繼續閱讀

準備開始嗎?

幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用

驗證日期