WhatsApp Business API #

Connect your business to WhatsApp through the official WhatsApp Business API. This channel is the recommended choice for businesses that need reliable, high-volume WhatsApp messaging with pre-approved message templates and delivery tracking.

No separate Twilio account needed. Twilio is the phone and messaging service that delivers your WhatsApp messages behind the scenes. The platform creates a managed Twilio account for you under the hood, so you don’t need to sign up for Twilio yourself or wire it to Meta manually. Buying a number or connecting an existing one happens entirely inside the app. If you specifically need to bring your own Twilio account (e.g. you already have warmed-up numbers and approved templates there), open the Twilio Account card on the Channels page and switch to your own account, then attach your existing sender — both steps are in SMS Provider (Bring Your Own Twilio). Most users should stick with the managed setup.

Prerequisites #

Before you begin, make sure you have the following:

• A Meta Business account (business.facebook.com) — business verification is optional: unverified businesses can activate a number, get templates approved, and send broadcasts, starting at the 250 unique contacts per 24 hours limit (see Messaging Limits below). You need it for Managed by us too: that option supplies the number and carries the messages, but the number still lives in your own WhatsApp Business Account, so you finish its setup in a Meta pop-up. The only way to connect WhatsApp without any Meta account is WhatsApp Web.
• An account with sufficient credits
• A phone number that is not already registered with WhatsApp (personal or Business app), and that is not already a Twilio number from another account

Add your business name and address first. Before you can buy your first number, fill in your business name and address under Settings → Business (Workspace group). The carrier validates this address, so make it accurate and complete — purchasing fails until it’s set. Some countries only accept a street address inside that same country: when the number’s country asks for one, the address country is fixed to it (for example, a Luxembourg number needs an address in Luxembourg), and a number from your own country is the way to use your own address.

Step 1: Buy a Phone Number #

1. In the left sidebar, click Settings near the bottom.
2. In the Settings left rail, under Channels, click Channels.
3. Find the WhatsApp Business API card and click the green Connect WhatsApp button.
4. Choose Get a new number from us, then Managed by us.

4. A Buy phone number pop-up opens. Pick a country — numbers and live pricing come straight from our carrier for that country — and optionally filter by Contains digits.

5. Browse the available numbers list that appears, each with its one-time purchase cost and monthly cost shown alongside it.

6. Click a number and fill in its Display name — the business name people see on WhatsApp. It must contain letters and should be your business or brand name; WhatsApp rejects a bare phone number and any name that includes the word “WhatsApp”. Then confirm the cost shown and complete the purchase.

A number bought here is for WhatsApp, not SMS. Numbers purchased through the platform are used for WhatsApp Business. They are not SMS numbers, and they are not calling numbers either: an inbound call reaches an automated recorder (there to answer WhatsApp’s verification call during setup), there’s no voicemail inbox to listen back to, and you can’t dial out from the number. SMS runs on your own Twilio account instead — see SMS. Don’t tell customers a bought number can do both; it can’t.

Credits are deducted from your account for the purchase. Each number then has a monthly rent to keep it active: at least 50 credits a month, and premium numbers cost more, in line with what the carrier charges. The number’s card on Settings → Channels always shows its exact monthly price, and the buy dialog shows it before you confirm.

That rent is the only monthly fee on the number — it includes the WhatsApp connection, so there’s nothing extra to pay to keep the number on WhatsApp. If you already rent numbers here, they move to this rate at their next billing cycle. See Phone Numbers.

Mexico and Argentina: only mobile numbers are offered for these countries. WhatsApp treats numbers there as mobile numbers, and only a mobile number can receive WhatsApp’s verification code — landline-style numbers can’t, so they aren’t listed. This also means the city prefix may differ from your own city; that doesn’t affect how your WhatsApp works.

Step 2: Connect the Number to Meta #

A bought number still needs to be activated with Meta before it can send and receive:

1. On the Channels page, the WhatsApp Business API card shows your new number in its list.
2. Click the number’s own connect action (Finish setup) — a Meta pop-up opens where you finish the connection with the Meta account that owns your WhatsApp Business Account, following Meta’s prompts.
3. When Meta confirms the connection, the number goes live automatically — there is no separate “announce” step. Its status switches to Active on its own once the connection is online.

You’ll be asked to log in to your Meta Business account and grant the platform permission to send and receive WhatsApp messages on your behalf.

Activation is usually automatic. It takes a few minutes, and in most cases you won’t need a verification call or code. Occasionally Meta keeps the number “Pending”, or the Meta window ends on “WhatsApp Connection Didn’t Complete” even though the ownership check passed. Leave the number as it is: it is re-checked every ten minutes, and a registration that stalled after a successful ownership check is re-registered for you automatically, usually within the next quarter of an hour. Do not delete the number or start Finish setup again in the meantime. If a number repeatedly fails to register, WhatsApp may be temporarily rate-limiting it — wait 24 hours and try again, or contact support if it is still Pending after an hour. The one exception is a WhatsApp Business Account that Meta has locked: see Locked by Meta below.

Already have your own Meta Cloud API number? #

You don’t have to buy through the platform. On the WhatsApp Business API card, click Connect WhatsApp, choose Use a number you already have, then Managed by us to open the Connect WhatsApp Business API modal:

1. Enter the number’s phone number, in international format (e.g. +1 555 123 4567).
2. Optionally, type a display name — the name shown to people you message on WhatsApp.
3. Click Continue to WhatsApp to finish the connection in Meta’s own window.

We strongly recommend NOT connecting your active personal WhatsApp Business number — connecting it here can disrupt your existing WhatsApp app. Use a fresh number.

In Meta’s window, add and verify your own number. Do not pick Meta’s free test number (it starts +1 555) — it can only message a handful of test contacts you add manually, so it can never reach real customers. If you enter or select Meta’s test number, the connection is rejected.

Moving a number that is currently on the WhatsApp app #

A number that is actively registered in the WhatsApp or WhatsApp Business app cannot be connected to the API — you have to release it from the app first. Do it in this order:

1. Save anything you need from the app first. Chat history does not carry over to the API, and deleting the account is permanent — export or back up important conversations before you continue.
2. Turn off two-step verification in the app (Settings → Account → Two-step verification), so the old PIN can’t interfere with API registration.
3. Delete the account in the app: Settings → Account → Delete my account. This releases the number — a number can only be on the app or on the API, never both at once.
4. Wait a few minutes for the release to propagate, then follow the connect steps above to connect the number.

Want your own WhatsApp Business Account without the developer setup? #

Through our Meta app is another answer to the same Connect WhatsApp button’s second question. You keep your own WhatsApp Business Account, but you don’t create anything in Meta’s developer site — you use our Meta app. Meta bills the conversations directly to your own WhatsApp Business Account. If you bring your own number: 50 credits a month from us for the connection. If you rent your number here: nothing extra, because the number’s rent already covers the connection. See Connect Through Our Meta App.

Prefer to run WhatsApp on your own Meta app? #

There is a further option for technical users and agencies: create your own app in Meta’s developer site and connect it directly. Meta bills you at their own rates, there are no per-message fees from us, and your clients only ever see your business name. The full walkthrough is in Connect Your Own Meta App.

Who pays the message fees depends on how the number is connected. Your own number Managed by us sends through our messaging account, so its message fees come out of your credits, the same as a rented number. Through our Meta app and your own Meta app, Meta bills the messages to the payment method attached to your WhatsApp Business Account, and if there isn’t a working one, Meta blocks broadcasts and template messages until you add one. Read WhatsApp Costs & the October 2026 Change before your first send — it also covers the pricing change coming on 1 October 2026.

Connection Gotchas #

A few issues trip up most new users during the Meta connection flow. Read these before you start activation.

Pick your own number, not Meta’s test number #

During the Meta connection flow, Meta will offer you a test phone number (a sample number in the +1 555 range) alongside the option to bring your own. Always bring your own. Meta’s test number can receive messages but can only send to a handful of numbers you manually add inside Meta, so it will never message real customers — every reply silently fails to send. The app blocks this: if you enter or select Meta’s test number, the connection is rejected and you’re asked to use a real number instead.

Your number has to end up inside the WhatsApp Business Account #

This is the most common reason a connection fails right at the last step. Choosing Meta’s test number, or clicking past the phone number step, leaves the WhatsApp Business Account you selected without your number in it — and there is then nothing for us to connect.

At the phone number step in Meta’s window:

1. Choose to add a new number.
2. Enter your number.
3. Verify it with the code Meta sends you by SMS or call.

When done correctly, your number appears under Phone numbers in that account in WhatsApp Manager, marked as verified. If the connection fails, the app tells you exactly which of these happened.

If it fails, don’t delete and recreate things #

When a connection fails, it is tempting to delete the WhatsApp Business Account and start over. Don’t. Deleting an account your number is attached to usually makes the problem harder to fix, and repeated connection attempts can get a number temporarily blocked by WhatsApp — which can become permanent. Read the error message: it names the specific problem and the next step. If it still won’t connect, contact support with the phone number and the error.

Each account needs its own WhatsApp Business Account #

A WhatsApp Business Account can only be linked to one messaging account at a time, so you cannot connect a second number through the same WhatsApp Business Account from a different account here — most often an agency and one of its sub-accounts, or two sub-accounts, all pointing at the same Business Account. Meta still shows the connection as successful, because the number really is verified and live in that Business Account, but activation stops here with a message naming the account that already uses it.

Two ways forward:

• Connect the number on the account that already uses that WhatsApp Business Account. Adding more numbers to it there works normally.
• Give this account its own WhatsApp Business Account. Start the connection again and choose to create a new WhatsApp Business Account instead of selecting the existing one. First remove the number from the old Business Account in Meta Business Manager, since a number can only belong to one of them.

Do not delete the existing WhatsApp Business Account to free it up — the number already running on it would stop working.

Don’t reuse a WhatsApp Business Account already linked to another BSP #

If your WhatsApp Business Account (WABA) is already linked to another BSP (Business Service Provider — another platform that connected to it previously), the connection here will fail and cannot be fixed by trying again; activation stops with a message saying the Business Account is already linked elsewhere. To avoid this, create a fresh WhatsApp Business Account in Meta Business Manager for this connection, rather than reusing one that has been wired up elsewhere.

Twilio in your Meta Business settings #

When you connect a number Managed by us, Meta adds Twilio to your Meta business as a partner. It shows up as Twilio in Meta Business Settings. Twilio is the service that carries your WhatsApp messages between WhatsApp and Your AI Connector, so it has to stay there.

Don’t remove Twilio. If it is removed, nothing comes in or goes out on that number: customers’ messages never reach you and your replies fail. Your AI Connector spots this, marks the number Offline under Settings → Channels and emails you. To fix it, reconnect the number under Settings → Channels, which adds Twilio back.

Step 3: Set Up Your WhatsApp Business Profile #

Your WhatsApp Business profile is what customers see when they interact with your business.

1. On the Channels page, find your WhatsApp-active number and open its profile editor.
2. Fill in:

3. Save to update your profile.

One Agent per Number #

If your account has more than one WhatsApp Business API number, each can be answered by a different AI Agent. The Who Answers New Conversations panel on the AI Agents page shows a per number block for WhatsApp with a picker per connected number: Same as WhatsApp follows the channel’s Agent; choosing another Agent (or No one’s answering) applies to that number only. Replies always go out from the number the customer messaged, whichever way each number is connected: a managed number, one on our Meta app and one on your own Meta app can sit side by side on one account, and a new number only carries the conversations that start on it. Details: Entry Points → One Agent per WhatsApp number. If a customer wrote to a WhatsApp number that is in your Meta business but not connected to this account, a reply to them is not sent from one of your other numbers (WhatsApp would refuse it); the message shows why, and connecting that number lets you reply from it. Templates still go out.

Your primary number #

When a contact has never messaged any of your numbers, a reply to them goes out from your primary number. To change it, open Settings → Channels, find the number on the WhatsApp Business API card and click Set as primary. Only a number that has finished connecting to WhatsApp can send: a number that still shows Setup not finished cannot send messages, and the app uses a connected number instead. Other numbers stay on your account as secondary numbers, and a bought number is billed every month whether or not its setup is finished, so either finish its setup or remove it if you don’t need it.

Understanding Messaging Limits #

WhatsApp imposes messaging limits to protect users from spam. These limits determine how many unique contacts you can message within a 24-hour rolling window.

Tier System #

How to Increase Your Limits #

• Verify your business on Meta Business Manager to move beyond the initial 250-contact limit to 2,000.
• Maintain high message quality — avoid getting reported or blocked by recipients.
• Send messages consistently — WhatsApp automatically increases your tier when you reach approximately half your current limit with good quality ratings, usually within 6 hours of meeting the criteria.

Message Types #

Session Messages (Free-form) #

Regular text, images, videos, documents, and other media you can send within an active conversation window.

• Can include any content
• Can only be sent within the 24-hour messaging window (see below)
• No pre-approval required

Shared locations #

When a contact shares a location (the paperclip → Location in WhatsApp, a pin or a saved place), the AI receives it as text inside the conversation: the place name and address when WhatsApp sends them, plus the coordinates, in the form [THE CONTACT SHARED A LOCATION] Playa Delfines, Cancún (21.1619, -86.8515). The agent can quote the address back, reason about it in its instructions (“if the contact is outside our delivery area, say so”) or pass the latitude and longitude on to a custom function or webhook as part of the conversation. The same shape is used whether the number is connected the default way (a number from us), through our Meta app, through your own Meta app, or on WhatsApp Web. Live (real-time) locations arrive once, with the position at the moment of sharing; the app does not follow the moving pin.

In Chats you see it as a card, not as that line of text: a pin with the place name and address, and an Open in Google Maps link that opens the exact spot in a new tab. A caption the contact typed with it shows underneath. The chat list shows a pin and the place name as the latest message.

Template Messages #

Pre-approved message formats that let you initiate conversations with customers outside the 24-hour window.

• Must be submitted to Meta for approval before use
• Support variables for personalization (e.g., customer name, order number)
• Required for initiating new conversations or re-engaging after 24 hours
• Available in multiple languages

Templates now live on their own page — see WhatsApp Message Templates for the full walkthrough.

The 24-Hour Messaging Window #

WhatsApp enforces a 24-hour conversation window to protect users:

• When a customer messages you, a 24-hour window opens. During this window, you can send any type of message (session messages) freely.
• After 24 hours of inactivity (no message from the customer), the window closes. You can only re-engage using an approved template message.
• When you send a template message, a new 24-hour window opens once the customer responds.

Replies inside this window stop being free on 1 October 2026. Meta has announced that from that date it charges for the free-form replies a business sends inside the 24-hour window, per message, at each market’s rate — the same rate utility and authentication templates already cost. They have been free since November 2024. Each phone number gets 1,000 free service messages a month first, and only the 1,001st onward is charged; the rate is the market’s utility rate, which is already on Meta’s rate card. What it means for you, and what to check before then, is on WhatsApp Costs & the October 2026 Change.

Testing Your Setup #

Before going live with customers, verify everything works:

1. Send a test message. Open the AI Agent or Broadcast assigned to this number and use its Try Out panel to send yourself a test message, or send from Chats directly.
2. Test incoming messages. Send a WhatsApp message from your personal phone to your business number and confirm it appears in Chats.
3. Test AI responses. Confirm the Agent replies within the expected timeframe and that its answers align with your instructions and Knowledge Base.
4. Test template messages. Create and approve a simple template, send it to your test number, and confirm it arrives with all variables filled in.

Troubleshooting #

Number Not Appearing as Active #

• Ensure you completed the full activation process, including logging into your Meta Business account and granting permissions.
• Check that your Meta Business account is in good standing.
• Wait a few minutes and refresh the page — activation can take time.

Pending Because Meta Is Still Reviewing a New WhatsApp Business Account #

If the Meta window created a brand new WhatsApp Business Account, Meta runs its own automatic review of that account before it lets the number go live. Until the review is approved, the number shows Pending in the app and in WhatsApp Manager. There is nothing to submit for this review and no way to speed it up from the app. Leave the number as it is: the app keeps checking, and the number connects on its own once Meta approves the account, even if that takes several days. Business Verification is a separate step; it raises your messaging limit but is not what this review waits on.

Locked by Meta #

Sometimes Meta locks the WhatsApp Business Account a number is on, for example while it waits for you to finish business verification or to resolve a review. A number on a locked account cannot connect: the app shows it as Locked by Meta, and hovering the badge tells you what to do. Re-registering does not help here, so the app does not try. Open Business Support Home in Meta Business Suite, follow Meta’s steps to unlock the account (and finish business verification if Meta asks for it), then leave the number as it is. The app keeps checking, and the number connects on its own once Meta lifts the lock; there is no need to reconnect or start Finish setup again.

If you would rather not wait, you can use the number on WhatsApp Web instead. Delete the number on Settings → Channels first, then delete it from the WhatsApp Business Account in WhatsApp Manager (a number that never went live can be removed there). After that, register it in the WhatsApp Business app on a phone and connect it with the QR code. Moving it back to the API later means deleting the account in the app again, as described in Moving a number that is currently on the WhatsApp app.

Number Shows Offline #

An Offline badge on the number under Settings → Channels means WhatsApp itself has stopped the number from sending. Hover over the badge to see why. The most common cause is Meta disabling the WhatsApp Business Account behind the number, usually over a policy issue; the badge then says so and points you to Meta Business Manager, where you can review the notice and appeal.

The badge also turns Offline when Twilio has been removed from your Meta business (see Twilio in your Meta Business settings); to fix it, reconnect the number under Settings → Channels.

While the number is offline, broadcasts from it are held back before they send instead of failing message by message, and automated replies from it can’t go out either. We check every number connected through this setup against WhatsApp once a day. When a number that was working goes offline with only a general WhatsApp error (no policy reason), that check re-registers it automatically, and you only get an email if that does not bring it back. For any other reason you get an email the first time the number goes offline. As soon as WhatsApp reports it back online the badge turns green again on its own, at the latest at the next daily check. If the number stays offline after you have resolved the issue on the Meta side, contact support and we will re-check it for you. Messages that could not be sent because the number was offline are not charged.

Number Shows Not Delivering #

A Not delivering badge on the number under Settings → Channels means the number is still connected and messages sent to you still arrive, but WhatsApp is not delivering the messages you send from it. Replies, including your Agent’s, stay queued for hours and then fail. In WhatsApp Manager this shows up as a number with no messaging limit; the usual causes are a restriction or review on the number or the WhatsApp Business Account, or a missing payment method. Hover over the badge for the reason.

Check the number in WhatsApp Manager and resolve what Meta shows there. While the badge is up, broadcasts from the number are held back before they send. We check every number connected through this setup once a day and email you the first time this happens; once WhatsApp delivers from the number again, the badge turns green on its own. In a chat, a reply that is still waiting to go out after 15 minutes shows an amber clock, so you can tell it apart from a message that is simply on its way.

Messages Not Sending #

• Verify you have sufficient credits in your account.
• Check if you have reached your messaging limit tier.
• Ensure the recipient’s phone number is in the correct international format (e.g., +1234567890).
• If sending outside the 24-hour window, make sure you are using an approved template.

Broadcasts and Templates Blocked, but Replies Still Work #

This pattern — you can answer people who message you first, but nothing you start goes out — almost always means the WhatsApp Business Account behind the number has no working payment method, and it only applies to connections that run on your own WhatsApp Business Account. Meta blocks business-initiated conversations (broadcasts, any template) until a valid payment method is on the account, and reports the error in WhatsApp Manager.

The app now stops a broadcast before it sends in this situation and tells you to add a payment method, instead of letting each message fail. Add or fix the payment method in WhatsApp Manager and send again — reconnecting the number here won’t clear it. See WhatsApp Costs & the October 2026 Change.

Template Rejected #

• Review Meta’s template guidelines — templates cannot contain promotional content in certain categories.
• Check for formatting issues, such as mismatched placeholders.
• Read the rejection reason Meta provided, revise, and resubmit — see WhatsApp Message Templates.

Poor Message Quality Rating #

• Review your message content for relevance and value to recipients.
• Avoid messaging contacts who have not opted in.
• Reduce message frequency if recipients are reporting or blocking you.

“Phone Number Not Found” Error #

• The phone number may not be properly linked to your Meta Business Account.
• Try re-activating the phone number through the WhatsApp connect flow.
• Contact support if the issue persists.

Best Practices #

• Always get consent before messaging customers on WhatsApp.
• Respond quickly to customer messages to make the most of the 24-hour window.
• Keep templates concise and valuable — high-quality templates get approved faster and perform better.
• Monitor your quality rating in Meta Business Manager to avoid tier downgrades.
• Let an AI Agent handle replies to ensure 24/7 responsiveness within the messaging window — see AI Agents.