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:
Muhsin Keloth
2025-10-02 11:25:48 +05:30
committed by GitHub
parent 109aaa2341
commit 66cfef9298
15 changed files with 914 additions and 40 deletions

View File

@@ -0,0 +1,14 @@
/* global axios */
import ApiClient from './ApiClient';
class InboxHealthAPI extends ApiClient {
constructor() {
super('inboxes', { accountScoped: true });
}
getHealthStatus(inboxId) {
return axios.get(`${this.url}/${inboxId}/health`);
}
}
export default new InboxHealthAPI();

View File

@@ -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 isnt 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",

View File

@@ -13,6 +13,7 @@ import DuplicateInboxBanner from './channels/instagram/DuplicateInboxBanner.vue'
import MicrosoftReauthorize from './channels/microsoft/Reauthorize.vue';
import GoogleReauthorize from './channels/google/Reauthorize.vue';
import WhatsappReauthorize from './channels/whatsapp/Reauthorize.vue';
import InboxHealthAPI from 'dashboard/api/inboxHealth';
import PreChatFormSettings from './PreChatForm/Settings.vue';
import WeeklyAvailability from './components/WeeklyAvailability.vue';
import GreetingsEditor from 'shared/components/GreetingsEditor.vue';
@@ -21,6 +22,7 @@ import CustomerSatisfactionPage from './settingsPage/CustomerSatisfactionPage.vu
import CollaboratorsPage from './settingsPage/CollaboratorsPage.vue';
import WidgetBuilder from './WidgetBuilder.vue';
import BotConfiguration from './components/BotConfiguration.vue';
import AccountHealth from './components/AccountHealth.vue';
import { FEATURE_FLAGS } from '../../../../featureFlags';
import SenderNameExamplePreview from './components/SenderNameExamplePreview.vue';
import NextButton from 'dashboard/components-next/button/Button.vue';
@@ -51,6 +53,7 @@ export default {
DuplicateInboxBanner,
Editor,
Avatar,
AccountHealth,
},
mixins: [inboxMixin],
setup() {
@@ -79,6 +82,9 @@ export default {
selectedPortalSlug: '',
showBusinessNameInput: false,
welcomeTaglineEditorMenuOptions: WIDGET_BUILDER_EDITOR_MENU_OPTIONS,
healthData: null,
isLoadingHealth: false,
healthError: null,
};
},
computed: {
@@ -175,6 +181,16 @@ export default {
},
];
}
if (this.shouldShowWhatsAppConfiguration) {
visibleToAllChannelTabs = [
...visibleToAllChannelTabs,
{
key: 'whatsappHealth',
name: this.$t('INBOX_MGMT.TABS.ACCOUNT_HEALTH'),
},
];
}
return visibleToAllChannelTabs;
},
currentInboxId() {
@@ -260,14 +276,30 @@ export default {
this.inbox.reauthorization_required
);
},
isEmbeddedSignupWhatsApp() {
return this.inbox.provider_config?.source === 'embedded_signup';
},
whatsappUnauthorized() {
return (
this.isAWhatsAppChannel &&
this.inbox.provider === 'whatsapp_cloud' &&
this.inbox.provider_config?.source === 'embedded_signup' &&
this.isAWhatsAppCloudChannel &&
this.isEmbeddedSignupWhatsApp &&
this.inbox.reauthorization_required
);
},
whatsappRegistrationIncomplete() {
if (
!this.healthData ||
!this.isAWhatsAppCloudChannel ||
!this.isEmbeddedSignupWhatsApp
) {
return false;
}
return (
this.healthData.platform_type === 'NOT_APPLICABLE' ||
this.healthData.throughput?.level === 'NOT_APPLICABLE'
);
},
},
watch: {
$route(to) {
@@ -275,15 +307,40 @@ export default {
this.fetchInboxSettings();
}
},
inbox: {
handler() {
this.fetchHealthData();
},
immediate: false,
},
},
mounted() {
this.fetchInboxSettings();
this.fetchPortals();
this.fetchHealthData();
},
methods: {
fetchPortals() {
this.$store.dispatch('portals/index');
},
async fetchHealthData() {
if (!this.inbox) return;
if (!this.isAWhatsAppCloudChannel) {
return;
}
try {
this.isLoadingHealth = true;
this.healthError = null;
const response = await InboxHealthAPI.getHealthStatus(this.inbox.id);
this.healthData = response.data;
} catch (error) {
this.healthError = error.message || 'Failed to fetch health data';
} finally {
this.isLoadingHealth = false;
}
},
handleFeatureFlag(e) {
this.selectedFeatureFlags = this.toggleInput(
this.selectedFeatureFlags,
@@ -446,7 +503,11 @@ export default {
<FacebookReauthorize v-if="facebookUnauthorized" :inbox="inbox" />
<GoogleReauthorize v-if="googleUnauthorized" :inbox="inbox" />
<InstagramReauthorize v-if="instagramUnauthorized" :inbox="inbox" />
<WhatsappReauthorize v-if="whatsappUnauthorized" :inbox="inbox" />
<WhatsappReauthorize
v-if="whatsappUnauthorized"
:whatsapp-registration-incomplete="whatsappRegistrationIncomplete"
:inbox="inbox"
/>
<DuplicateInboxBanner
v-if="hasDuplicateInstagramInbox"
:content="$t('INBOX_MGMT.ADD.INSTAGRAM.DUPLICATE_INBOX_BANNER')"
@@ -458,7 +519,7 @@ export default {
:sub-title="$t('INBOX_MGMT.SETTINGS_POPUP.INBOX_UPDATE_SUB_TEXT')"
:show-border="false"
>
<div class="flex flex-col mb-4 items-start gap-1">
<div class="flex flex-col gap-1 items-start mb-4">
<label class="mb-0.5 text-sm font-medium text-n-slate-12">
{{ $t('INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_AVATAR.LABEL') }}
</label>
@@ -856,6 +917,9 @@ export default {
<div v-if="selectedTabKey === 'botConfiguration'">
<BotConfiguration :inbox="inbox" />
</div>
<div v-if="selectedTabKey === 'whatsappHealth'">
<AccountHealth :health-data="healthData" />
</div>
</section>
</div>
</template>

View File

@@ -16,6 +16,10 @@ const props = defineProps({
type: Object,
required: true,
},
whatsappRegistrationIncomplete: {
type: Boolean,
default: false,
},
});
const { t } = useI18n();
@@ -28,6 +32,20 @@ const whatsappConfigurationId = computed(
() => window.chatwootConfig.whatsappConfigurationId
);
const actionLabel = computed(() => {
if (props.whatsappRegistrationIncomplete) {
return t('INBOX_MGMT.COMPLETE_REGISTRATION');
}
return '';
});
const description = computed(() => {
if (props.whatsappRegistrationIncomplete) {
return t('INBOX_MGMT.WHATSAPP_REGISTRATION_INCOMPLETE');
}
return '';
});
const reauthorizeWhatsApp = async params => {
isRequestingAuthorization.value = true;
@@ -185,6 +203,8 @@ defineExpose({
<InboxReconnectionRequired
class="mx-8 mt-5"
:is-loading="isRequestingAuthorization"
:action-label="actionLabel"
:description="description"
@reauthorize="requestAuthorization"
/>
</template>

View File

@@ -0,0 +1,228 @@
<script setup>
import { computed } from 'vue';
import { useI18n } from 'vue-i18n';
import ButtonV4 from 'next/button/Button.vue';
import Icon from 'dashboard/components-next/icon/Icon.vue';
const props = defineProps({
healthData: {
type: Object,
default: null,
},
});
const { t } = useI18n();
const QUALITY_COLORS = {
GREEN: 'text-n-teal-11',
YELLOW: 'text-n-amber-11',
RED: 'text-n-ruby-11',
UNKNOWN: 'text-n-slate-12',
};
const STATUS_COLORS = {
APPROVED: 'text-n-teal-11',
PENDING_REVIEW: 'text-n-amber-11',
AVAILABLE_WITHOUT_REVIEW: 'text-n-teal-11',
REJECTED: 'text-n-ruby-9',
DECLINED: 'text-n-ruby-9',
};
const MODE_COLORS = {
LIVE: 'text-n-teal-11',
SANDBOX: 'text-n-slate-11',
};
const healthItems = computed(() => {
if (!props.healthData) {
return [];
}
const {
display_phone_number: displayPhoneNumber,
verified_name: verifiedName,
name_status: nameStatus,
quality_rating: qualityRating,
messaging_limit_tier: messagingLimitTier,
account_mode: accountMode,
} = props.healthData;
return [
{
key: 'displayPhoneNumber',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.DISPLAY_PHONE_NUMBER.LABEL'),
value: displayPhoneNumber || 'N/A',
tooltip: t(
'INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.DISPLAY_PHONE_NUMBER.TOOLTIP'
),
show: true,
},
{
key: 'verifiedName',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.VERIFIED_NAME.LABEL'),
value: verifiedName || 'N/A',
tooltip: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.VERIFIED_NAME.TOOLTIP'),
show: true,
},
{
key: 'displayNameStatus',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.DISPLAY_NAME_STATUS.LABEL'),
value: nameStatus || 'UNKNOWN',
tooltip: t(
'INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.DISPLAY_NAME_STATUS.TOOLTIP'
),
show: true,
type: 'status',
},
{
key: 'qualityRating',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.QUALITY_RATING.LABEL'),
value: qualityRating || 'UNKNOWN',
tooltip: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.QUALITY_RATING.TOOLTIP'),
show: true,
type: 'quality',
},
{
key: 'messagingLimitTier',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.MESSAGING_LIMIT_TIER.LABEL'),
value: messagingLimitTier || 'UNKNOWN',
tooltip: t(
'INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.MESSAGING_LIMIT_TIER.TOOLTIP'
),
show: true,
type: 'tier',
},
{
key: 'accountMode',
label: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.ACCOUNT_MODE.LABEL'),
value: accountMode || 'UNKNOWN',
tooltip: t('INBOX_MGMT.ACCOUNT_HEALTH.FIELDS.ACCOUNT_MODE.TOOLTIP'),
show: true,
type: 'mode',
},
];
});
const handleGoToSettings = () => {
const { business_id: businessId } = props.healthData || {};
if (businessId) {
// WhatsApp Business Manager URL with specific business ID and phone numbers tab
const whatsappBusinessUrl = `https://business.facebook.com/latest/whatsapp_manager/phone_numbers/?business_id=${businessId}&tab=phone-numbers`;
window.open(whatsappBusinessUrl, '_blank');
} else {
// Fallback to general WhatsApp Business Manager if business_id is not available
const fallbackUrl = 'https://business.facebook.com/';
window.open(fallbackUrl, '_blank');
}
};
const getQualityRatingTextColor = rating =>
QUALITY_COLORS[rating] || QUALITY_COLORS.UNKNOWN;
const formatTierDisplay = tier =>
t(`INBOX_MGMT.ACCOUNT_HEALTH.VALUES.TIERS.${tier}`) || tier;
const formatStatusDisplay = status =>
t(`INBOX_MGMT.ACCOUNT_HEALTH.VALUES.STATUSES.${status}`) || status;
const formatModeDisplay = mode =>
t(`INBOX_MGMT.ACCOUNT_HEALTH.VALUES.MODES.${mode}`) || mode;
const getModeStatusTextColor = mode => MODE_COLORS[mode] || 'text-n-slate-12';
const getStatusTextColor = status => STATUS_COLORS[status] || 'text-n-slate-12';
</script>
<template>
<div class="gap-4 pt-8 mx-8">
<div
class="px-5 py-5 space-y-6 rounded-xl border shadow-sm border-n-weak bg-n-solid-2"
>
<div
class="flex flex-col gap-5 justify-between items-start w-full md:flex-row"
>
<div>
<span class="text-base font-medium text-n-slate-12">
{{ t('INBOX_MGMT.ACCOUNT_HEALTH.TITLE') }}
</span>
<p class="mt-1 text-sm text-n-slate-11">
{{ t('INBOX_MGMT.ACCOUNT_HEALTH.DESCRIPTION') }}
</p>
</div>
<ButtonV4
sm
solid
blue
class="flex-shrink-0"
@click="handleGoToSettings"
>
{{ t('INBOX_MGMT.ACCOUNT_HEALTH.GO_TO_SETTINGS') }}
</ButtonV4>
</div>
<div v-if="healthData" class="grid grid-cols-1 gap-4 xs:grid-cols-2">
<div
v-for="item in healthItems"
:key="item.key"
class="flex flex-col gap-2 p-4 rounded-lg border border-n-weak bg-n-solid-1"
>
<div class="flex gap-2 items-center">
<span class="text-sm font-medium text-n-slate-11">
{{ item.label }}
</span>
<Icon
v-tooltip.top="item.tooltip"
icon="i-lucide-info"
class="flex-shrink-0 w-4 h-4 cursor-help text-n-slate-9"
/>
</div>
<div class="flex items-center">
<span
v-if="item.type === 'quality'"
class="inline-flex items-center px-2 py-0.5 min-h-6 text-xs font-medium rounded-md bg-n-alpha-2"
:class="getQualityRatingTextColor(item.value)"
>
{{ item.value }}
</span>
<span
v-else-if="item.type === 'status'"
class="inline-flex items-center px-2 py-0.5 min-h-6 text-xs font-medium rounded-md bg-n-alpha-2"
:class="getStatusTextColor(item.value)"
>
{{ formatStatusDisplay(item.value) }}
</span>
<span
v-else-if="item.type === 'mode'"
class="inline-flex items-center px-2 py-0.5 min-h-6 text-xs font-medium rounded-md bg-n-alpha-2"
:class="getModeStatusTextColor(item.value)"
>
{{ formatModeDisplay(item.value) }}
</span>
<span
v-else-if="item.type === 'tier'"
class="text-sm font-medium text-n-slate-12"
>
{{ formatTierDisplay(item.value) }}
</span>
<span v-else class="text-sm font-medium text-n-slate-12">{{
item.value
}}</span>
</div>
</div>
</div>
<div v-else class="pt-8">
<div
class="flex justify-center items-center p-8 text-center text-n-slate-11"
>
<div>
<Icon icon="i-lucide-activity" class="mb-2 w-8 h-8" />
<p class="text-sm">{{ t('INBOX_MGMT.ACCOUNT_HEALTH.NO_DATA') }}</p>
</div>
</div>
</div>
</div>
</div>
</template>

View File

@@ -1,15 +1,26 @@
<script setup>
import Banner from 'dashboard/components-next/banner/Banner.vue';
defineProps({
actionLabel: {
type: String,
default: null,
},
description: {
type: String,
default: null,
},
});
const emit = defineEmits(['reauthorize']);
</script>
<template>
<Banner
color="ruby"
:action-label="$t('INBOX_MGMT.CLICK_TO_RECONNECT')"
:action-label="actionLabel || $t('INBOX_MGMT.CLICK_TO_RECONNECT')"
@action="emit('reauthorize')"
>
{{ $t('INBOX_MGMT.RECONNECTION_REQUIRED') }}
{{ description || $t('INBOX_MGMT.RECONNECTION_REQUIRED') }}
</Banner>
</template>