- What This Feature Does
- Prerequisites
- View Phone Numbers
- Health Indicators (Ban-Prevention)
- Numbers Also Used in the WhatsApp Business App
- Sync Phone Numbers from Meta
- Edit a Phone Number
- Manage a Number's Business Profile
- Test a Phone Number
- Delete a Phone Number
- Errors, Messages, and Common Fixes
- Best Practices
- External Dependencies
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 #
- In the sidebar, click WhatsApp → Phone Numbers.
- The list shows all configured numbers with status, quality rating, and messaging limits.
- 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.
Sync Phone Numbers from Meta #
- Click the Sync from Meta button.
- 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 #
- Click Edit on the phone number row.
- Update Display Name, Daily Outbound Send Limit, and Active status.
- 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 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 #
- Click Test on the phone number row.
- 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.
- Click Delete on the phone number row.
- Confirm in the popup.
- 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/ — add, verify, and manage phone numbers.
- Meta Cloud API Docs: https://developers.facebook.com/docs/whatsapp/cloud-api — reference for API limits and status codes.
