WhatsApp Business

Getting Started with WhatsApp Cloud API: The Setup Checklist I Use

Getting Started with WhatsApp Cloud API: The Setup Checklist I Use

From Business Portfolio to first production message: the setup steps for WhatsApp Cloud API and the decisions worth making before writing code.

WhatsApp Cloud API building blocks

Before touching code, it helps to know how the pieces relate. Most setup confusion comes from mixing up these objects.

  • Business Portfolio: the business entity in Meta that owns assets and completes verification.
  • WhatsApp Business Account (WABA): the container for phone numbers and message templates.
  • Phone number: the number customers message, with its own display name, quality rating, and messaging limit.
  • Meta app: the developer app connected to the WhatsApp product and your webhook.
  • System user and token: the server credential your backend uses to send messages.

WhatsApp Cloud API setup steps

  • Create or choose the Business Portfolio and start Business Verification early.
  • Create a Meta app and add the WhatsApp product.
  • Add a production phone number that is not active on the WhatsApp consumer or Business app, or migrate it properly first.
  • Set a display name that matches the business, and wait for approval.
  • Create a system user, assign it to the app and the WhatsApp Business Account, and generate a token with whatsapp_business_messaging and whatsapp_business_management.
  • Configure the webhook URL and subscribe to the messages field.
  • Add a payment method to the WhatsApp Business Account.

The test number Meta provides is useful for the first hour of development, but switch to a real number early. Display name approval and verification take time you should not leave until launch week.

Sending your first WhatsApp message

Businesses can start conversations only with approved templates. This request sends Meta's default hello_world template to a test recipient:

POST https://graph.facebook.com/{version}/{phone-number-id}/messages
Authorization: Bearer {system-user-token}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "{recipient-phone-number}",
  "type": "template",
  "template": {"name": "hello_world", "language": {"code": "en_US"}}
}

Once the customer replies, the customer service window opens and free-form messages are allowed for 24 hours from their last message. I test both cases early because they shape the entire product flow, as described in designing a WhatsApp booking bot around the messaging window.

Receiving messages with webhooks

Inbound messages, delivery statuses, and read receipts arrive at your webhook under entry, changes, and value. Verify the signature, store the event, and process it in a background worker. The patterns in handling Meta webhooks in production apply directly, including idempotency: WhatsApp can deliver the same message or status more than once.

Status events matter as much as messages. They tell you whether a message was sent, delivered, read, or failed, and failures include error codes you should store and surface to operations teams.

Decisions to make before writing code

  • How WhatsApp conversations map to your data model: customer, conversation, booking, ticket.
  • Whether one number serves one brand, or several tenants share numbers. Usually each tenant should own its number.
  • How human agents take over from automation, and how they see conversation context.
  • Which message templates the product needs for notifications and reminders.
  • Which interactive features to use: reply buttons, list messages, or WhatsApp Flows for structured forms.
  • How opt-in is collected and recorded before sending business-initiated messages.

Changing these later is far harder than changing an API call.

Quality rating and messaging limits

Each phone number has a quality rating based on how customers respond to your messages, including blocks and reports. Business-initiated messaging is also limited per number, and limits increase as you send high-quality messages and complete verification. Low quality can reduce limits or pause templates.

The best protection is product design: message only people who opted in, send messages they expect, and make it easy to stop. In my experience, quality problems almost always start with templates used for promotions that customers did not ask for.

Multi-tenant WhatsApp setups

If your product serves many businesses, each business usually needs its own WhatsApp Business Account and phone number, so its display name, quality rating, and templates are its own. Embedded Signup lets businesses connect their accounts to your app from inside your product, which is much smoother than collecting credentials manually. Plan your data model so every message, template, and token is linked to the tenant that owns it.

Production checklist for WhatsApp Cloud API

  • Business Verification complete and display name approved.
  • System user token stored encrypted, with minimal assigned assets. See managing Meta access tokens.
  • Webhook signature validation, idempotency, and monitoring in place.
  • Templates approved for every business-initiated message the product sends.
  • Opt-in recorded and an easy opt-out path available.
  • Error codes from failed messages stored and visible to operations.

Frequently asked questions

Can I use my existing WhatsApp number with the Cloud API?

Yes, but a number can only be active on one WhatsApp service at a time. Migrate it from the WhatsApp app or another provider before registering it with the Cloud API.

Do I need Business Verification for WhatsApp Cloud API?

You can start testing without it, but verification is needed to raise messaging limits and is expected for production use.

How does WhatsApp Cloud API pricing work?

Pricing depends on the message category and the recipient's country, and Meta updates it periodically. Check Meta's current pricing page before estimating costs.

Can I send free-form messages anytime?

No. Free-form messages are allowed only within 24 hours of the customer's last message. Outside that window, use approved templates.