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>
85 lines
2.3 KiB
Ruby
85 lines
2.3 KiB
Ruby
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
|