WhatsApp Channel

Connect WhatsApp Business to your agent — Meta setup guide, features, message limits, and troubleshooting.

Tip: Your agent handles WhatsApp messages exactly like dashboard chat — same tools, same skills, same context.

Connecting WhatsApp

WhatsApp integration uses the official Meta WhatsApp Business Cloud API. The setup requires creating a Meta App and configuring a few pieces — it takes about 10–15 minutes the first time, but you only need to do it once.

Before You Start

You'll need:

  • A Facebook account (your personal account is fine)
  • A phone number that can receive an SMS or voice call for verification
  • That phone number must NOT be currently registered with WhatsApp (personal or business). If you want to use your existing number, you must first delete your WhatsApp account on that number. Alternatively, use a new number or Meta's free test number for development.

Info: If you don't have a Meta Business Portfolio yet, one will be created for you automatically during the app creation process.

Step 1: Create a Meta App

  1. Go to developers.facebook.com and log in with your Facebook account
  2. Click My Apps in the top navigation, then Create App
  3. Under "What do you want your app to do?", select Other, then click Next
  4. Select app type: Business — then click Next
  5. Enter an app name (e.g., "My Communa Agent") and your contact email
  6. If prompted, select or create a Business Portfolio (this links your app to your business)
  7. Click Create App

You'll land on the App Dashboard. This is where you'll manage everything.

Step 2: Set Up the WhatsApp Use Case

  1. In the App Dashboard, click Use cases in the left sidebar
  2. Find Connect on WhatsApp and click the Customize button
  3. If prompted to select a Business Portfolio, choose the same one from Step 1
  4. You'll land in the WhatsApp configuration panel — the left submenu shows Quickstart, API Setup, Configuration, and other sub-pages

Step 3: Get Your Phone Number ID

In the WhatsApp configuration panel, click API Setup in the left submenu. You'll see a section called "Send and receive messages".

  1. Under "From", you'll see a dropdown with a test phone number provided by Meta
  2. Below the dropdown, you'll see the Phone Number ID — a numeric string like 100234567890123
  3. Copy this Phone Number ID — you'll need it when connecting in Communa

About test numbers: Meta provides a free test phone number. It works for development, but has limitations: you can only send messages to up to 5 phone numbers that you pre-register in the "To" field on this same page. For production use, you'll add your own business phone number later.

Step 4: Create a System User & Generate a Permanent Access Token

This is the most important step. The temporary token shown on the Getting Started page expires after 24 hours. For a reliable connection, you need a permanent token from a System User.

Create a System User

  1. Open business.facebook.com/settings (Meta Business Settings)
  2. In the left sidebar, navigate to Users → System users
  3. Click Add to create a new system user
  4. Enter a name (e.g., communa-agent) and set the role to Admin
  5. Click Create system user

Assign the WhatsApp App to the System User

  1. Click on the system user you just created
  2. Click Add assets
  3. Select Apps from the asset type
  4. Find and select the app you created in Step 1
  5. Enable Full control (Manage app)
  6. Click Save changes

Generate a Permanent Token

  1. Still on the system user page, click Generate new token
  2. Select the app you created in Step 1
  3. Set token expiration to Never (this creates a permanent token)
  4. Select these permissions (check both):
    • whatsapp_business_messaging — allows sending and receiving messages
    • whatsapp_business_management — allows subscribing to your WhatsApp Business Account for webhook delivery
  5. Click Generate token
  6. Copy the token immediately and save it somewhere safe

⚠️ Important: You will only see this token once. If you close the dialog without copying it, you'll need to generate a new one. The token will look like EAABs... and will be quite long.

Step 5: Get Your WhatsApp Business Account (WABA) ID

The WABA ID is needed so Communa can subscribe to your WhatsApp Business Account for message delivery.

  1. In business.facebook.com/settings, go to Accounts → WhatsApp Accounts in the left sidebar
  2. Click on your WhatsApp Business Account
  3. The WABA ID is a numeric string shown on the page (e.g., 109876543210) — you can also find it in the URL: business.facebook.com/settings/whatsapp-business-accounts/WABA_ID
  4. Copy this WABA ID

Step 6: Connect in Communa

Now you have everything needed. Head to Communa:

  1. Go to your agent → Channels tab
  2. Click Connect Channel → select the WhatsApp tab
  3. Fill in the fields:
    • Access Token — the permanent token from Step 4
    • Phone Number ID — from Step 3
    • WABA ID — from Step 5
    • App Secret (recommended) — found in Meta App Dashboard → App Settings (gear icon at the bottom of the left sidebar) → Basic → App Secret (click "Show" to reveal it). This enables webhook signature verification for security.
  4. Click Connect WhatsApp

Communa will validate your credentials, verify the phone number, and subscribe your app to the WABA. If successful, you'll see the connection as Active.

Webhook URL & Verify Token: After clicking Connect, the setup drawer shows the full Webhook URL and a pre-generated Verify Token — both with copy buttons. You'll need both values in the next step. Copy them before closing the drawer.

Step 7: Configure the Webhook in Meta

This final step tells Meta where to send incoming messages.

  1. Go back to developers.facebook.com → your app
  2. In the left sidebar, click Use cases → find Connect on WhatsApp → click Customize
  3. In the left submenu, click Configuration
  4. Under the Webhook section, click Edit
  5. Enter these values:
    • Callback URL: https://communa.io/api/webhooks/whatsapp — this is always our production URL. You can copy it directly from the setup drawer.
    • Verify token: The verify token shown after connecting in Step 6
  6. Click Verify and save — Meta will send a verification request to your URL, and if the token matches, it will confirm
  7. After verification, scroll down to the Webhook fields table. Find the messages row and click Subscribe in its Subscribe column

⚠️ You must subscribe to the "messages" webhook field. Without this subscription, Meta won't forward incoming messages to your webhook URL, and your agent won't receive any WhatsApp messages. You'll see a list of available fields (like account_alerts, message_template_status_update, messages, etc.) — make sure messages has a checkmark in the Subscribe column.

That's it — your WhatsApp channel is now fully connected and live!

Test Your Connection

  1. Open WhatsApp on your phone
  2. Send a message to the business phone number shown in your Communa connection card
  3. Your agent should wake up and respond

If using the test number: Remember, Meta's test number can only receive messages from the phone numbers you've pre-registered in the Meta App Dashboard → WhatsApp → Getting Started → "To" field. Add your phone number there first.

WhatsApp Features

How WhatsApp Conversations Work

WhatsApp conversations work slightly differently from Telegram:

  • No bot commands — WhatsApp doesn't have a /command system. Just send normal messages.
  • Read receipts — Your agent automatically marks messages as read (blue double-check marks) when they're received.
  • Inline Stop button — Like Telegram, the first response message includes a ⏹ Stop button to cancel the active task.
  • Group chats — If the business number is added to a WhatsApp group, all messages in the group are processed by the agent.

Voice Messages

Send a voice note to your agent and it's automatically transcribed — the agent reads it as regular text and responds naturally.

  • WhatsApp voice notes (OGG/Opus format) are fully supported
  • Language is auto-detected (Hebrew, English, Arabic, and 50+ more)
  • Audio files sent as attachments (.mp3, .m4a, .wav, etc.) are also transcribed
  • Cost: ~$0.003 per minute of audio, billed from your credits

Info: If transcription fails for any reason, the audio file is still delivered as an attachment.

WhatsApp Message Limits

WhatsApp has a 4,096-character limit per message (same as Telegram). Long responses are automatically split into multiple messages at natural paragraph boundaries.

Test Number Limitations

If you're using Meta's free test phone number:

  • You can only send messages to up to 5 pre-registered phone numbers
  • Register recipient numbers in Meta Dashboard → WhatsApp → Getting Started → "To" field
  • The test number has a lower rate limit than production numbers
  • For production use, add and verify your own business phone number in the Meta Dashboard

Troubleshooting

Messages Not Arriving

SymptomLikely CauseFix
Agent never respondsWebhook not configuredComplete Step 7 — set the callback URL and subscribe to "messages"
Agent never respondsApp not subscribed to WABAMake sure you provided the WABA ID when connecting in Communa
Agent never respondsVerify token mismatchDisconnect and reconnect in Communa, then update the verify token in Meta
Agent never respondsUsing test number without registering recipientAdd your phone number in Meta Dashboard → WhatsApp → Getting Started → "To" field

"Invalid Token" Error When Connecting

SymptomLikely CauseFix
Invalid token errorUsing the 24-hour temporary tokenGenerate a permanent token via System User (Step 4)
Invalid token errorToken missing required permissionsRegenerate with both whatsapp_business_messaging and whatsapp_business_management
Invalid token errorPhone Number ID doesn't match the token's appEnsure the Phone Number ID belongs to the same WABA that the system user has access to

"WABA Subscription Failed" Error

This means Communa couldn't subscribe your app to the WhatsApp Business Account:

  • "Access token is invalid or expired" — Your token has expired. Generate a new permanent token (Step 4).
  • "whatsapp_business_management permission required" — Your token is missing a permission. Regenerate it with both permissions checked (Step 4).
  • Wrong WABA ID — Double-check the WABA ID in Business Settings → WhatsApp Accounts.

Webhook Verification Fails in Meta

When you click "Verify and save" in Meta's webhook configuration:

  • The callback URL must be exactly https://communa.io/api/webhooks/whatsapp — do not use localhost or a custom domain
  • Ensure the Verify Token matches exactly — copy it from Communa, don't type it manually
  • Check that the callback URL path is exactly /api/webhooks/whatsapp (no trailing slash)

Tips & Best Practices

  • Always use a permanent token — The temporary token from Meta's Getting Started page expires in 24 hours. Use a System User permanent token for production.
  • Don't forget the webhook — The most common issue is forgetting to configure the webhook URL and subscribe to the "messages" field in Meta's dashboard
  • Keep your App Secret configured — While optional, the App Secret enables webhook signature verification, which protects against spoofed messages
  • Moving to production? — When you're ready to use your own phone number instead of Meta's test number, go to WhatsApp → Getting Started → add a phone number and complete verification
  • Keep messages concise — Add to your agent's custom instructions: "When responding via WhatsApp, keep messages concise and well-formatted for mobile reading"

What's Next?

Previous

Telegram Channel

Next

Queue