Buddy
All posts

Developers

WhatsApp Business API integration: how to build one that holds up in production

Sending your first WhatsApp message through the API takes an afternoon. Running it in production takes consent records, templates, webhooks and retries. This guide walks through all of it, with working code, and shows where the Buddy API saves you the plumbing.

The Buddy Team · · 10 min read

Developers

API integration

A WhatsApp Business API integration connects your software to Meta's WhatsApp Business Platform, so your product can send approved template messages, reply to customers and receive delivery statuses and replies through webhooks. You can build it on Meta's Cloud API directly, or on a platform API such as Buddy's that handles consent, templates, retries and reporting for you.

The first message is the easy part. What breaks integrations is everything around it: a STOP reply that never reaches your database, a webhook processed twice, a campaign that hits a messaging limit halfway through. The same rules apply whichever route you take: people must opt in, business-initiated messages need an approved template, and your reach grows only as fast as your quality allows.

This guide covers the Cloud API's building blocks, the rules every integration has to respect, a working template send, webhook handling, and how the Buddy API fits in. It's part of our guide to choosing a WhatsApp marketing platform.

What is the WhatsApp Business API?

The WhatsApp Business Platform is Meta's official way for businesses to message people on WhatsApp at scale. Its API, the Cloud API, is hosted by Meta and exposed through the Graph API (Meta, about the platform). It's now the only option: the last version of the older self-hosted On-Premises API expired on 23 October 2025, and Meta says the Cloud API handles up to 1,000 messages per second (Meta, On-Premises API sunset).

Building blockWhat it is
WhatsApp Business AccountThe account that holds your phone numbers and message templates
Business phone numberThe number customers see and message. Each one has a phone number ID you send from
Message templateA pre-approved message with variables, buttons and optional media, in one of three categories
WebhookAn HTTPS endpoint of yours that Meta calls with incoming messages and delivery statuses
Business portfolioThe Meta business that owns the account. Messaging limits are set at this level

What rules does every WhatsApp API integration follow?

Four rules shape the design of any integration. Build them into your data model from day one, because they're painful to retrofit.

1. Opt-in comes first

Meta requires that people agree to receive WhatsApp messages from your business before you message them, and the opt-in must name your business (Meta, getting opt-in). Your integration needs somewhere to store who agreed, when, where and to what, plus a way to stop instantly when someone opts out. Our WhatsApp opt-in guide has the wording and the record to keep.

2. The 24-hour window decides what you can send

When a customer messages you, a 24-hour customer service window opens, and every new message from them resets it. Inside it you can send free-form text, images and documents. When the window closes, "you can only send pre-approved template messages" (Meta, send messages). Most product-triggered messages, such as a shipping update or a renewal notice, happen outside a window, so they must be templates.

3. Templates need approval and a category

Every template is marketing, utility or authentication (Meta, templates), and the category sets its price and its rules. Review "can take up to 24 hours" (Meta, template review), so create templates before the feature that needs them ships. Our WhatsApp message templates guide covers categories with examples.

4. Messaging limits grow with quality

A new business portfolio can reach 250 unique people in a rolling 24 hours with business-initiated messages, rising through 2,000, 10,000 and 100,000 to unlimited as you send well. The limit is shared by every number in the portfolio (Meta, messaging limits). If your product sends on behalf of a big launch, queue and pace the sends rather than firing them all at once. Our guide to messaging limits and quality rating explains the tiers.

Meta also charges per delivered message, by category and recipient country (Meta pricing).

How to integrate directly with the Cloud API

Meta's get started guide walks through the setup. In short:

  1. 1Create a Meta app with the WhatsApp use case in the App Dashboard.
  2. 2Connect a WhatsApp Business Account, then send a test message from the API Setup screen.
  3. 3Set up a webhook endpoint to receive incoming messages and statuses such as delivered and read.
  4. 4Create a long-lived credential for your server in Business Settings, and keep it out of client code.
  5. 5Register your real business phone number and submit your own templates for approval.
  6. 6Send from your server, using your phone number ID.

Send a template message

Every send is a POST to your phone number's messages endpoint. Here is a template send using the endpoint from Meta's send messages guide and the payload from its templates overview, with named parameters:

Cloud API: send an approved utility template. Replace PHONE_NUMBER_ID and the token with your own.
curl 'https://graph.facebook.com/v25.0/PHONE_NUMBER_ID/messages' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+447700900123",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en_GB" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "parameter_name": "first_name", "text": "Amira" },
            { "type": "text", "parameter_name": "order_number", "text": "HX-4821" }
          ]
        }
      ]
    }
  }'

A successful response returns a message ID. Save it: every delivery status that arrives later by webhook refers to that ID, and it's how you tie a read or a failure back to the right customer and campaign.

How do WhatsApp webhooks work?

Webhooks are how Meta tells you what happened: a customer replied, a message was delivered or read, a send failed. Setup starts with a verification request. Meta sends a GET with hub.mode set to subscribe, a hub.verify_token you chose and a hub.challenge number; you check the token and echo the challenge back (Meta, webhooks). After that, events arrive as signed POST requests.

Verify every payload

Meta signs each request with SHA-256 using your app secret and puts the result in the X-Hub-Signature-256 header, prefixed with sha256= (Meta, webhooks). Compute the same signature over the raw request body and compare before trusting anything.

Node.js: check Meta's signature against the raw body before parsing it.
import crypto from "node:crypto";

export function isFromMeta(rawBody, signatureHeader, appSecret) {
  const expected = crypto
    .createHmac("sha256", appSecret)
    .update(rawBody)
    .digest("hex");
  const received = (signatureHeader || "").replace("sha256=", "");
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Acknowledge fast, process later

Return HTTP 200 straight away, then handle the event on a queue. If your endpoint returns anything else, Meta "retries delivery with decreasing frequency until the request succeeds, for up to 7 days" (Meta, webhooks overview). Slow handlers turn into retry storms.

Expect duplicates and gaps

  • Deduplicate on the message ID. Meta warns that retries "can result in duplicate webhook notifications" (Meta).
  • Don't require a delivered status before a read. When someone receives a message while they're already in the chat, it's delivered and read at once, and Meta skips the delivered webhook (Meta, status webhooks).
  • Treat read counts as a floor. People can turn off read receipts in WhatsApp (WhatsApp Help Center), so some messages are read without a read status. Replies and clicks are firmer signals.

What does a production integration need beyond sending?

This is the list that turns a two-day prototype into a two-month project. Each item is small. Together they're most of the work.

  • A consent store with source, date, wording and category for every subscriber.
  • STOP handling that catches "stop", "unsubscribe" and opt-outs made inside WhatsApp, and suppresses the number everywhere.
  • Status tracking that maps every webhook to a message, a person and a campaign.
  • Retries with idempotency, so a timeout never sends the same message twice.
  • Pacing that respects your messaging limit and per-user marketing limits.
  • Template sync, so your app knows which templates are approved, paused or rejected.
  • Screens for the people who write the messages, so marketing and support aren't waiting on a deploy to change a sentence.

Should you build on the Cloud API directly or use a platform?

Both are sound choices. Building directly gives you complete control and no extra vendor. Building on a platform such as Buddy gives you the production list above already done, an app your marketing and support teams use, and an API for the parts your product automates.

TaskDirectly on the Cloud APIWith Buddy
Connect a numberBuild the connection flow yourselfConnect in a few clicks through Meta's own signup window
Collect opt-insBuild forms, storage and an audit trailOpt-in page, QR code and website form, each recording source and date
STOP and opt-outsParse replies and suppress numbers yourselfHandled automatically and sent to you as a webhook
TemplatesManage templates and track review yourselfTemplate builder with approval status kept in sync
SendingQueue, throttle, retry and deduplicate yourselfOne API call with an idempotency key, or a scheduled WhatsNew
StatusesParse Meta's webhooks and store themSigned Buddy webhooks for sent, delivered, read, replied and failed
RepliesStore messages and build a UIShared inbox and automations
Meta feesBilled by Meta to your accountStill billed by Meta to your account, with no Buddy mark-up

How to integrate WhatsApp with the Buddy API

The Buddy API connects your product to your WhatsApp audience in Buddy. Create an API key in your workspace settings, keep it on your server and send it as a Bearer token. Test keys return the same responses and webhooks as live keys and never deliver a message, so you can build safely. Full reference lives on the REST API page.

Add a subscriber who opted in

Add a subscriber. Only phone is required, in international format; name and tags are optional.
curl -X POST https://usebuddy.app/api/v1/subscribers \
  -H "Authorization: Bearer $BUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amira Haddad",
    "phone": "+447700900123",
    "tags": ["trial", "web-signup"]
  }'

Each subscriber added this way is recorded with its source and appears in your consent history like any other opt-in. Adding a number that already exists merges the new tags, and Buddy never re-subscribes someone who opted out: the API answers with a clear subscriber_opted_out error instead. Tags you set here are the same tags your team uses to target WhatsNew and automations.

Send an approved template

Send a template. Buddy checks consent and the 24-hour window first; the Idempotency-Key makes retries safe.
curl -X POST https://usebuddy.app/api/v1/messages \
  -H "Authorization: Bearer $BUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_1042" \
  -d '{
    "to": "+33612345678",
    "template": "order_shipped",
    "variables": { "name": "Camille", "order": "1042" }
  }'

If the same idempotency key arrives again, Buddy returns the original result instead of sending twice. Transactional updates such as receipts and renewal notices, and one-time passcodes on authentication templates, go through the same endpoint.

Send events and let your team decide the message

Instead of hard-coding every message, send Buddy an event such as trial_started or order_paid with the properties your messages need. Your marketing team then uses it as an automation trigger or segment rule in Buddy, and changes the journey without a deploy. See Events.

Receive signed webhooks

Buddy webhooks tell your app when a message is sent, delivered, read, replied to or fails, and when a subscriber is created, tagged, opts in or opts out. Each request carries a Buddy-Signature header made with your endpoint's secret, failed deliveries are retried with backoff, and every event can be replayed from the log. Forward subscriber.opted_out to your CRM and email tool, and someone who said STOP on WhatsApp is respected across your whole stack. See Webhooks.

What can you build with a WhatsApp API integration?

Signup form to WhatsApp list

A SaaS product adds an unticked "Send me product updates on WhatsApp" box to signup and adds each opted-in user with a trial tag. Our WhatsApp for SaaS guide has the lifecycle messages.

Order updates from your backend

A store sends order_paid and order_shipped events, and approved utility templates confirm and track each order.

CRM sync

An agency pushes contacts who opted in through its CRM, tagged by interest, and receives opt-outs back by webhook.

Replies into your help desk

message.replied webhooks open a ticket, so a customer's answer reaches a person in seconds.

No backend needed

Collecting signups on your website? The Buddy opt-in form does it with one script tag.

Connecting a store or no-code tool instead of your own product? Our guide to WhatsApp integrations covers Shopify, WooCommerce, Zapier and Make.

Frequently asked questions

Is the WhatsApp Business API free?

No. The API itself has no fee, but Meta charges per delivered message, by category and recipient country, billed to your WhatsApp Business Account. See Meta's pricing for current rates.

Can I send any message through the WhatsApp API?

Only inside a 24-hour customer service window, which opens when the customer messages you. To start a conversation, or after the window closes, you must use a template Meta has approved, and the person must have opted in to hear from your business.

Which Graph API version should I use for the Cloud API?

Use the version shown in Meta's current send messages guide, which is v25.0 at the time of writing, and pin it in one config value so upgrades are a one-line change. Meta publishes new Graph API versions regularly and retires old ones on a schedule.

How long does Meta keep retrying a webhook?

Up to 7 days, with decreasing frequency, until your endpoint returns 200. Retries can create duplicates, so deduplicate by message ID (Meta).

Can I send WhatsApp messages with the Buddy API?

Yes. POST an approved template to the messages endpoint with an idempotency key. Buddy checks consent first, and you get statuses back by webhook or by asking the API.

Do I need my own Meta developer app to use Buddy?

No. You connect your WhatsApp Business number to Buddy through Meta's own signup window. Buddy is a Meta Tech Provider, and your account, number and templates stay in your own Meta business account.

Start sending WhatsApp campaigns with Buddy.

Connect your number, collect subscribers with consent and send your first WhatsNew.

Join the waitlist