Direct Send Message Callbacks

Meta sends webhook events to the RML callback endpoint for account restriction changes and template status updates triggered by Direct Send activity. Seven webhook payloads are documented below.

Template Paused event

Triggered when Meta pauses an auto-generated Direct Send template due to a policy or quality violation.

Template Paused Event Webhook payload received when an auto-generated template is paused by Meta.

{
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1751247548,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 761478853568170,
            "message_template_name": "auto_generated_ef286867_dca6_4309_9c44_8c52745f04f0",
            "message_template_language": "en_US"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Warning (no restriction)

First-level signal from Meta indicating potential Direct Send utility category abuse. No account restriction is applied at this stage but the warning should prompt immediate content review.

Warning (No Restriction) Webhook payload for abuse warning — no send restriction applied.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1710000000,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "violation_info": {
              "violation_type": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_WARN"
            }
          }
        }
      ]
    }
  ]
}

📘
Note
No restriction applied. Review message content immediately to avoid strike escalation.

7-day restriction (Strike 1)

Account restricted from sending Direct Send utility templates for 7 days. restriction_info.expiration contains the Unix timestamp of the lift.

7-Day Restriction (Strike 1) Webhook payload for first strike — 7-day restriction applied.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1710000000,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "violation_info": {
              "violation_type": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1"
            },
            "restriction_info": {
              "restriction_type": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
              "expiration": 1710604800
            }
          }
        }
      ]
    }
  ]
}

📘
Note
Direct Send utility templates are blocked until expiration timestamp. Parse expiration as Unix epoch to surface lift date to account holders.

30-day restriction (Strike 2)

Account restricted from sending Direct Send utility templates for 30 days. More severe than Strike 1 and requires a compliance review before resuming.

30-Day Restriction (Strike 2) Webhook payload for second strike — 30-day restriction applied.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1710000000,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "violation_info": {
              "violation_type": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_2"
            },
            "restriction_info": {
              "restriction_type": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
              "expiration": 1712592000
            }
          }
        }
      ]
    }
  ]
}

📘
Note
30-day block on Direct Send utility templates. A compliance review with Meta is recommended.

Permanent ban (offboarding)

Account permanently banned from Direct Send capability. No expiration timestamp is included. The account is offboarded from the feature.

Permanent Ban (Offboarding) Webhook payload for permanent ban — no expiration.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1710000000,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "violation_info": {
              "violation_type": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_OFFBOARD"
            },
            "restriction_info": {
              "restriction_type": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES"
            }
          }
        }
      ]
    }
  ]
}

❗️
Important
Permanent ban. No expiration field. Account is fully offboarded from Direct Send. Contact Meta support to appeal.

Unban event

Restriction lifted. Direct Send capability is restored. This event follows a Strike 1, Strike 2, or Offboard event after the restriction expires or is appealed successfully.

Unban Event Webhook payload when a restriction is lifted and Direct Send is restored.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1710000000,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "violation_info": {
              "violation_type": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_UNBAN"
            }
          }
        }
      ]
    }
  ]
}

📘
Info
Direct Send capability restored. Resume normal operations. Audit message content to prevent recurrence.

Template Category Correction

Meta reclassifies an auto-generated template from UTILITY to MARKETING. Templates moved to MARKETING consume marketing-tier messaging credits and fall under 24-hour session window rules.

Template Category Correction Webhook payload when Meta reclassifies an auto-generated template category.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "2061629777463969",
      "time": 1713264000,
      "changes": [
        {
          "field": "template_correct_category_detection",
          "value": {
            "message_template_id": "987654321098765",
            "message_template_name": "order_update_notification",
            "message_template_language": "en_US",
            "category": "UTILITY",
            "correct_category": "MARKETING"
          }
        }
      ]
    }
  ]
}

📘
Note
Category reclassification from UTILITY to MARKETING changes billing tier and applies the 24-hour session window. Update routing logic accordingly.

Callback payload — field reference

Field	Type	Required	Description
object	string	Yes	Always whatsapp_business_account
entry[].id	string	Yes	WhatsApp Business Account ID.
entry[].time	integer	Yes	Unix epoch timestamp of the event.
entry[].changes[].field	string	Yes	Event category: account_update, message_template_status_update, or template_correct_category_detection.
value.event	string	Yes	Event type: PAUSED, ACCOUNT_RESTRICTION, etc.
value.violation_info.violation_type	string	No	Restriction type code. See violation types table above.
value.restriction_info.restriction_type	string	No	Restriction scope: RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES.
value.restriction_info.expiration	integer	No	Unix epoch timestamp when restriction lifts. Absent for permanent bans.
value.correct_category	string	No	New category assigned by Meta during category correction event.