MANUAL

What is WhatsApp Enterprise?

WhatsApp Enterprise (Meta Business API) is Meta/Facebook's OFFICIAL API for integrating WhatsApp into enterprise applications. Unlike unofficial solutions like Baileys, this API:

• Has official Meta support
• Guarantees 99.9% availability (SLA)
• No risk of ban for automation
• Allows mass messaging with approved templates

Difference with Baileys

When to use Meta Enterprise?

• You have a legally constituted business
• You need 24/7 customer support
• You want to send mass notifications/campaigns
• The per-message cost is viable for your business

Business Requirements

• Legally constituted company
• Active company website
• Published privacy policy
• Dedicated phone number (not used for personal WhatsApp)

Technical Requirements

• Server with public IP
• Valid SSL certificate (HTTPS required)
• Port 7071 accessible from the Internet
• Fararoni Core installed and running
• Java 25+ with --enable-preview

Required Accounts

• Personal Facebook account (administrator)
• Meta for Developers account
• WhatsApp Business Account (created during the process)

Channel Encryption

# Production (recommended for WhatsApp Enterprise)
export FARARONI_CHANNELS_ENCRYPTION_KEY="$(openssl rand -base64 32)"
export FARARONI_ENV=production
java --enable-preview -jar fararoni-core-1.0.0.jar --server

# Local development
export FARARONI_DEV_MODE=true
# Key is auto-generated

Step 3.1: Create App in Meta for Developers

1. Go to https://developers.facebook.com
2. Click "My Apps" → "Create App"
3. Select type: "Business"
4. Name: "Fararoni WhatsApp" (or your company name)
5. Click "Create App"

Step 3.2: Add WhatsApp to the App

1. In the Dashboard, find "WhatsApp"
2. Click "Set Up"
3. Meta will guide you to create a WhatsApp Business Account

Step 3.3: Verify Your Business

1. Go to Meta Business Suite → Settings → Business Info
2. Complete: legal name, address, website, verification documents
3. Wait for approval (1-5 business days)

Step 3.4: Register Phone Number

1. In WhatsApp → API Setup → "Add Phone Number"
2. Enter the dedicated number
3. Verify via SMS or call
4. Save the Phone Number ID

Step 3.5: Permanent Access Token

1. Business Settings → Users → System Users
2. Click "Add" → Name: "Fararoni API"
3. Assign permissions: whatsapp_business_messaging, whatsapp_business_management
4. Generate Token

System User tokens don't expire. Normal user tokens expire in 60 days.

Step 3.6: Configure Webhook

1. In WhatsApp → Configuration → Webhook
2. Callback URL: https://your-server.com:7071/gateway/v1/meta/webhook
3. Verify Token: A secret string (e.g.: my_secret_token_123)
4. Click "Verify and Save"

Step 3.7: Subscribe to Events

In "Webhook fields", subscribe to: messages (required). Optional: message_template_status_update.

Step 4.1: Environment Variables

# WhatsApp Enterprise - Meta Business API
export META_VERIFY_TOKEN="my_secret_token_123"
export META_ACCESS_TOKEN="EAAGm0PX4ZCps..."
export META_PHONE_ID="123456789012345"

source ~/.bashrc  # or ~/.zshrc

Step 4.2: Edit modules.yml

Location: ~/.fararoni/config/modules.yml

gateway:
  rest:
    enabled: true
    port: 7071

  meta:
    enabled: true
    verify_token: "env:META_VERIFY_TOKEN"
    access_token: "env:META_ACCESS_TOKEN"
    phone_id: "env:META_PHONE_ID"
    api_version: "v18.0"

channels:
  whatsapp:
    enabled: false  # Disable Baileys

  whatsapp_meta:
    enabled: true
    trust_level: SECURE_ENTERPRISE
    egress_adapter: "meta_enterprise"
    capabilities:
      - text
      - template
    timeout_ms: 10000
    retry_count: 3

Step 4.3: Restart Fararoni

pkill -f fararoni-core
cd fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Verify Startup Logs

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071
[META-ENTERPRISE] Meta webhook endpoint registered: /gateway/v1/meta/webhook
[META-EGRESS] Initialized for phone: 123456789012345

Automatic Verification

When you configure the webhook in Meta, it sends a GET request:

GET /gateway/v1/meta/webhook?hub.mode=subscribe&hub.challenge=1234567890&hub.verify_token=my_secret_token_123

Fararoni must respond with the hub.challenge number.

Manual Verification

curl "https://your-server.com:7071/gateway/v1/meta/webhook?hub.mode=subscribe&hub.challenge=test123&hub.verify_token=my_secret_token_123"

Expected response: test123

Send Test Message (from Meta)

1. In Meta for Developers → WhatsApp → API Setup
2. In "Send and receive messages", there's a Meta test number
3. Add your personal number as a test recipient
4. Send a test message

Receive Message in Fararoni

From your personal WhatsApp, send a message to the Enterprise number. Verify in logs:

[META-WEBHOOK] Received message from: 5212291234567
[OmniChannel] Processing message: "Hello"
[OmniChannel] Response sent to: 5212291234567

Error: "Webhook verification failed"

1. Verify META_VERIFY_TOKEN matches exactly
2. Verify port 7071 is accessible from the Internet
3. Verify SSL certificate

Error: "Invalid OAuth access token"

Expired or incorrect token. Regenerate in Meta for Developers, update META_ACCESS_TOKEN and restart.

Error: "Phone number not registered"

The Phone ID doesn't match the verified number. Copy the correct one from Meta for Developers → WhatsApp → Phone Numbers.

Messages don't reach Fararoni

1. Webhook is subscribed to messages
2. Firewall allows traffic to port 7071
3. Server has valid SSL certificate

tail -f ~/.fararoni/logs/fararoni.log | grep META

Bot doesn't respond

Verify: message reaches the bus (agency.input.whatsapp), OmniChannelRouter processes, egress works ([META-EGRESS]).

Meta Pricing Model (2026)

Meta charges per conversation, not per individual message:

24-Hour Window

If the user initiates the conversation, you have 24 hours to respond FREE. After 24 hours, you can only send approved templates (with cost).

Templates (Mass Messages)

1. Create template in Meta Business → WhatsApp → Message Templates
2. Wait for approval (1-24 hours)
3. Use from Fararoni:

metaAdapter.sendTemplate("5212291234567", "welcome_message", "en");

Billing

Meta invoices monthly. Payment method required (credit card). You can configure spend alerts in Meta Business Suite.

Implementation Checklist

PRE-REQUISITES
[ ] Legally constituted company
[ ] Website with privacy policy
[ ] Dedicated phone number
[ ] Server with HTTPS and port 7071 open

META BUSINESS
[ ] App created in Meta for Developers
[ ] WhatsApp Business Account created
[ ] Business verified
[ ] Phone number registered
[ ] System User token generated
[ ] Webhook configured and verified
[ ] Subscribed to "messages" event

FARARÓNI
[ ] Environment variables configured
[ ] modules.yml updated
[ ] gateway.meta.enabled: true
[ ] channels.whatsapp_meta.enabled: true
[ ] Fararoni restarted

TESTING
[ ] Webhook verification successful
[ ] Test message received
[ ] Response sent correctly

Useful Commands

# View real-time logs
tail -f ~/.fararoni/logs/fararoni.log | grep -E "(META|WHATSAPP)"

# Verify gateway health
curl http://localhost:7071/gateway/v1/health

# View environment variables
echo $META_ACCESS_TOKEN | head -c 20
echo $META_PHONE_ID
echo $META_VERIFY_TOKEN

Author: Fararoni Team | Version: 1.0