WhatsApp API Checklist: What to Prepare Before You Connect Your Number
What to have ready before connecting the WhatsApp API: verified business portfolio, approved display name, valid payment method and a clean number.
In this article
The most common WhatsApp API support ticket we see is not a technical error. It is a channel that connected without a hitch, shows as active, and sends absolutely nothing. The cause is almost always something that should have been prepared before the number was connected: an unverified Meta business portfolio, a display name that was never approved, a card that failed, or a number with a history. This WhatsApp API checklist is the list of things to have ready before you connect your number, drawn from real support cases rather than from Meta's documentation alone.
Every item on it is boring and fixable. The catch is that most are invisible until a message fails, and some (like a locked portfolio) take days to resolve while customers wait. Items one to three stop messages from going out at all; the rest determine how far you can scale and how safe the number is.
The checklist at a glance
- A verified Meta business portfolio, or access to an existing verified one.
- A display name that matches the brand and has been approved.
- A valid payment method attached to the WhatsApp Business account.
- A number with no previous bans and no active registration you cannot release.
- Two-step verification (2FA) PIN known and stored safely.
- A decision on connection mode: coexistence, migration or a new number.
- A person with admin access to the portfolio who is available on connection day.
- A first set of templates drafted, ready to submit for approval.
Below, why each one matters and what goes wrong when it is missing.
Item 1: the verified business portfolio
This is the item behind the "sends nothing" ticket. When you create the WhatsApp channel inside a brand-new Meta business portfolio that has not been through business verification, Meta may lock the account from minute one. The channel looks connected, the number shows up, and every outbound message fails with error 131031 (business account locked). Nothing you change in the platform fixes it; the fix is on Meta's side.
Two ways to avoid it: verify the portfolio before creating the channel (verification asks for legal documents matching the company name and address; start it days in advance), or reuse a portfolio that is already verified, for example the one your company runs Facebook or Instagram ads from. Do not create a fresh portfolio "to keep things clean". Clean and unverified is exactly what gets locked.
Item 2: the display name
The display name is what customers see instead of a raw number. Meta reviews it against its naming rules: it must match your brand or legal name, must not be generic ("Sales", "Support"), and must not imply an affiliation you do not have.
While the display name is not approved, the number stays at the lowest messaging tier: 250 business-initiated conversations per 24 hours. For a shop sending confirmations that may be fine for a while; for a clinic sending reminders to a few hundred patients a day, it is a hard ceiling from day one. Submit a name consistent with your website and legal documents, and submit it early.
Item 3: the payment method
The WhatsApp Business account needs a valid payment method for Meta to bill conversations. Two failure modes: no card attached, and messages fail with 141006 (payment method issue); or a card that failed (expired, declined), and Meta locks the account, so you see 131031 on every send until billing is settled. Use a company card, and make sure whoever receives the billing emails reads them.
Item 4: a clean number
The API needs a number that can receive an SMS or voice call for verification, is not registered on another WhatsApp Business account you cannot access, and has no ban history. Avoid a number permanently banned on the app (it cannot be registered while the ban stands), a number whose 2FA PIN nobody remembers, and a number owned by a rep rather than the company; the reasons are in why the WhatsApp number belongs to the company, not the rep.
Item 5: two-step verification
WhatsApp numbers can have a six-digit two-step verification PIN, and the API requires it when registering. If the number was set up years ago by someone who left and the PIN is unknown, registration stalls until the PIN is reset, which involves waiting periods. Find or reset it before connection day, and store it where the company, not one person, can find it.
Item 6: coexistence, migration or a new number
Decide this before you start, because the steps differ.
| Option | Keep the app on the phone? | History imported? | Best for |
|---|---|---|---|
| Coexistence | Yes, the same number works in the app and the API | Up to 6 months of chats and contacts during pairing | Businesses that want to try the API without giving up the app |
| Migration | No, the number leaves the app | No automatic import; export from the app first | Teams ready to work fully from the platform, including WhatsApp calls |
| New number | Not applicable | Starts empty | Companies that want a dedicated line from day one |
One detail that matters: with WhatsApp coexistence, WhatsApp voice calls are not handled inside the platform; calls need a number that is 100 % on the API. If calling matters, plan for migration or a new number.
Symptom, cause, fix
When something does go wrong, this is how the most common symptoms map to causes.
| Symptom | Likely cause | Fix |
|---|---|---|
| Channel connected, every message fails with 131031 | Unverified portfolio, failed payment or policy lock | Verify or settle billing in Meta Business Manager |
| Messages fail with 141006 | No valid payment method | Add a company card to the WhatsApp Business account |
| Messages fail with 141010 | Business not verified | Finish business verification |
| Stuck at 250 conversations per day | Display name not approved | Submit a compliant display name |
| Registration asks for a PIN nobody knows | Two-step verification set long ago | Reset the PIN and wait the required period |
| Messages fail with 190 | Access token expired or revoked | Reconnect the channel for a fresh token |
| Template send fails with 131009 | Parameters do not match the approved body | Fix the variable count or format |
Codes such as 131031 arrive in the delivery status webhook, not in the send response, which is why a message can show as sent and then flip to failed. Definitions are in WhatsApp API error codes 131031, 131047 and 130429 explained.
Items 7 and 8: the person and the templates
Connection day needs someone with admin rights on the Meta portfolio, holding the phone if the number is in the app, with time to complete the flow. Half the delays we see are "the person with access is on holiday". Templates are the other thing to prepare: any message outside the 24-hour window needs one, and approval takes time. Draft the three or four you need first and submit them the day the channel goes live. A first utility template for a clinic:
Hello {{1}}, your appointment with Dr. {{2}} is confirmed for {{3}} at {{4}}.
Reply CHANGE if you need a different time.
Frequently asked questions
Why does my WhatsApp API channel show as connected but send nothing?
Most often because the Meta business portfolio is unverified or has a billing problem, which locks the account and returns error 131031 on every send. The fix is in Meta Business Manager, not in the platform.
Do I need business verification to use the WhatsApp API?
For normal sending and to move beyond the lowest messaging tier, yes in practice. A brand-new, unverified portfolio may be locked from the start, so verify before you create the channel.
What is the messaging tier and why am I stuck at 250?
The tier is how many business-initiated conversations you can open per 24 hours: 250, then 1,000, 10,000, 100,000 and unlimited. Tiers grow with volume and quality; an unapproved display name keeps you at 250.
Can I use a number that was previously banned?
A number under a permanent ban cannot be registered on the API while the ban stands. Use a company-owned number with no ban history, and register it with 2FA set by the company.
Prepare first, connect once
Almost every failed WhatsApp API launch traces back to one of these items. Verify the portfolio, get the display name approved, attach a company card, secure the PIN, decide between coexistence and migration, and draft the templates. Then the connection takes minutes. Omnifox walks you through the flow and shows channel health (quality, phone status, messaging tier) once you are live. Start a 7-day free trial and run through this list before you connect.
Ready to try it in your business?
Bring WhatsApp, Instagram, Messenger, email and calls into one inbox, and let AI handle the first reply. Set it up today.
7 days free. No credit card required.
Read more
-

Automated Replies on Your Facebook Page: A Practical Guide
-
After-Hours Coverage Across Four US Time Zones
-

How to Use Instagram Direct to Sell More
-

The Best Business Messaging Platforms in 2026
-

Website Chat for Universities and Colleges: Admissions That Answer in Minutes
-
Business Text Messaging in Canada: The Complete Guide
-
Customer Messaging Software: A Buyer's Guide for US SMBs
-

How to Connect n8n with Your Omnichannel Platform Step by Step
Comments (0)
No comments yet. Be the first to share your thoughts.
Leave a comment
Your email is never published. Comments are moderated before appearing.