📱 WhatsApp Cloud API

WhatsApp is connected via Meta's Cloud API — the official, free-tier-available API that lets you send and receive WhatsApp messages from your own server. No third-party BSP (Business Solution Provider) is required.

---

Prerequisites

1. A Meta Developer account at developers.facebook.com
2. A Meta Business Account (a.k.a. Business Manager)
3. A phone number for WhatsApp that is not already registered on personal WhatsApp (you can use a SIM, a virtual number, or a landline)

---

Setup Steps

1. Create a Meta App

1. Go to developers.facebook.com/apps
2. Click Create App
3. Choose Business type
4. Fill in a name and connect your Business Account

2. Add the WhatsApp Product

1. In your app's dashboard, scroll to Add Products to Your App
2. Click Set Up on WhatsApp
3. Select your Business Account

3. Get Your Credentials

Navigate to WhatsApp → API Setup in your app dashboard:

Credential	Where to Find It
Phone Number ID	Listed under "From" section — a numeric ID like 123456789012345
Access Token	The temporary token shown on this page. For production, generate a permanent token via System Users.
App Secret	App Dashboard → Settings → Basic → App Secret
Verify Token	A string you make up yourself — any random string, e.g. my_secret_verify_token_2024

4. Add the Channel in PulseHub

1. Go to Channels → Add Channel
2. Select WhatsApp
3. Fill in all four fields
4. Click Save Channel
5. Copy the Webhook URL shown on the channel card

5. Configure the Webhook in Meta

1. In your Meta app, go to WhatsApp → Configuration
2. Click Edit next to the Webhook section
3. Callback URL: paste your PulseHub webhook URL
4. Verify Token: enter the same string you put in PulseHub
5. Click Verify and Save

Meta will make a GET request to your webhook URL with ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... PulseHub checks the verify token and echoes back the challenge.

6. Under Webhook Fields, subscribe to: messages

6. Test

Send a WhatsApp message to your business number. It should appear as a new conversation in PulseHub's inbox within seconds.

---

Signature Verification

Meta includes an X-Hub-Signature-256 header on every webhook:

X-Hub-Signature-256: sha256=abc123...

PulseHub verifies it using HMAC-SHA256 with your App Secret. If verification fails, the webhook returns 401 Signature mismatch.

---

Sending Messages

When an agent sends a reply from the inbox, PulseHub calls the WhatsApp Cloud API:

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Your reply here"}
}

---

Production Access

The default Meta app is in Development mode — it can only message numbers added as test numbers. To go live:

1. Complete the Business Verification in Meta Business Manager
2. Submit your WhatsApp use case for Meta's review
3. Once approved, your app gains access to message all WhatsApp users

---

Common Issues

Symptom	Likely Cause
Verification fails during webhook setup	verify_token in PulseHub doesn't match what you entered in Meta
Signature mismatch error in logs	Wrong app_secret — copy it from App Settings → Basic, not from API Setup
Messages not arriving	Webhook field messages not subscribed in Meta dashboard
Invalid phone number when sending	Number format must be E.164 without + (e.g. 15551234567)
App in Development mode error	Only verified test numbers can receive messages in dev mode