--- title: 9.1 WhatsApp Phone Numbers description: Manages the WhatsApp Cloud API phone numbers connected to your tenant. These numbers are used for sending and receiving messages, running campaigns, and… url: "https://peikly.com/docs/peikly-whatsapp-setup/" updated: "2026-10-18" category: WhatsApp tags: - Manual sync --- # 9.1 WhatsApp Phone Numbers ## What This Feature Does Manages the WhatsApp Cloud API phone numbers connected to your tenant. These numbers are used for sending and receiving messages, running campaigns, and syncing templates. ## Prerequisites - CompanyAdmin role. - Meta Platform connected. - Phone numbers verified in Meta/WhatsApp Manager. ## View Phone Numbers 1. In the sidebar, click **WhatsApp** → **Phone Numbers**. 2. The list shows all configured numbers with status, quality rating, and messaging limits. 3. Under **2-step PIN**, click the masked value to reveal the 2-step verification PIN Meta holds for this number on demand — it is never shown by default. ## Health Indicators (Ban-Prevention) The **Health** column protects each number from Meta ever flagging or banning it for sending too aggressively: | Indicator | Meaning | | --- | --- | | Quality: Green | Meta rates this number's recent message quality as good — normal sending. | | Quality: Yellow | Quality is degrading — marketing sends are automatically subject to a tighter frequency cap per contact. | | Quality: Red | Quality is poor — Application automatically **blocks marketing-category sends** on this number until Meta's rating recovers, to prevent a ban. | | Quality: Unknown | Meta has not reported a rating yet (new or rarely-used number). | | Tier: `TIER_xxx` | Meta's messaging-limit tier for this number — the ceiling on unique conversations per rolling 24 hours. | | **Protected** badge | Marketing sends are currently being throttled or paused automatically because the quality rating dropped, specifically to protect this number from a ban. | | **Warming up** badge | The number was connected within the last 14 days and is still on Meta's warm-up ramp — its daily send cap increases gradually instead of jumping straight to the full tier limit. | Application computes each number's actual daily send cap as the smaller of three limits: your configured **Daily Outbound Send Limit**, Meta's messaging tier, and the warm-up ramp (if still warming up) — whichever is currently the tightest is what's actually enforced. ## Numbers Also Used in the WhatsApp Business App A number you connected by keeping your WhatsApp Business app shows **WhatsApp Business app + Peikly** with a status dot. Its **Business Profile** button is switched off (edit the profile in the app), **Delete** reads **Stop using in Peikly**, and a **Details** button shows import results and the **What changes in your app** reminder. See [9.9](/docs/connect-the-number-you-already-use-in-the-whatsapp-business-app/). ## Sync Phone Numbers from Meta 1. Click the **Sync from Meta** button. 2. Application queries the Meta Graph API and updates the list. **Messages:** - `Synced {count} phone number(s) from Meta.` — success. - `Phone numbers are already up to date.` — no changes found. - `Unable to sync phone numbers from Meta.` — Meta API error; retry after a moment. ## Edit a Phone Number 1. Click **Edit** on the phone number row. 2. Update **Display Name**, **Daily Outbound Send Limit**, and **Active** status. 3. Click **Save**. ## Manage a Number's Business Profile If your plan includes the feature and the `whatsapp_business_management` Meta permission is granted, each row shows a **Business Profile** button (person-card icon) next to **Statistics**. Click it to manage that specific number's about text, description, address, email, websites, industry, profile picture, and display name — see [9.5 WhatsApp Business Profile](/docs/whatsapp-business-profile/) for the full workflow. The button is hidden entirely when the feature or permission isn't available, rather than shown disabled. ## Test a Phone Number 1. Click **Test** on the phone number row. 2. Application sends a test API call to verify the phone is reachable. **Messages:** - `Meta reports that '{phone}' is not CONNECTED and cannot send WhatsApp messages.` — check Meta Business Manager for issues with this number. ## Delete a Phone Number For a number that is also in your WhatsApp Business app the button reads **Stop using in Peikly**. It removes the number from Peikly only; your app keeps working. See [9.9](/docs/connect-the-number-you-already-use-in-the-whatsapp-business-app/). 1. Click **Delete** on the phone number row. 2. Confirm in the popup. 3. The number is soft-deleted. Associated quotas and templates are also soft-deleted. ## Errors, Messages, and Common Fixes | Message | Why It Happens | How to Fix | | --- | --- | --- | | `WABA, display name, and phone number are required.` | Required fields missing on add form | Fill all required fields | | `Unable to add phone to WABA.` | Meta API rejected the add request | Check WABA credentials in Meta Manager | | `Meta reports that '{phone}' is not CONNECTED` | Phone disconnected in Meta | Check phone status in WhatsApp Manager | | Marketing broadcasts pause or fail with a quality-protection reason | Quality rating is Red (or Yellow with the tighter cap exceeded) | Wait for the rating to recover; avoid sending to inactive or unengaged contacts in the meantime | | Daily send volume is lower than expected on a new number | Number is still on the warm-up ramp (**Warming up** badge) | This is expected and temporary — the cap increases automatically over the first ~2 weeks | ## Best Practices - Set a realistic **Daily Outbound Send Limit** aligned with your subscription plan to avoid hitting Meta's messaging tier limits. - Keep numbers **Active** only when you actively use them to avoid confusion. - Sync from Meta periodically to pick up any changes made in WhatsApp Manager. - Don't fight the **Protected** or **Warming up** states by adding more numbers or forcing sends — they exist specifically to keep the number from being banned, and resolve on their own. - Watch the Health column after any campaign — a drop to Yellow/Red usually means the last send list included too many unengaged or invalid contacts. ## External Dependencies - **WhatsApp Manager:** [https://business.facebook.com/wa/manage/phone-numbers/](https://business.facebook.com/wa/manage/phone-numbers/) — add, verify, and manage phone numbers. - **Meta Cloud API Docs:** [https://developers.facebook.com/docs/whatsapp/cloud-api](https://developers.facebook.com/docs/whatsapp/cloud-api) — reference for API limits and status codes.