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>
This commit is contained in:
@@ -5,6 +5,8 @@
|
||||
"LEARN_MORE": "Learn more about inboxes",
|
||||
"RECONNECTION_REQUIRED": "Your inbox is disconnected. You won't receive new messages until you reauthorize it.",
|
||||
"CLICK_TO_RECONNECT": "Click here to reconnect.",
|
||||
"WHATSAPP_REGISTRATION_INCOMPLETE": "Your WhatsApp Business registration isn’t complete. Please check your display name status in Meta Business Manager before reconnecting.",
|
||||
"COMPLETE_REGISTRATION": "Complete Registration",
|
||||
"LIST": {
|
||||
"404": "There are no inboxes attached to this account."
|
||||
},
|
||||
@@ -605,8 +607,62 @@
|
||||
"BUSINESS_HOURS": "Business Hours",
|
||||
"WIDGET_BUILDER": "Widget Builder",
|
||||
"BOT_CONFIGURATION": "Bot Configuration",
|
||||
"ACCOUNT_HEALTH": "Account Health",
|
||||
"CSAT": "CSAT"
|
||||
},
|
||||
"ACCOUNT_HEALTH": {
|
||||
"TITLE": "Manage your WhatsApp account",
|
||||
"DESCRIPTION": "Review your WhatsApp account status, messaging limits, and quality. Update settings or resolve issues if needed",
|
||||
"GO_TO_SETTINGS": "Go to Meta Business Manager",
|
||||
"NO_DATA": "Health data is not available",
|
||||
"FIELDS": {
|
||||
"DISPLAY_PHONE_NUMBER": {
|
||||
"LABEL": "Display phone number",
|
||||
"TOOLTIP": "Phone number displayed to customers"
|
||||
},
|
||||
"VERIFIED_NAME": {
|
||||
"LABEL": "Business name",
|
||||
"TOOLTIP": "Business name verified by WhatsApp"
|
||||
},
|
||||
"DISPLAY_NAME_STATUS": {
|
||||
"LABEL": "Display name status",
|
||||
"TOOLTIP": "Status of your business name verification"
|
||||
},
|
||||
"QUALITY_RATING": {
|
||||
"LABEL": "Quality rating",
|
||||
"TOOLTIP": "WhatsApp quality rating for your account"
|
||||
},
|
||||
"MESSAGING_LIMIT_TIER": {
|
||||
"LABEL": "Messaging limit tier",
|
||||
"TOOLTIP": "Daily messaging limit for your account"
|
||||
},
|
||||
"ACCOUNT_MODE": {
|
||||
"LABEL": "Account mode",
|
||||
"TOOLTIP": "Current operating mode of your WhatsApp account"
|
||||
}
|
||||
},
|
||||
"VALUES": {
|
||||
"TIERS": {
|
||||
"TIER_250": "250 customers per 24h",
|
||||
"TIER_1000": "1K customers per 24h",
|
||||
"TIER_1K": "1K customers per 24h",
|
||||
"TIER_10K": "10K customers per 24h",
|
||||
"TIER_100K": "100K customers per 24h",
|
||||
"TIER_UNLIMITED": "Unlimited customers per 24h"
|
||||
},
|
||||
"STATUSES": {
|
||||
"APPROVED": "Approved",
|
||||
"PENDING_REVIEW": "Pending Review",
|
||||
"AVAILABLE_WITHOUT_REVIEW": "Available Without Review",
|
||||
"REJECTED": "Rejected",
|
||||
"DECLINED": "Declined"
|
||||
},
|
||||
"MODES": {
|
||||
"SANDBOX": "Sandbox",
|
||||
"LIVE": "Live"
|
||||
}
|
||||
}
|
||||
},
|
||||
"SETTINGS": "Settings",
|
||||
"FEATURES": {
|
||||
"LABEL": "Features",
|
||||
|
||||
Reference in New Issue
Block a user