WhatsApp Setup

Fair warning: WhatsApp is the hardest channel to set up. Telegram takes five minutes. WhatsApp takes an afternoon, maybe longer if you hit snags with Meta's approval process.

If you're just getting started with Moltbot, do Telegram first. Seriously. Come back to WhatsApp once you know everything works.

Still here? Alright, let's do it.

Why WhatsApp Is Harder

Telegram lets anyone create a bot in 30 seconds with BotFather. WhatsApp doesn't work like that.

WhatsApp requires you to go through the WhatsApp Business API, which means:

• A Meta Business account
• A verified business phone number
• API access through Meta's Cloud API or a third-party provider
• Approval that can take hours or days

There's no "@BotFather for WhatsApp." It's a whole process.

Option 1: Meta Cloud API (Official)

This is the official route. Free tier available with limitations.

Step 1: Create a Meta Business Account

Go to business.facebook.com and create an account if you don't have one. You'll need a Facebook account too. Yeah.

Step 2: Set Up a WhatsApp Business App

1. Go to developers.facebook.com
2. Create a new App → select "Business" type
3. Add the WhatsApp product to your app
4. You'll get a temporary access token and a test phone number

The test phone number lets you send messages to up to 5 verified numbers. Good enough for testing.

Step 3: Get a Permanent Token

The temporary token expires in 24 hours. For production use, generate a System User Token:

1. Go to Business Settings → System Users
2. Create a system user with admin access
3. Generate a token with whatsapp_business_messaging permission

Step 4: Configure Moltbot

# ~/.moltbot/config.yaml
channels:
  whatsapp:
    provider: meta
    phoneNumberId: "YOUR_PHONE_NUMBER_ID"
    accessToken: "YOUR_ACCESS_TOKEN"
    verifyToken: "any-random-string-you-make-up"
    webhookPort: 8444

Or use environment variables:

export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
export WHATSAPP_ACCESS_TOKEN=your_access_token
export WHATSAPP_VERIFY_TOKEN=my_secret_verify_string

Step 5: Set Up the Webhook

Meta needs a public HTTPS endpoint to send messages to. You'll need to:

1. Expose Moltbot's webhook port (8444 by default) to the internet
2. Use HTTPS (Cloudflare Tunnel works great here)
3. In the Meta Developer Console, set your webhook URL to https://your-domain.com/whatsapp/webhook
4. Enter the same verifyToken you put in your config

When you click "Verify and Save," Meta sends a challenge request. Moltbot handles this automatically if it's running.

Step 6: Start and Pair

moltbot start

Send a message from your WhatsApp to the bot's number. You'll see a pairing code in your terminal, just like with Telegram.

moltbot pairing approve whatsapp ABCD-1234

Option 2: Third-Party Bridges

If dealing with Meta's API sounds like too much, some people use third-party bridges that connect to WhatsApp Web. These are unofficial and can break when WhatsApp updates their protocol.

Popular options:

• Baileys — open-source WhatsApp Web API library
• whatsapp-web.js — another open-source option
• Evolution API — self-hosted WhatsApp API

Moltbot supports these through community plugins. Check the GitHub discussions for current recommendations. The landscape changes fast.

WARNING

Third-party bridges violate WhatsApp's Terms of Service. Your number could get banned. Use at your own risk. For personal use it's usually fine, but don't say we didn't warn you.

Limitations

WhatsApp has some annoying limitations compared to Telegram:

• 24-hour messaging window: After someone messages you, you have 24 hours to respond freely. After that, you can only send pre-approved template messages. This matters for proactive messaging.
• No inline formatting: WhatsApp supports bold and italic but not code blocks or most Markdown. Moltbot does its best to format responses nicely, but it's not as pretty as Telegram.
• Rate limits: Meta's free tier is limited. You'll hit walls if you're chatting a lot.
• Media handling: Sending and receiving images works, but it goes through Meta's CDN. Files are temporary.

Group Chats

Same warning as Telegram, but even more important here: don't add your bot to WhatsApp groups unless you really know what you're doing. WhatsApp groups tend to be bigger, noisier, and harder to control. Every message in the group gets processed, which burns through your API quota fast.

If you must use groups, set strict policies:

channels:
  whatsapp:
    groupPolicy: "mention-only"

Troubleshooting

Webhook verification fails

• Make sure Moltbot is running before you click "Verify" in Meta's console
• Check that your verifyToken matches exactly
• Confirm your HTTPS endpoint is reachable from the internet

Messages aren't arriving

• Check Meta's Developer Console for webhook delivery status
• Look at moltbot logs for incoming requests
• Make sure you've subscribed to the messages webhook field

Bot responds but WhatsApp shows "waiting for this message"

End-to-end encryption issue. Make sure you're using the Cloud API, not trying to decrypt E2E messages yourself.

Token expired

If you're using the temporary test token, it expires every 24 hours. Set up a permanent System User Token (Step 3 above).

What's Next

• Telegram — if you haven't tried the easier option yet
• Security — especially important with WhatsApp's token setup
• Proactive Messages — note the 24-hour window limitation