WhatsApp API Integration Tutorial

The WhatsApp Business API is the infrastructure that turns WhatsApp into a proper business communication channel — handling thousands of conversations, running automated chatbots, and sending bulk broadcasts to opted-in contacts. Getting it connected to your product or platform is a one-time technical investment that pays off every day in automated workflows and customer engagement.

This WhatsApp API integration tutorial walks through the complete process from nothing to a working integration: account prerequisites, phone number setup, webhook configuration, message template approval, and sending your first programmatic message. Two paths are covered — through a no-code Business Solution Provider (BSP) if you want to skip the infrastructure work, and directly against the WhatsApp Cloud API if you want full technical control.

Before You Start: What You Need

Before writing a single line of code or creating an account, gather these prerequisites:

A Meta Business account. You need a Meta Business Manager account tied to your business. If you do not have one, create it at business.facebook.com. Use a business email address, not a personal one.

A verified business. Meta requires business verification for higher message volume tiers and certain template categories. You will need your business registration details and a document such as a utility bill or government filing that confirms your business name and address. Verification takes 2–5 business days.

A phone number. The number must be capable of receiving an SMS or voice call to verify ownership. Critically, it cannot already be registered on the WhatsApp consumer app or the WhatsApp Business App — if it is, you must delete the existing account from WhatsApp before registering it on the API.

A webhook endpoint (for direct integrations). If you are building a direct API integration, you need a publicly accessible HTTPS endpoint that can receive POST requests from Meta. This is where WhatsApp will deliver incoming messages and message status events. Local development tools like ngrok work for testing; production requires a real server.

Path 1: Integration Through a Business Solution Provider

For most businesses, integrating through a WhatsApp Business Solution Provider (BSP) is the fastest and most practical route. A BSP like Greenbubble has already built the webhook infrastructure, template management UI, and the connection to Meta's API — you use it through a dashboard rather than managing servers.

Step 1: Create Your BSP Account

Sign up for a Greenbubble account. During signup, you will connect your Meta Business account through an embedded flow — this authorises Greenbubble to manage your WhatsApp Business Account (WABA) on your behalf.

The embedded signup handles the OAuth handshake with Meta, creates your WABA automatically, and links it to your Meta Business Manager. You do not need to navigate the Meta Business Manager or the Meta developer portal directly.

Step 2: Add and Verify Your Phone Number

Inside the BSP dashboard, navigate to the phone number setup section. Enter the phone number you want to use as your WhatsApp business number.

WhatsApp will send a 6-digit OTP to that number via SMS or voice call. Enter the code in the dashboard. Once verified, your number is registered on the WhatsApp Business Platform and live on the API — messages sent to it will arrive in the BSP inbox.

If the number was previously registered on the WhatsApp Business App, you must first open the app, go to Settings, delete the account, and then proceed with registration on the API side. The number cannot be active on both products simultaneously.

Step 3: Configure Your Business Profile

Set up your WhatsApp Business profile within the BSP dashboard:

• Display name: The name your contacts will see. Meta reviews this for brand consistency — it should match your business name on your website and Meta Business account.
• Category: Select the category that best describes your business.
• Description: A short description of what your business does (up to 256 characters).
• Profile photo: Your business logo or a clear brand image.

Display name approval can take up to 24 hours. A name that closely matches your registered business name is approved more quickly. Generic or keyword-heavy names are often rejected.

Step 4: Create and Submit Message Templates

To send outbound messages to customers (outside of a customer-initiated conversation), you need approved message templates. Navigate to the template manager in the BSP dashboard.

Template categories:

• Marketing: Promotional content, offers, product announcements
• Utility: Transactional messages tied to a customer's existing relationship with your business — order updates, account alerts, appointment reminders
• Authentication: One-time passcodes and verification messages

Each template requires:

• A unique name (lowercase, underscores only, no spaces)
• The category
• The message body, with dynamic variables in double curly braces: {{1}}, {{2}}, etc.
• Optional header (text, image, video, or document)
• Optional footer text
• Optional buttons (URL, phone number, or quick-reply)

Example utility template:

Header: Order Update
Body: Hi {{1}}, your order #{{2}} has been dispatched and is expected to arrive by {{3}}. Track your order here: {{4}}
Button: Track Order → [URL]

Submit the template through the BSP dashboard. Meta's automated review typically responds within a few minutes for straightforward templates; complex or flagged templates can take up to 24 hours.

Common rejection reasons: vague variable usage, overly promotional language in utility templates, or content that could be used for deception. If a template is rejected, revise the flagged element and resubmit — you can view the rejection reason in the template manager.

Step 5: Build Your First Automated Flow

With templates approved and your number live, use the BSP's no-code chatbot builder to create your first automated workflow. A typical starting point:

1. Welcome flow: Triggered when a contact messages your number for the first time. Sends a greeting, offers a menu of options.
2. FAQ handler: Automatically answers common questions without a human agent.
3. Lead capture: Collects contact details and hands off to a sales agent with a notification.

Test each flow by messaging your WhatsApp number from a personal device. Verify that the bot responds correctly, that variables are populated, and that handoffs to human agents work as expected.

For broadcast campaigns and bulk messaging, create a contact list, select an approved template, and schedule or send the broadcast from the campaigns section of the dashboard.

Path 2: Direct WhatsApp Cloud API Integration

If you are building a custom integration — connecting WhatsApp directly to your own platform, CRM, or application — the WhatsApp Cloud API gives you full programmatic control. This path requires a developer comfortable with REST APIs and webhook architecture.

Step 1: Create a Meta Developer App

Go to developers.facebook.com and create a new app. Select Business as the app type. Connect it to your Meta Business account.

Inside the app dashboard, find the WhatsApp product and click "Set Up" to add it to your app. This provisions a test WABA and a test phone number automatically — useful for development before connecting your real business number.

Step 2: Configure Your Webhook

Your application needs to receive events from Meta — incoming messages, delivery receipts, read receipts, and opt-out signals. Meta delivers these as HTTP POST requests to a webhook URL you specify.

Register your webhook:

1. In the Meta app dashboard, go to WhatsApp → Configuration → Webhook.
2. Enter your webhook URL and a verification token (a string you choose).
3. Meta sends a GET request to your URL with a challenge parameter. Your endpoint must echo back the challenge value to confirm ownership.

Webhook verification handler (Node.js example):

app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

1. Subscribe to the messages webhook field to receive incoming message events.

Incoming message handler:

app.post('/webhook', (req, res) => {
  const body = req.body;
  if (body.object === 'whatsapp_business_account') {
    body.entry.forEach(entry => {
      entry.changes.forEach(change => {
        const messages = change.value.messages;
        if (messages) {
          messages.forEach(message => {
            console.log('Received message:', message.text?.body);
            // Handle the message here
          });
        }
      });
    });
    res.sendStatus(200);
  } else {
    res.sendStatus(404);
  }
});

Return a 200 OK response immediately — if your webhook does not respond within 5 seconds, Meta will retry the event. Process message handling asynchronously.

Step 3: Register Your Production Phone Number

Once your test environment is working, add your real phone number to your WABA through the Meta Business Manager or the Embedded Signup API. Verify it with the OTP sent to the number.

Retrieve your phone number ID from the Meta app dashboard — this is the identifier used in API calls, not the phone number itself.

Step 4: Obtain an Access Token

API requests to the WhatsApp Cloud API are authenticated with access tokens. For production use, create a System User in your Meta Business Manager and assign it to your WABA with appropriate permissions (WhatsApp Business Messaging). Generate a permanent System User token — this does not expire, unlike user access tokens.

Store the token as an environment variable. Never hardcode it into your application or commit it to version control.

Step 5: Send a Template Message

With your access token and phone number ID, you can send your first message. Template messages are required for business-initiated conversations:

const axios = require('axios');

const phoneNumberId = process.env.WHATSAPP_PHONE_NUMBER_ID;
const accessToken = process.env.WHATSAPP_ACCESS_TOKEN;

async function sendTemplateMessage(recipientPhone, templateName, variables) {
  const response = await axios.post(
    https://graph.facebook.com/v19.0/${phoneNumberId}/messages,
    {
      messaging_product: 'whatsapp',
      to: recipientPhone,
      type: 'template',
      template: {
        name: templateName,
        language: { code: 'en_US' },
        components: [
          {
            type: 'body',
            parameters: variables.map(v => ({ type: 'text', text: v }))
          }
        ]
      }
    },
    {
      headers: {
        Authorization: Bearer ${accessToken},
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Send an order update to a customer
sendTemplateMessage('447911123456', 'order_dispatched', [
  'Sarah', 'ORD-8821', 'tomorrow by 5 PM', 'https://track.example.com/8821'
]);

Recipient phone numbers must be in international format with country code, no plus sign: 447911123456 not +44 7911 123456.

Step 6: Send a Session Message

When a customer has messaged you within the last 24 hours, you can send a free-form session message without a template:

async function sendTextMessage(recipientPhone, text) {
  const response = await axios.post(
    https://graph.facebook.com/v19.0/${phoneNumberId}/messages,
    {
      messaging_product: 'whatsapp',
      to: recipientPhone,
      type: 'text',
      text: { body: text }
    },
    {
      headers: {
        Authorization: Bearer ${accessToken},
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

Step 7: Handle Delivery and Read Receipts

Delivery and read events arrive at your webhook as status updates. Parse them to track message lifecycle:

const statuses = change.value.statuses;
if (statuses) {
  statuses.forEach(status => {
    console.log(Message ${status.id} status: ${status.status});
    // status.status: 'sent', 'delivered', 'read', or 'failed'
  });
}

Store these status events in your database against the message ID to power delivery analytics and trigger follow-up flows when a message is read or fails.

Common Integration Issues and Fixes

Phone number already registered. If you get an error saying the number is already in use, the number is still registered on the WhatsApp consumer or Business App. Delete the account from WhatsApp on the device first, then retry registration.

Webhook not receiving events. Confirm your webhook URL is publicly accessible (not localhost without a tunnel), returns 200 for the verification GET request, and that you have subscribed to the messages webhook field in the Meta app dashboard.

Template rejected. Review the rejection reason in the template manager. Common fixes: replace vague variables with descriptive placeholder names in the sample content, remove superlatives from marketing templates, ensure the template category matches the actual content.

Messages not delivering. Check the recipient number format (international, no plus, no spaces). Verify the contact has not blocked your number. Check your WhatsApp quality rating in the Meta Business Manager — a red or yellow rating can restrict delivery.

Messaging limit reached. New accounts start at 1,000 unique contacts per day. If you hit this limit, the API returns an error. Tier upgrades happen automatically as you build a quality messaging history — typically 7 consecutive days at 80% of your current limit with a good quality rating.

Testing Your Integration End to End

Before going live, run through this test checklist:

1. Send a template message to your personal number — confirm it arrives and variables are populated correctly
2. Reply from your personal number — confirm the reply arrives at your webhook
3. Send a session message in response — confirm it delivers
4. Test an opt-out: reply "STOP" and confirm your system records the opt-out and suppresses future sends to that number
5. Check delivery receipts are arriving and being stored correctly
6. Verify your error handling: send to an invalid number and confirm your application handles the error gracefully without crashing

Scale and Quality Considerations

A working integration is the start, not the finish. Two factors determine whether your integration stays healthy at scale:

Quality rating. Meta monitors how recipients respond to your messages. High block rates, spam reports, or opt-outs drag your quality rating down, which restricts your messaging volume and can lead to account suspension. Send only to contacts who have explicitly opted in, make opting out easy, and prioritise message relevance over broadcast frequency.

Conversation volume tracking. The WhatsApp API charges per conversation — a 24-hour window per contact, per business-initiated exchange. Track your conversation volume to avoid unexpected costs as your integration scales. Greenbubble's pricing page breaks down the full cost model including Meta's conversation fees.

Build on Top of Your Integration

Once your base integration is working, the natural extensions are:

• WhatsApp chatbot flows: Automated response trees for inbound messages, built on top of the session messaging and interactive message types
• Bulk broadcast campaigns: Scheduled template message sends to opted-in contact segments
• CRM integration: Sync contact data and conversation history between WhatsApp and your CRM so agents have full context
• Abandoned cart recovery: Trigger template messages when a customer leaves your checkout without completing a purchase

Each of these builds directly on the integration foundation covered in this tutorial.

Get Started with Greenbubble

Whether you are building a direct integration or want a no-code path to the same capabilities, Greenbubble provides the infrastructure, tools, and support to make the WhatsApp Business API work for your business.

The no-code chatbot builder handles automated flows without any coding. The shared team inbox gives your agents a professional interface for managing conversations. The bulk broadcast tool handles campaigns, segmentation, and analytics in one place. And as an official WhatsApp Business Solution Provider, Greenbubble manages the API infrastructure so your team can focus on the customer experience rather than the plumbing underneath it.

View plans and get started — your WhatsApp Business API number can be live within the hour.