feat: Add WhatsApp health monitoring and self-service registration completion (#12556)

Fixes
https://linear.app/chatwoot/issue/CW-5692/whatsapp-es-numbers-stuck-in-pending-due-to-premature-registration


###  Problem  
Multiple customers reported that their WhatsApp numbers remain stuck in
**Pending** in WhatsApp Manager even after successful onboarding.

- Our system triggers a **registration call**
(`/<PHONE_NUMBER_ID>/register`) as soon as the number is OTP verified.
- In many cases, Meta hasn’t finished **display name
review/provisioning**, so the call fails with:

  ```
  code: 100, error_subcode: 2388001
  error_user_title: "Cannot Create Certificate"
error_user_msg: "Your display name could not be processed. Please edit
your display name and try again."
  ```

- This leaves the number stuck in Pending, no messaging can start until
we manually retry registration.
- Some customers have reported being stuck in this state for **7+
days**.

###  Root cause  
- We only check `code_verification_status = VERIFIED` before attempting
registration.
- We **don’t wait** for display name provisioning (`name_status` /
`platform_type`) to be complete.
- As a result, registration fails prematurely and the number never
transitions out of Pending.

### Solution  

#### 1. Health Status Monitoring  
- Build a backend service to fetch **real-time health data** from Graph
API:
  - `code_verification_status`  
  - `name_status` / `display_name_status`  
  - `platform_type`  
  - `throughput.level`  
  - `messaging_limit_tier`  
  - `quality_rating`  
- Expose health data via API
(`/api/v1/accounts/:account_id/inboxes/:id/health`).
- Display this in the UI as an **Account Health tab** with clear badges
and direct links to WhatsApp Manager.

#### 2. Smarter Registration Logic  
- Update `WebhookSetupService` to include a **dual-condition check**:  
  - Register if:  
    1. Phone is **not verified**, OR  
2. Phone is **verified but provisioning incomplete** (`platform_type =
NOT_APPLICABLE`, `throughput.level = NOT_APPLICABLE`).
- Skip registration if number is already provisioned.  
- Retry registration automatically when stuck.  
- Provide a UI banner with complete registration button so customers can
retry without manual support.

### Screenshot
<img width="2292" height="1344" alt="CleanShot 2025-09-30 at 16 01
03@2x"
src="https://github.com/user-attachments/assets/1c417d2a-b11c-475e-b092-3c5671ee59a7"
/>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>

app/services/whatsapp/embedded_signup_service.rb

@@ -17,6 +17,7 @@ class Whatsapp::EmbeddedSignupService
 
     channel = create_or_reauthorize_channel(access_token, phone_info)
     channel.setup_webhooks
+    check_channel_health_and_prompt_reauth(channel)
     channel
 
   rescue StandardError => e
@@ -52,6 +53,24 @@ class Whatsapp::EmbeddedSignupService
     end
   end
 
+  def check_channel_health_and_prompt_reauth(channel)
+    health_data = Whatsapp::HealthService.new(channel).fetch_health_status
+    return unless health_data
+
+    if channel_in_pending_state?(health_data)
+      channel.prompt_reauthorization!
+    else
+      Rails.logger.info "[WHATSAPP] Channel #{channel.phone_number} health check passed"
+    end
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP] Health check failed for channel #{channel.phone_number}: #{e.message}"
+  end
+
+  def channel_in_pending_state?(health_data)
+    health_data[:platform_type] == 'NOT_APPLICABLE' ||
+      health_data.dig(:throughput, 'level') == 'NOT_APPLICABLE'
+  end
+
   def validate_parameters!
     missing_params = []
     missing_params << 'code' if @code.blank?

app/services/whatsapp/health_service.rb

@@ -0,0 +1,84 @@
+class Whatsapp::HealthService
+  BASE_URI = 'https://graph.facebook.com'.freeze
+
+  def initialize(channel)
+    @channel = channel
+    @access_token = channel.provider_config['api_key']
+    @api_version = GlobalConfigService.load('WHATSAPP_API_VERSION', 'v22.0')
+  end
+
+  def fetch_health_status
+    validate_channel!
+    fetch_phone_health_data
+  end
+
+  private
+
+  def validate_channel!
+    raise ArgumentError, 'Channel is required' if @channel.blank?
+    raise ArgumentError, 'API key is missing' if @access_token.blank?
+    raise ArgumentError, 'Phone number ID is missing' if @channel.provider_config['phone_number_id'].blank?
+  end
+
+  def fetch_phone_health_data
+    phone_number_id = @channel.provider_config['phone_number_id']
+
+    response = HTTParty.get(
+      "#{BASE_URI}/#{@api_version}/#{phone_number_id}",
+      query: {
+        fields: health_fields,
+        access_token: @access_token
+      }
+    )
+
+    handle_response(response)
+  rescue StandardError => e
+    Rails.logger.error "[WHATSAPP HEALTH] Error fetching health data: #{e.message}"
+    raise e
+  end
+
+  def health_fields
+    %w[
+      quality_rating
+      messaging_limit_tier
+      code_verification_status
+      account_mode
+      id
+      display_phone_number
+      name_status
+      verified_name
+      webhook_configuration
+      throughput
+      last_onboarded_time
+      platform_type
+      certificate
+    ].join(',')
+  end
+
+  def handle_response(response)
+    unless response.success?
+      error_message = "WhatsApp API request failed: #{response.code} - #{response.body}"
+      Rails.logger.error "[WHATSAPP HEALTH] #{error_message}"
+      raise error_message
+    end
+
+    data = response.parsed_response
+    format_health_response(data)
+  end
+
+  def format_health_response(response)
+    {
+      display_phone_number: response['display_phone_number'],
+      verified_name: response['verified_name'],
+      name_status: response['name_status'],
+      quality_rating: response['quality_rating'],
+      messaging_limit_tier: response['messaging_limit_tier'],
+      account_mode: response['account_mode'],
+      code_verification_status: response['code_verification_status'],
+      throughput: response['throughput'],
+      last_onboarded_time: response['last_onboarded_time'],
+      platform_type: response['platform_type'],
+      business_id: @channel.provider_config['business_account_id']
+    }
+  end
+end

app/services/whatsapp/webhook_setup_service.rb

@@ -8,8 +8,12 @@ class Whatsapp::WebhookSetupService
 
   def perform
     validate_parameters!
-    # Since coexistence method does not need to register, we check it
-    register_phone_number unless phone_number_verified?
+
+    # Register phone number if either condition is met:
+    # 1. Phone number is not verified (code_verification_status != 'VERIFIED')
+    # 2. Phone number needs registration (pending provisioning state)
+    register_phone_number if !phone_number_verified? || phone_number_needs_registration?
+
     setup_webhook
   end
 
@@ -69,9 +73,44 @@ class Whatsapp::WebhookSetupService
   def phone_number_verified?
     phone_number_id = @channel.provider_config['phone_number_id']
 
-    @api_client.phone_number_verified?(phone_number_id)
+    # Check with WhatsApp API if the phone number code verification is complete
+    # This checks code_verification_status == 'VERIFIED'
+    verified = @api_client.phone_number_verified?(phone_number_id)
+    Rails.logger.info("[WHATSAPP] Phone number #{phone_number_id} code verification status: #{verified}")
+
+    verified
   rescue StandardError => e
-    Rails.logger.error("[WHATSAPP] Phone registration status check failed, but continuing: #{e.message}")
+    # If verification check fails, assume not verified to be safe
+    Rails.logger.error("[WHATSAPP] Phone verification status check failed: #{e.message}")
+    false
+  end
+
+  def phone_number_needs_registration?
+    # Check if phone is in pending provisioning state based on health data
+    # This is a separate check from phone_number_verified? which only checks code verification
+
+    phone_number_in_pending_state?
+
+  rescue StandardError => e
+    Rails.logger.error("[WHATSAPP] Phone registration check failed: #{e.message}")
+    # Conservative approach: don't register if we can't determine the state
+    false
+  end
+
+  def phone_number_in_pending_state?
+    health_service = Whatsapp::HealthService.new(@channel)
+    health_data = health_service.fetch_health_status
+
+    # Check if phone number is in "not provisioned" state based on health indicators
+    # These conditions indicate the number is pending and needs registration:
+    # - platform_type: "NOT_APPLICABLE" means not fully set up
+    # - throughput.level: "NOT_APPLICABLE" means no messaging capacity assigned
+    health_data[:platform_type] == 'NOT_APPLICABLE' ||
+      health_data.dig(:throughput, :level) == 'NOT_APPLICABLE'
+
+  rescue StandardError => e
+    Rails.logger.error("[WHATSAPP] Health status check failed: #{e.message}")
+    # If health check fails, assume registration is not needed to avoid errors
     false
   end
 end