Official WhatsApp API: the complete guide (2026)

Updated on October 29, 2026

The official WhatsApp API is Meta’s WhatsApp Business Platform, offered today as the WhatsApp Cloud API: an HTTP API hosted by Meta that lets your systems send and receive WhatsApp messages. To use it you need a Meta business portfolio, a phone number registered on the platform, approved templates to start conversations and a way to pay, since Meta charges per delivered message. It’s the only route Meta authorizes for automating a company’s WhatsApp.

This guide covers what separates the official WhatsApp Business API from unofficial libraries, the requirements, how to choose between integrating directly with Meta or going through an intermediary, what it costs in broad terms and when switching is worth it.

What the official WhatsApp API is

The WhatsApp Business Platform is the set of APIs Meta makes available to businesses. In practice, when people say “official WhatsApp API” today they mean the Cloud API: Graph API endpoints (graph.facebook.com) that take JSON and return JSON, plus webhooks that notify your server when a message arrives or the status of a sent message changes.

A few terms show up all the time in Meta’s documentation. It helps to know them before you start:

Term	What it is	Where it appears
Business portfolio	Your company’s account at Meta (formerly Business Manager). It can be verified.	business_id
WhatsApp Business Account (WABA)	Since September 23, 2026, Meta splits it into a WhatsApp account (the phone number) and a Messaging account (templates, billing, webhooks). Old IDs and endpoints keep working during the transition.	waba_id
Business phone number	The number registered on the Cloud API, used to send and receive.	phone_number_id
Template (message template)	A pre-approved message, required to start contact outside the customer service window.	type: "template"
Customer service window	A 24-hour period opened by each customer message, during which you can reply with free-form messages.	sending and pricing rules
Webhook	A URL on your system that receives events (incoming messages, delivery statuses).	object: "whatsapp_business_account"

The account split is explained step by step in WhatsApp account vs Messaging account: the new WABA structure.

Official API vs unofficial API

Libraries such as Baileys and WPPConnect, and tools built on them (such as Evolution API’s Baileys mode), work by emulating WhatsApp Web: you scan a QR code with your phone and the software takes over that session. There’s no agreement with Meta, no templates and no per-message billing. There’s also no guarantee the next WhatsApp update won’t break the integration.

The WhatsApp Terms of Service prohibit accessing or using the service through automated means that aren’t authorized, and creating accounts “through unauthorized or automated means.” They also list bulk messaging and auto-messaging among impermissible communications. That’s why numbers used with unofficial APIs can be banned without warning.

Criterion	Official API (Cloud API)	Unofficial API (Baileys, WPPConnect, etc.)
Authorized by Meta	Yes, it’s Meta’s product for businesses	No; it goes against the Terms of Service
Connection	Access token and HTTP calls	WhatsApp Web session via QR code
Ban risk from the tool itself	No; risk comes from quality and policy	High and unpredictable
Starting a conversation	Only with an approved template	Free-form message (and that’s where the risk is)
Message cost	Per delivered message, Meta’s rate card	No Meta charges
Stability	Versioned, with a changelog and deprecation dates	Depends on reverse engineering
Webhooks	Format documented by Meta	Each library’s own format

Worth noting: Evolution API also offers an integration with the official Cloud API, besides its Baileys-based mode. What defines the risk is the channel, not the tool’s name. If that’s your situation, How to migrate from an unofficial API to the official WhatsApp API has the step by step, and Official vs unofficial WhatsApp API goes deeper into the ban risk.

Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →

Requirements to use the official API

A business portfolio at Meta

Everything on the platform starts from a business portfolio. That’s where your WhatsApp and Messaging accounts, numbers, system users and payment method live.

Business verification

Verification isn’t required for your first steps, but it changes what you can do. According to Meta’s messaging limits documentation, new portfolios start with a limit of 250 unique recipients per rolling 24 hours outside the customer service window. Verifying the business is one of the ways to move up to 2,000 (the others are having your partner verified, or delivering 2,000 messages outside the window to unique numbers within 30 days with high-quality templates). The limit on registered numbers depends on it too: new portfolios can register two numbers, and the cap rises to 20 once the business is verified or reaches the 2,000 limit.

In Vectalk’s flow, the quickstart asks for a verified Meta Business account to connect the number. So treat verification as part of the project, not an optional step. Our guide to Meta business verification covers the process.

Phone number

Per Meta’s business phone numbers documentation, the number must:

• belong to your business;
• have a country code and an area code (short codes aren’t accepted);
• be able to receive an SMS or voice call for the verification code.

One thing that trips many people up: numbers already in use on WhatsApp can’t be registered on the Cloud API until the account is deleted from the app. The exception is a number on the WhatsApp Business app, which can be connected to the API while you keep using the app, a feature known as coexistence. We cover requirements and limitations in WhatsApp API coexistence.

You’ll also need a display name. Depending on the name, Meta may review it before it can be used.

Payment method

Since October 1, 2026, Meta charges for service messages beyond a free monthly allowance per number. The pricing page states that accounts without a payment method only get service messages delivered within that allowance. In practice, any production operation needs a funded billing setup: either your own payment method at Meta or a provider’s credit line (with Vectalk, it’s the latter; see below).

Contact consent (opt-in)

The WhatsApp Business Messaging Policy only allows you to contact people who gave you their phone number and opt-in permission to receive messages. Requests to stop must be respected, including those made off WhatsApp. This applies to every official integration and is one of the biggest factors in your number’s quality.

Limits you need to know

Limit	Default value	Notes
Messaging limit (outside the window)	250 unique recipients / rolling 24 h for new portfolios	Rises to 2,000, 10,000, 100,000 and unlimited based on verification, volume and quality. Applies to the whole portfolio.
Registered numbers per portfolio	2 at first	Goes to 20 with verification or on reaching the 2,000 limit
Throughput	80 messages per second per number by default	Eligible numbers are upgraded automatically up to 1,000 mps; coexistence numbers stay at 20 mps
Customer service window	24 hours from the customer’s last message	Outside it, templates only

Sources: messaging limits, phone numbers and throughput.

An important detail: the messaging limit belongs to the portfolio, not the number. If you have three numbers in the same portfolio, one of them can use up the whole day’s capacity. Above 2,000, the limit scales automatically when quality is high and you’ve used at least half of it in the last 7 days.

How conversations work: the 24-hour window and templates

The core rule of the official API is simple. When a customer messages you, a 24-hour customer service window opens. Inside it you can reply with any message type: text, images, buttons, lists. Each new customer message restarts the clock.

Outside the window you can only send templates. They’re created with a category (marketing, utility or authentication), go through Meta’s approval and accept variables. An order confirmation template, for example:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Maria" },
          { "type": "text", "text": "#12345" }
        ]
      }
    ]
  }
}

This is the same payload accepted by Meta and by Vectalk. The template’s category also sets the price of the message, which we detail in WhatsApp API pricing in Brazil.

One change to plan for: Meta is moving marketing templates to the Marketing Messages API. The Cloud API (/messages) stops sending marketing messages on October 13, 2027, and Messaging accounts created from April 13, 2027 can’t send them there at all. See Marketing Messages API: how to migrate.

Solution Partner, Tech Provider or direct Cloud API

There are three ways to reach the Cloud API. The difference is who handles the app at Meta, tokens, webhooks and billing.

Direct integration. You create an app in Meta’s dashboard, generate a system user token, set up the webhook with verification and signature checks, subscribe to the account’s webhook fields and handle credential rotation. There’s no intermediary, but the whole operation sits with your team.

Meta partners. The partner documentation splits intermediaries into three types:

• Solution Partners (what the market calls BSPs): Meta Business Partners that can extend credit lines to their clients and bill them directly for platform usage.
• Tech Providers: offer services on top of the platform, but without a credit line. Clients add their own payment method and Meta bills them directly for API usage.
• Tech Partners: Tech Providers that are, or are eligible to become, Meta Business Partners.

Managed proxy. This is Vectalk’s model. Your application talks to Vectalk, which forwards the calls to the Cloud API. Payloads are the same as Meta’s; only the base URL and the token change:

	Direct Cloud API	Vectalk
Base URL	https://graph.facebook.com/vXX.X	https://apis.vectalk.com.br/api
Token	Meta access token (system user)	Token generated in Vectalk
Payloads	Meta’s format	Same as Meta’s
Multiple accounts	One token and one phone_number_id per context	One organization token for all instances, sending the phone_number_id
Webhooks	One endpoint per app, configured in Meta’s dashboard	Multiple URLs per instance, registered via API

With Vectalk, sending a text message looks like this:

curl -X POST https://apis.vectalk.com.br/api/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5584999999999",
    "type": "text",
    "text": { "body": "Your order is out for delivery." }
  }'

If you already have code written for the Cloud API, moving to the proxy means changing two environment variables. Organization and instance tokens are explained on the authentication page. For a side-by-side of the options, read Direct from Meta or through a provider?.

Costs in broad terms

Since July 1, 2025, Meta charges per delivered message, priced by message category and by the recipient’s country code. The template categories are marketing, utility and authentication; non-template messages are service messages, and since July 1, 2026 there’s also Meta Business Agent, for replies generated by Meta’s own AI, billed at a global rate of US$2.00 per 1 million tokens. Some messages are free: those sent inside the free entry point window opened by Click-to-WhatsApp ads (which can stay open for up to 7 days; Meta Business Agent messages are still charged inside it) and the first 1,000 service messages each month, per number. Since October 1, 2026, utility templates sent inside the customer service window are charged.

In Brazil, Meta publishes the official rate card in Brazilian reais (BRL), and BRL accounts are invoiced by Facebook Brasil. Rates, volume tiers and the October 2026 changes are covered in WhatsApp API pricing in Brazil. If your customers are in other markets, see WhatsApp API pricing by country.

When the official API makes sense

It pays off when WhatsApp is part of your product or operation, not a side channel:

• Systems that need to notify customers: order confirmations, appointment reminders, a new copy of a boleto (Brazil’s bank payment slip), verification codes.
• Support with several people or with AI: one number, several agents or an automated agent replying, with history stored in your system.
• SaaS that offers WhatsApp to its own customers: CRMs, ERPs, scheduling and e-commerce platforms that need to connect third-party numbers securely.
• Operations that can’t stop: any flow where a banned number is expensive.

And it makes less sense in some cases:

• when usage is only manual chatting, with a few messages a day, and the WhatsApp Business app is enough;
• when the plan depends on messaging lists without consent, which the policy doesn’t allow on any official API;
• when the flow depends on features the Cloud API doesn’t cover, or covers with limits. The Groups API, for example, requires an Official Business Account and allows at most 8 participants per group, according to the groups documentation.

Getting started with Vectalk

1. Create your account at apps.vectalk.com.br/register. An organization is created automatically.
2. In Instances (Instâncias in the Portuguese interface), click Connect account (Conectar conta in the Portuguese interface) and complete Meta’s Embedded Signup. Vectalk imports the phone_number_id, the waba_id and the access token.
3. In Settings → API Tokens (Configurações → API Tokens in the Portuguese interface), generate an organization or instance token. It’s shown only once.
4. Send your first message with POST /api/messages and register a webhook with POST /api/webhooks.

Billing works as a monthly fee plus prepaid balance: Vectalk places its own credit line on your number, each delivered message is deducted from your balance, and you don’t add a card at Meta. The full walkthrough is in the documentation quickstart. For account and billing questions, contact us.

Frequently asked questions

Is the official WhatsApp API free?

No. Meta charges per delivered message, based on category and the recipient’s country. Some messages aren’t charged, such as the 1,000 free service messages per month per number and messages inside the free entry point window. The intermediary you choose may charge separately for its own service.

Do I need a CNPJ to use the official API?

A CNPJ is Brazil’s company registration number. Meta requires a business portfolio, and business verification asks for documents about the organization. Check Meta’s Business Help Center for the documents accepted in your country before you start.

Can I use the number I already have on my phone?

If the number is on the WhatsApp Business app, you can connect it to the API without leaving the app, through coexistence. If it’s on regular WhatsApp (Messenger), you have to delete the account from the app before registering the number on the Cloud API.

What’s the difference between the official API and the WhatsApp Business app?

The app is built for manual use on a phone and computer. The API is for systems: programmatic sending, webhooks, multiple agents, integrations and automation. The API has template and 24-hour window rules that the app doesn’t.

How long does it take to go live?

The technical integration is usually quick when your team already knows REST APIs. What tends to take longer is Meta’s side: business verification and display name and template approvals. Plan those steps ahead.

---

Sources checked on October 29, 2026: WhatsApp Business Platform pricing, Messaging limits, Business phone numbers, Throughput, Solution providers, Account model evolution, Marketing Messages API, Groups, WhatsApp Terms of Service, WhatsApp Business Messaging Policy.