How to subscribe to account update web-hooks?

Helpdesk Updated by Helpdesk

Businesses can integrate with webhooks to get real-time notifications about changes to a WhatsApp Business Account (WABA), including when a business has violated a WhatsApp policy. This guide teaches you how to set up your webhooks to receive those notifications so businesses can quickly adjust behaviour to avoid additional warnings and/or enforcement actions.

Before You Start

To complete this guide you need to register as a Meta Developer. Once you are registered, you need to set up a Business Manager account and a Meta for Developers App.

When creating your Meta app, make sure you select the "Business" type and link your new app with the Business Manager.

Once you have created the app, add WhatsApp as a product to your application. To do that:

  • Go to developers.facebook.com/apps and click the app. After the click, you will be redirected to the app dashboard for your app.
  • On the dashboard, find Products on the left side panel and click Add Product. After the click, you will see a list of products that can be added to an app. 
  • Find WhatsApp and click Set Up.

Additionally, make sure your app has completed App Review and requested the whatsapp_business_management permission.

Step 1: Set up Endpoint and Configure Web-hooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your Web-hooks.

Step 2: Subscribe Your App to your WABA

You need to subscribe your app to Web-hook notifications for the WhatsApp Business Account. You can subscribe in two different ways:

Step 3: Signup for Account Updates

Now that your app has signed up to receive webhooks related to your WABA, you can refine which types of updates you want to receive. To track a WABA’s status, you need to select the account_update option. This way, you will be notified when a WABA has violated WhatsApp policies.

To select this option, go to your App Dashboard and find the Settings option. You will see a Webhooks section with all the information you provided in the previous steps. Find Webhook fields, and click Manage. A dialog box will appear with all the fields you can subscribe to. Click Subscribe for account_update.

Now, every time your WABA has violated a policy, you will get a notification looking like this:

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

Step 4: Track WABA restrictions.

You should keep an eye on your webhooks to check if your WABA has been restricted due to policy violations. If a restriction has been imposed, you get a webhook that includes the restriction_info field, inside the value object. The restriction_info field lists all restrictions imposed on your account and when those restrictions expire.

Your WABA may receive one or more restrictions due to policy violations. In the following example, the webhook reports that a WABA has been restricted from adding new phone numbers:

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

Here, you see a WABA that is no longer allowed to send business-initiated messages:

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

Finally, you see a WABA that is no longer allowed to respond to user-initiated messages:

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

How did we do?

How to appeal to facebook if Business actually follows WhatsApp Commerce policies?

Contact