Skip to main content

WhatsApp Business API

WhatsApp Business Integration Guide

Overview

This guide explains how to connect Bridged with WhatsApp Business API (also known as WhatsApp Cloud API) to enable messaging, broadcasting, and conversational engagement. The integration supports sending and receiving WhatsApp messages, managing conversation threads, and syncing message status updates.

WhatsApp Business API is Meta's official interface for businesses to send and receive WhatsApp messages at scale — powering bulk campaigns, automated conversations, order notifications, and customer support. Meta now hosts the Cloud API directly, eliminating the need for third-party Business Solution Providers (BSPs) or on-premise servers.

Prerequisites

Before starting, ensure you have:

  • A Facebook Business Manager account (verified)

  • A Meta Developer account (created at developers.facebook.com)

  • A dedicated business phone number that can receive SMS or voice calls for verification

  • Business verification documents (registration certificate, tax ID, or EIN)

  • A company website where your business name is clearly visible

Note for testing: Meta automatically provides a test phone number when you add the WhatsApp product to a test app. No separate Business Manager or paid phone number is required for development and testing.

Connection Methods

Bridged supports two authentication methods for WhatsApp Business API:

Method

Best for

Setup complexity

API Key (Access Token - Preferred)

Production integrations, server-to-server, automation

Medium

OAuth 2.0

Multi-tenant apps, user-specific access

Medium

Recommendation: API Key (Permanent Access Token) is the preferred method for production integrations. OAuth 2.0 is supported as an alternative. For testing, a temporary access token can be used.

Step 1: Create a Meta App and Add WhatsApp Product

  1. Go to Meta for Developers and log in with your Facebook account.

  2. Click Create App.

  3. Select Business as the app type.

  4. Fill in the required information:

    • App Name: Bridged WhatsApp Integration

    • Contact Email: Your business email

  5. Click Create App (you may be prompted to enter your password).

  6. On the app dashboard, click Add Product and select WhatsApp.

  7. Click Set Up next to the WhatsApp product.

Step 2: Configure WhatsApp Business Account

Option A: Production Setup

  1. In the WhatsApp product section, click Continue.

  2. Select or create a Business Portfolio (your business account).

  3. Register a phone number:

    • Enter your dedicated business phone number

    • Verify the number via SMS or voice call

  4. Complete your business profile:

    • Company name and description

    • Business hours (use U.S. time zones for consistency)

    • Website URL and contact email

    • Profile picture or logo

Option B: Testing Setup (No Phone Number Required)

Meta automatically provides a test phone number when you add the WhatsApp product to a test app. You can use this for development and testing without registering a real number.

Step 3: Generate Access Token

Bridged supports both temporary and permanent access tokens.

For Testing (Temporary Token)

  1. In your Meta app, navigate to WhatsApp → API Setup.

  2. Under the Send messages with the API section, find your temporary access token.

  3. Copy the token for use in Bridged.

For Production (Permanent System User Token)

  1. Go to Business Manager → Users → System Users.

  2. Click Add New System User.

  3. Create a system user with Admin permissions.

  4. Click Add Assets and assign the system user to your WhatsApp Business Account.

  5. Under Permissions, select the required scopes:

    • whatsapp_business_messaging - Send and receive messages

    • whatsapp_business_management - Manage phone numbers and templates

  6. Generate an access token with no expiration date.

  7. Copy the token immediately — you won't be able to see it again.

Step 4: Configure Webhook for Real-time Messaging

WhatsApp sends incoming messages and status updates to your webhook URL. Bridged provides a webhook endpoint to receive these events.

Step 4.1: Get Your Webhook Credentials

  1. Log in to your Bridged dashboard.

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media.

  3. Click WhatsApp Business → Webhook Settings.

  4. Copy your:

    • Callback URL (e.g., https://gateway.bridged.media/webhooks/whatsapp)

    • Verify Token (a secret string you set in Bridged)

Step 4.2: Configure Webhook in Meta

  1. In your Meta app, go to WhatsApp → Configuration.

  2. Under the Webhook section, click Edit or Add Webhook.

  3. Set the following:

    • Callback URL: Paste the URL from Bridged

    • Verify Token: Paste the verify token from Bridged

  4. Click Verify and Save.

    • Meta will send a GET request to your URL. Bridged automatically responds with the challenge token to complete verification.

Step 4.3: Subscribe to Webhook Fields

  1. After verification, scroll to Webhook Fields.

  2. Subscribe to the following events:

    • messages (required) - Receives incoming messages from users

    • message_status (optional) - Receives delivery and read status updates

  3. Click Subscribe.

Step 5: Configure Bridged to Connect to WhatsApp

  1. Log in to your Bridged dashboard.

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media.

  3. Click WhatsApp Business → Connect Account.

  4. Choose your authentication method:

Option A: API Key (Access Token) - Preferred

Enter the following credentials:

Field

Description

Where to find

Phone Number ID

Unique ID of your WhatsApp business phone number

WhatsApp → API Setup in Meta app

Access Token

Permanent or temporary access token

Generated in Step 3

App Secret

Your Meta app's secret key

App Settings → Basic → App Secret

API Version

Graph API version (default: v21.0)

Use latest version from Meta docs

Business Account ID

Your WhatsApp Business Account ID (optional)

WhatsApp → API Setup

Option B: OAuth 2.0

  1. Enter your App ID and App Secret from your Meta app.

  2. Enter your Phone Number ID.

  3. Click Connect with Facebook.

  4. You will be redirected to Facebook to log in and grant permissions.

  5. After authorization, you will be redirected back to Bridged.

Step 6: Configure Sync Settings

Once connected, configure the following:

Setting

Options

Description

Message direction

Inbound only, Outbound only, Both

Define which messages to sync

Conversation tracking

Enabled, Disabled

Track 24-hour conversation windows

Webhook events

Messages, Statuses, Both

Choose which events to receive

Template management

Auto-sync, Manual

Sync approved message templates

Bulk sync limit: Each bulk operation is limited to 50 records per request. For high-volume messaging, queue messages in batches.

Step 7: Create and Manage Message Templates

For outbound marketing, utility, and authentication messages, you must use approved templates.

Template Categories

Category

Initiated by

Use cases

Approval time

Marketing

Business

Promotions, offers, announcements

24-48 hours

Utility

Business

Order confirmations, shipping updates

4-8 hours

Authentication

Business

OTP codes, login verification

2-4 hours

Service

Customer

Customer-initiated conversations

Not required

Creating a Template

  1. In your Meta app, go to WhatsApp → Message Templates.

  2. Click Create Message Template.

  3. Select a category (Marketing, Utility, or Authentication).

  4. Enter the template content:

    • Header (optional): Text, image, or video

    • Body (required): Main message content with optional variables ({{1}}, {{2}})

    • Footer (optional)

    • Buttons (optional): Quick reply or call to action

  5. Submit for approval.

Note: Only approved templates can be used for outbound messages. Service category messages (customer-initiated) do not require templates.

Step 8: Test the Integration

  1. In Bridged, go to Integrations → WhatsApp Business → Test Connection.

  2. Send a test message using the API:

    • Use the To field in Meta's API Setup to send a message to your test number

  3. Send a message from your phone to your WhatsApp Business number:

    • Your webhook should receive the POST request

  4. Verify message delivery and status updates in Bridged.

Using the WhatsApp Cloud API for Testing

You can test sending a message directly using the Graph API:

bash

curl -X POST \
  "https://graph.facebook.com/v21.0/YOUR_PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "RECIPIENT_PHONE_NUMBER",
    "type": "text",
    "text": { "body": "Hello from Bridged!" }
  }'

Common Use Cases

Playbook

Direction

Description

Activation

Outbound

Broadcast marketing messages to leads via approved templates

Qualification Agent

Inbound + Outbound

Receive user responses, qualify leads through conversation

Nurture & Conversion

Outbound

Send order confirmations, shipping updates, appointment reminders

Customer Support

Inbound + Outbound

Multi-agent inbox for customer service conversations

Rate Limiting & Performance

  • Meta's standard throughput: 80 messages per second (MPS) for Cloud API

  • Rate limits depend on your WhatsApp Business Account tier, not on Bridged

  • Bulk operations: Maximum 50 records per request. Queue messages when sending high volumes

  • For high-volume campaigns (50+ messages/second), contact support for queue optimization

Conversation-Based Pricing

Meta charges based on conversation windows (24-hour messaging sessions):

Conversation Type

Initiator

Free Tier

Marketing

Business

None

Utility

Business

None

Authentication

Business

None

Service

Customer

1,000/month free

Indicative pricing (2026):

  • India: $0.0088 (marketing) / $0.0014 (service)

  • UK/EU: $0.0685 (marketing) / $0.0136 (service)

  • US: $0.0250 (marketing) / $0.0076 (service)

Security & Permissions

  • Bridged supports Access Token (preferred) and OAuth 2.0 authentication

  • Permanent access tokens should be stored securely and rotated periodically

  • Webhook verification uses X-Hub-Signature-256 headers to verify requests are from Meta

  • All API calls are made over TLS 1.2+

  • You can revoke access at any time from Meta Developer Portal → Apps → Your App → Remove

Required Scopes

For full functionality, your access token requires these permissions:

  • whatsapp_business_messaging - Send and receive messages

  • whatsapp_business_management - Manage phone numbers and templates

  • business_management - Access Business Manager assets

Troubleshooting

Issue

Likely cause

Solution

Webhook verification fails

Callback URL or verify token mismatch

Ensure URL and token exactly match Bridged configuration

No incoming messages received

Webhook fields not subscribed

Subscribe to messages field in Meta Configuration

Message send fails

Invalid phone number ID or token

Verify Phone Number ID and Access Token in Meta API Setup

Rate limiting (80 MPS)

Exceeding Meta's throughput

Queue messages or upgrade your WhatsApp Business Account

Template message rejected

Template not approved

Wait for approval or check template category

Authentication error (401)

Expired access token

Generate a new permanent system user token

Webhook not receiving events

Incorrect URL or SSL issue

Verify Callback URL uses HTTPS and is publicly accessible

Support

For integration support, contact your Bridged account manager or email support@bridged.media.