ATOM Documentation

← Back to App

WhatsApp Business Integration Setup Guide

Complete setup instructions for Meta WhatsApp Business API on Fly.io.

---

PART 1: Meta Developer Console Setup

Step 1: Create Meta App

  1. Go to Meta for Developers
  2. Click **"Create App"**
  3. Select **"Business"** app type
  4. Enter app name: Atom WhatsApp Integration (or your preference)
  5. Click **"Create App"**

Step 2: Add WhatsApp Product

  1. In your app dashboard, find **"Add Products"** section
  2. Click **"Set up"** under **WhatsApp**
  3. You'll be redirected to WhatsApp configuration

Step 3: Configure WhatsApp

**A. Basic Setup**

  1. Select **"Get Started"** with WhatsApp Cloud API
  2. Select your **Meta Business Account** (or create one)
  3. Enter your business display name and category

**B. Webhook Configuration**

  1. Scroll to **"Webhooks"** section
  2. Click **"Configure"**
  3. **Webhook URL:**
  4. **Verify Token:**
  5. Click **"Verify and Save"**

**C. Subscribe to Webhook Events**

After verification succeeds, subscribe to these events:

  • ✅ **Messages** - Required for receiving messages
  • ✅ **Messaging Postbacks** - Delivery status
  • ✅ **Message Template Status** - Template approval updates

**D. Phone Number Setup**

  1. Go to **"Send & Receive Messages"** section
  2. Add a phone number (or use test number)
  3. Copy the **Phone Number ID** - you'll need this later
  4. Copy the **WhatsApp Business Account ID (WABA ID)**

Step 4: Generate Access Token

  1. In WhatsApp configuration, scroll to **"Access Token"**
  2. Click **"Generate"** or **"Edit"**
  3. Select token expiration (prefer **"Never expires"** for production)
  4. Copy the **Temporary Access Token** (starts with EAA...)
  5. **⚠️ IMPORTANT:** Copy this token NOW - you won't see it again!

Step 5: Get App Credentials

  1. Go to **Settings** → **Basic**
  2. Copy **App ID** (also called Client ID)
  3. Copy **App Secret** (click "Show" to reveal)
  4. Note your **App Secret** - you'll need it for OAuth

Step 6: Configure Embedded Signup (Optional but Recommended)

  1. Go to **WhatsApp** → **Embedded Signup**
  2. Add your domain: app.atomagentos.com
  3. Copy the **Configuration ID**

---

PART 2: Fly.io Configuration

Step 1: Set Secrets on Fly.io

Run these commands to set your WhatsApp credentials:

# App Credentials (for OAuth)
fly secrets set WHATSAPP_APP_ID=your_app_id_here -a atom-saas
fly secrets set WHATSAPP_APP_SECRET=your_app_secret_here -a atom-saas
fly secrets set WHATSAPP_CONFIG_ID=your_config_id_here -a atom-saas

# Webhook Verification Token
fly secrets set WHATSAPP_WEBHOOK_VERIFY_TOKEN=atom_whatsapp_verify_token_2024 -a atom-saas

# Redirect URI (should match Meta dashboard)
fly secrets set WHATSAPP_REDIRECT_URI=https://app.atomagentos.com/api/integrations/whatsapp/callback -a atom-saas

**Example:**

fly secrets set WHATSAPP_APP_ID=123456789012345 -a atom-saas
fly secrets set WHATSAPP_APP_SECRET=abc123def456 -a atom-saas
fly secrets set WHATSAPP_CONFIG_ID=987654321 -a atom-saas

Step 2: Verify Secrets are Set

fly secrets list -a atom-saas | grep WHATSAPP

You should see:

* WHATSAPP_APP_ID                                    	[HASH]	Staged
* WHATSAPP_APP_SECRET                                	[HASH]	Staged
* WHATSAPP_CONFIG_ID                                 	[HASH]	Staged
* WHATSAPP_REDIRECT_URI                              	[HASH]	Staged
* WHATSAPP_WEBHOOK_VERIFY_TOKEN                      	[HASH]	Staged

Step 3: Deploy (if not already deployed)

fly deploy -a atom-saas

---

PART 3: Meta Developer Console - Final Configuration

Step 1: Configure Redirect URI

In your Meta App:

  1. Go to **WhatsApp** → **Configuration**
  2. Find **"Callback URL"** or **"Redirect URI"** setting
  3. Set it to:

Step 2: Configure OAuth (for Embedded Signup)

  1. Go to **Settings** → **Basic**
  2. Under **"App Domlices"**, add: app.atomagentos.com
  3. Under **"Redirect OAuth URIs"**, add:

---

PART 4: Verification & Testing

Test 1: Verify Webhook Endpoint

curl "https://app.atomagentos.com/api/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=atom_whatsapp_verify_token_2024&hub.challenge=TEST123"

**Expected Response:** TEST123 (the challenge string echoed back)

Test 2: Test OAuth Authorization

  1. Visit in your browser:
  2. Should return JSON with authorization_url
  3. Click that URL - should redirect to Meta's OAuth screen

Test 3: Check Connection Status

# After completing OAuth, check status
curl https://app.atomagentos.com/api/integrations/whatsapp/status

**Expected Response:**

{
  "connected": true,
  "phone_number": "+1234567890",
  "business_name": "Your Business Name",
  "connected_at": "2026-04-07T..."
}

Test 4: Send Test Message

# Via SSH into the container
fly ssh console -a atom-saas -C "curl -X POST http://localhost:8000/api/v1/integrations/whatsapp/message -H 'Content-Type: application/json' -d '{\"to\": \"PHONE_NUMBER\", \"message\": \"Test from Atom\"}'"

---

PART 5: Troubleshooting

Issue: Webhook Verification Fails (403 Forbidden)

**Cause:** Verify token mismatch

**Solution:**

  1. Check Meta dashboard has exact token: atom_whatsapp_verify_token_2024
  2. Check Fly secret: fly secrets list -a atom-saas | grep WHATSAPP_WEBHOOK_VERIFY_TOKEN
  3. Both must match exactly

Issue: Webhook Returns 500 Error

**Cause:** Internal server error

**Solution:**

# Check logs
fly logs -a atom-saas -c 100 | grep -i whatsapp

# Check Python health
fly ssh console -a atom-saas -C "curl http://localhost:8000/health"

Issue: OAuth Callback Fails

**Cause:** Redirect URI mismatch

**Solution:**

  1. Meta dashboard: Check Callback URL matches exactly
  2. Fly secret: Check WHATSAPP_REDIRECT_URI
  3. Both must be: https://app.atomagentos.com/api/integrations/whatsapp/callback

Issue: Messages Not Received

**Cause:** Phone number ID not mapped to tenant

**Solution:**

  1. Complete OAuth flow for your tenant
  2. Check phone_number_id is saved in tenant credentials
  3. Webhook uses phone_number_id to resolve tenant

Issue: HTTP 431 Errors

**Cause:** atom-saas-api.fly.dev references (old architecture)

**Solution:**

  1. Verify PYTHON_BACKEND_URL=http://localhost:8000 in fly.toml
  2. Check next.config.mjs doesn't reference atom-saas-api.fly.dev
  3. See SINGLE_APP_ARCHITECTURE.md for details

---

PART 6: Environment Variables Reference

VariableDescriptionExampleRequired
WHATSAPP_APP_IDMeta App ID123456789012345✅ Yes
WHATSAPP_APP_SECRETMeta App Secretabc123def456✅ Yes
WHATSAPP_CONFIG_IDEmbedded Signup Config ID987654321Optional
WHATSAPP_REDIRECT_URIOAuth Callback URLhttps://app.atomagentos.com/api/integrations/whatsapp/callback✅ Yes
WHATSAPP_WEBHOOK_VERIFY_TOKENWebhook verification tokenatom_whatsapp_verify_token_2024✅ Yes

---

PART 7: Meta Dashboard URLs Reference

ResourceURL
Meta for Developershttps://developers.facebook.com
Your Appshttps://developers.facebook.com/apps
WhatsApp Documentationhttps://developers.facebook.com/docs/whatsapp
Webhooks Documentationhttps://developers.facebook.com/docs/whatsapp/cloud-api/webhooks
Embedded Signuphttps://developers.facebook.com/docs/whatsapp/embedded-signup

---

Summary Checklist

Meta Developer Console

  • [ ] Create Business app
  • [ ] Add WhatsApp product
  • [ ] Configure webhook URL: https://app.atomagentos.com/api/v1/webhooks/whatsapp
  • [ ] Set verify token: atom_whatsapp_verify_token_2024
  • [ ] Subscribe to webhook events (Messages, Message Postbacks)
  • [ ] Generate access token (never expires)
  • [ ] Copy App ID, App Secret, Phone Number ID, WABA ID
  • [ ] Configure Embedded Signup (optional)
  • [ ] Add domain and redirect URI

Fly.io

  • [ ] Set WHATSAPP_APP_ID secret
  • [ ] Set WHATSAPP_APP_SECRET secret
  • [ ] Set WHATSAPP_CONFIG_ID secret (if using Embedded Signup)
  • [ ] Set WHATSAPP_WEBHOOK_VERIFY_TOKEN secret
  • [ ] Set WHATSAPP_REDIRECT_URI secret
  • [ ] Deploy app: fly deploy -a atom-saas
  • [ ] Test webhook verification endpoint
  • [ ] Test OAuth authorization flow

Verification

  • [ ] Webhook verification returns challenge
  • [ ] OAuth authorization URL is generated
  • [ ] OAuth callback succeeds
  • [ ] Connection status shows connected
  • [ ] Test message can be sent

---

Last Updated: 2026-04-07

Related Docs: SINGLE_APP_ARCHITECTURE.md