WhatsApp Business 管理 API

Webhooks 元件

Webhooks 擁有頂層陣列欄位，用以指明所傳達的內容。陣列由 JSON 物件組成，其中包括與 Webhook 相關的詳細欄位。

WhatsApp Business 管理 API Webhooks 可以包含以下物件：

參數說明

object

此為所訂閱物件。


如果是內嵌註冊，此物件一律為 whatsapp_business_account。

entry

此物件包含觸發 Webhooks 呼叫的變更詳細資訊。

entry 物件

參數說明

id

此 Webhook 所屬的 WhatsApp Business 帳戶編號。

time

entry 物件的時間。

changes

觸發 Webhooks 呼叫的變更，詳見 changes 物件。

changes

參數說明（點擊左欄的箭咀以了解支援的值。）

field

包含您將在此 Webhook 中收到的通知類型。

支援的值

  • account_alerts
  • account_review_update
  • account_update
  • business_capability_update
  • message_template_quality_update
  • message_template_status_update
  • phone_number_name_update
  • phone_number_quality_update
  • security
  • template_category_update

value

包含指定 field 的相關變更細節，詳見 value 物件。

value

參數說明（點擊左欄的箭咀以了解支援的值。）

ban_info

在帳戶被封鎖時加到 Webhooks。此物件包含 2 個屬性：

  • waba_ban_state：選項包括：
    • DISABLE
    • REINSTATE
    • SCHEDULE_FOR_DISABLE
  • waba_ban_date

current_limit

包含此帳戶目前的級別限制。

支援的值

  • TIER_50
  • TIER_250
  • TIER_1K
  • TIER_10K
  • TIER_100K
  • TIER_UNLIMITED

decision

在作出了有關帳戶或電話號碼的決定時使用。

支援的值

  • APPROVED
  • REJECTED

display_phone_number

包括觸發相應通知的商業帳戶顯示電話號碼。

event

在指定 WhatsApp Business 帳戶發生事件時使用。點擊左欄的箭咀以查看所有可用選項。

顯示名稱更新

  • APPROVED：審查已通過。如果商家之前無法下載憑證，現在也應能夠下載憑證以使用顯示名稱。
  • DEFERRED：審查已延遲，商家可下載憑證以使用顯示名稱。
  • REJECTED：審查未能通過，當中附有未能通過的原因。如果商家之前無法下載憑證，便要重新申請顯示名稱審查，這樣才能取得憑證。如果商家已在使用憑證，則即使未能通過顯示名稱審查，也不會影響到該商家的運作。不過，如要提高訊息和帳戶限制，該商家便要通過顯示名稱審查。

訊息範本品質更新

之前的品質分數：


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

新的品質分數：


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

訊息範本狀態更新

  • APPROVED
  • DISABLED
  • IN_APPEAL
  • PENDING
  • REINSTATED
  • REJECTED
  • FLAGGED

電話號碼更新

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

範本類別更新

之前的類別：


  • MARKETING
  • OTP
  • TRANSACTIONAL

新的類別：


  • AUTHENTICATION
  • MARKETING
  • UTILITY

雙重認證驗證碼

  • PIN_CHANGED: 雙重認證驗證碼已更新（僅限雲端 API）
  • PIN_RESET_REQUEST: 要求停用雙重認證驗證碼
  • PIN_RESET_SUCCESS: 雙重認證驗證碼已停用

WhatsApp Business 帳戶更新

  • ACCOUNT_RESTRICTION：用以在 WhatsApp Business 帳戶因違反 WhatsApp Business 平台政策而向其施加限制時，回報此次限制。
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

field=business_capability_update 時，此值一律存在。


表示您可使用 WhatsApp Business 帳戶的每個具獲核准顯示名稱的企業電話號碼所傳送的範本訊息數量。查看收發訊息限制。

max_phone_numbers_per_business

包括一個商家可擁有的電話號碼數量上限。


field=business_capability_update 時，Webhook 將有 max_phone_numbers_per_business 或 max_phone_numbers_per_waba。

max_phone_numbers_per_waba

包括一個 WhatsApp Business 帳戶可擁有的電話號碼數量上限。


field=business_capability_update 時，Webhook 將有 max_phone_numbers_per_business 或 max_phone_numbers_per_waba。

reason

範本被拒原因。可能的值：


  • ABUSIVE_CONTENT：內容被判為屬濫用情況。
  • INCORRECT_CATEGORY：類別被判為有誤。請參閱範本類別。
  • INVALID_FORMAT：內容重複或欠缺範例。
  • NONE：範本獲批時設定的預設值。
  • SCAM：內容被判為屬詐騙情況。

rejection_reason

如果要求遭拒，此欄位會顯示拒絕原因。

requested_verified_name

此欄位顯示傳送以供驗證的名稱。

restriction_info

列舉

在特定 WhatsApp Business 帳戶因違反 WhatsApp Business 平台政策時而被施加限制時，回報有關限制。


此欄位包括限制類型清單及其相應的到期日。可能的限制類型包括：


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION
  • RESTRICTED_BIZ_INITIATED_MESSAGING
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING

到期日以 DateTime 格式提供。

requester

已要求停用或者已停用／已更新雙重認證驗證碼的用戶之編號。

範例

訊息範本狀態更新

獲批准範本

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}

被拒絕範本

{
  "object": "whatsapp_business_account"
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ]
}

已排定停用的範本

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

已暫停範本

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

範本訊息正待刪除

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

範本類別更新

範本類別已變更

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

訊息範本品質更新

範本品質評級已變更

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

電話號碼更新

已收到名稱更新

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243053,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "16505551111",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

已收到品質更新

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶更新

沙箱編號已升級為驗證帳戶

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶已停權

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶違反政策

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶在違反政策後受到限制

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶已停用

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "DISABLED_UPDATE",
            "ban_info": {
              "waba_ban_state": 
               "SCHEDULE_FOR_DISABLE" | 
               "DISABLE" | 
               "REINSTATE",
               "waba_ban_date": TIMESTAMP
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶審查已完成

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶因違反政策而受到限制

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

WhatsApp Business 帳戶已遭刪除

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "ACCOUNT_DELETED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business 帳戶已從合作夥伴移除

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "PARTNER_REMOVED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

商家功能更新

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

帳戶警示

提高收發訊息限制的要求被拒

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

提高收發訊息限制的要求被拒，需要提供更多使用情況

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

提高收發訊息限制的要求被拒，需要提供更多資料

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}