WhatsApp Business API Setup

Enterprise messaging via Meta Business API

Overview

Meta Business Account Required

This integration requires a Meta Business account and is designed for the WhatsApp Business API only. Consumer WhatsApp or WhatsApp Business App accounts cannot be used with this integration.

The WhatsApp Business API integration enables SingularCore to send and receive messages through WhatsApp using Meta's official Business API. This is designed for enterprise use cases and requires proper business verification.

Difficulty

Advanced

Setup Time

1-2 hours

Notification Tiers

Normal, High, Urgent

Prerequisites

Meta Business account (business.meta.com)
Business verification completed
Valid phone number (not already on WhatsApp)
HTTPS webhook endpoint

Step-by-Step Setup

Create Meta Business Account

Go to business.meta.com
Click "Create Account" and complete registration
Verify your business email address
Complete business verification (may take 24-48 hours)
Note your Business ID from Settings

Set Up WhatsApp Business Account

In Meta Business Manager, go to "Accounts" → "WhatsApp Accounts"
Click "Add WhatsApp Business Account"
Choose "Create a new WhatsApp Business Account"
Enter a display name for your WhatsApp Business Profile
Add a phone number (must not be on WhatsApp already)
Verify the phone number via SMS or voice call

Get API Credentials

Go to developers.facebook.com and select your app
Navigate to "WhatsApp" → "Get Started"
Copy the Phone Number ID
Copy the WhatsApp Business Account ID
Go to "App Dashboard" → "WhatsApp" → "API Setup"
Generate a Permanent Access Token with whatsapp_business_messaging permission

Configure Webhook

In Meta Business Manager:

Go to your WhatsApp Business Account → Configuration
Click "Edit" under Webhooks
Enter your webhook URL: https://your-domain.com/webhook/whatsapp
Enter a verification token (create a secure random string)
Subscribe to messages events
Click "Verify and Save"

Required: Your webhook endpoint must respond to the verification challenge with the hub.challenge parameter.

Configure Bot

Edit config/comms.json:

{
  "whatsapp": {
    "enabled": true,
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765",
    "access_token": "EAAB...",
    "webhook_secret": "your-webhook-verification-token",
    "allowed_phone_numbers": ["+1234567890", "+0987654321"],
    "api_version": "v17.0"
  }
}

Supported Commands

Command	Description	Tier
status	System health check	0
skills	List available skills	0
dream	View last dream summary	0
approve <id>	Approve pending action	1+
reject <id>	Reject pending action	1+
(text)	Submit as goal	1+

Troubleshooting

Webhook Not Verifying

Ensure webhook endpoint is HTTPS
Check webhook returns hub.challenge in response
Verify webhook_secret matches in config and Meta
Check server logs for verification requests

Messages Not Sending

Verify access token has not expired
Check phone_number_id is correct
Ensure phone number is registered and verified
Review Meta Business account for policy violations

Rate Limiting

WhatsApp Business API has rate limits per phone number
Monitor API usage in Meta Business Manager
Implement retry logic with exponential backoff

Need More Details?

View Meta's official WhatsApp Business API documentation for complete API reference, rate limits, and best practices.

Meta WhatsApp Business API Docs

Documentation Menu

Back to Channels