Messaging Health Status

Overview

Messaging health status indicates whether a phone number can currently send WhatsApp messages. Dualhook displays this as one of four states:

• AVAILABLE — normal operations
• LIMITED — degraded quality, reduced capacity
• BLOCKED — messaging suspended
• UNKNOWN — health data not yet retrieved

Dualhook pulls health from Meta Graph API and stores history snapshots for monitoring dashboards.

In coexistence / Embedded Signup setups, not every raw LIMITED response means quality or policy trouble. If the only Meta notice is the display-name approval notice and display-name statuses are name_status = NON_EXISTS plus new_name_status = PENDING_REVIEW, Dualhook treats that as a separate expected coexistence state in customer-facing UI while preserving Meta's raw LIMITED status in diagnostics.

The connection Debug tab exposes the raw Meta diagnostics behind these signals, with inline guidance for common expected patterns such as coexistence display-name gating and webhook-routing checks.

Graph API Health Check

Query the phone-number node with health-related fields:

curl -X GET "https://graph.facebook.com/<GRAPH_VERSION>/<PHONE_NUMBER_ID>?fields=health_status,quality_rating,account_mode,whatsapp_business_manager_messaging_limit" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

AVAILABLE Response

{
  "id": "123456789012345",
  "health_status": {
    "can_send_message": "AVAILABLE",
    "entities": []
  },
  "quality_rating": "GREEN",
  "account_mode": "LIVE",
  "whatsapp_business_manager_messaging_limit": "TIER_10K"
}

LIMITED Response

{
  "id": "123456789012345",
  "health_status": {
    "can_send_message": "LIMITED",
    "entities": [
      {
        "entity_type": "PHONE_NUMBER",
        "id": "123456789012345",
        "can_send_message": "LIMITED",
        "additional_info": [
          "Recent quality degradation detected."
        ],
        "errors": [
          {
            "error_code": 131056,
            "error_description": "Rate limit reached for current quality tier.",
            "possible_solution": "Improve quality and reduce promotional send volume."
          }
        ]
      }
    ]
  },
  "quality_rating": "YELLOW",
  "account_mode": "LIVE",
  "whatsapp_business_manager_messaging_limit": "TIER_2K"
}

BLOCKED Response

{
  "id": "123456789012345",
  "health_status": {
    "can_send_message": "BLOCKED",
    "entities": [
      {
        "entity_type": "PHONE_NUMBER",
        "id": "123456789012345",
        "can_send_message": "BLOCKED",
        "additional_info": [
          "Messaging blocked due to policy enforcement."
        ]
      }
    ]
  },
  "quality_rating": "RED",
  "account_mode": "LIVE",
  "whatsapp_business_manager_messaging_limit": "TIER_250"
}

Health Status States

The table above describes Meta's raw health states. Your product UI may still want a friendlier derived state for known expected patterns such as coexistence display-name gating.

Tier Field Notes

Request the current portfolio-level limit field:

• whatsapp_business_manager_messaging_limit — shared business-portfolio messaging limit

Dualhook uses this field for new health checks. For background on the portfolio-level shift, see Capacity, Quality & Messaging Limits.

Health Webhook Events

Health changes are also reflected via management webhook events. See Webhook Events for the full event list.

phone_number_quality_update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "event": "QUALITY_UPDATED",
            "phone_number_id": "123456789012345",
            "display_phone_number": "15550001234",
            "current_limit": "TIER_2K",
            "current_quality_rating": "YELLOW",
            "previous_quality_rating": "GREEN"
          }
        }
      ]
    }
  ]
}

account_update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "VERIFIED_ACCOUNT",
            "ban_info": {
              "waba_ban_state": "NONE"
            }
          }
        }
      ]
    }
  ]
}

Recommended Ops Flow

1. Run periodic health checks against Meta Graph API.
2. Process health-related webhook events in real time.
3. Alert on LIMITED and BLOCKED states.
4. Review quality trends, tier movement, and alert causes before scaling campaigns.

Dualhook surfaces health snapshots and quality-change events in the monitoring dashboard. For a complete quality management strategy, see Maintain Account Health.