WhatsApp Channel

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.

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

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

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.

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

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

---

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.
• Outbound templates — Your agent can proactively send pre-approved template messages to contacts, even after the 24-hour window. See Template Messages below.

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

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

---

Template Messages (Outbound)

Your agent can proactively send messages to WhatsApp contacts using pre-approved Message Templates. This is how you reach out to customers — whether it's sending appointment confirmations, order updates, follow-up messages, or marketing campaigns.

Why Templates?

WhatsApp has a strict 24-hour messaging window. After a contact messages your agent, you can reply freely for 24 hours. But once that window closes, the only way to reach out is through a pre-approved template.

Templates are reviewed and approved by Meta before they can be used. This ensures quality and prevents spam — but it also means templates are the key to proactive outbound communication.

Template Categories

Meta organizes templates into categories, each with different pricing and approval criteria:

Setting Up Templates

1. Create Templates in Meta

1. Go to Meta Business Suite → Message Templates
2. Click Create Template
3. Choose a category, name, and language
4. Write your template body — use placeholders like {{customer_name}} or {{order_id}} for dynamic content
5. Submit for review — Meta typically approves templates within minutes to a few hours

2. Sync Templates into Communa

Once your templates are approved in Meta:

1. Go to your agent → Settings tab → scroll to the WhatsApp section
2. Click Sync from Meta — this pulls all your approved templates
3. You'll see each template listed with its name, category, and body text

3. Configure Each Template

Click on a template to expand its configuration:

• Enable/Disable toggle — Only enabled templates are available to the AI
• "When should the AI use this template?" — Write a clear description of when this template should be sent. The AI reads this to decide which template fits the situation.
  • Good: "Use to confirm an appointment with a customer, including date and time"
  • Bad: "Appointment template" (too vague)
• Parameter Labels — The name the AI sees for each placeholder. Keep these descriptive (e.g., customer_name, appointment_date)
• AI Guidance — Additional context for each parameter to help the AI fill in the right value (e.g., "The customer's full name as it appears in the conversation")

4. Save Settings

Click Save Settings at the bottom. Your templates are now live.

How the AI Uses Templates

Once configured, the AI automatically decides when to send a template based on the context of the conversation:

1. The AI evaluates the situation and matches it to a template's description
2. It fills in the parameters using information from the conversation
3. The template message is sent to the contact on WhatsApp
4. This works even after the 24-hour window has expired — that's the whole point

You don't need to tell the AI "send a template" — it understands when a template is appropriate based on the descriptions you wrote. Of course, you can also instruct it to send specific templates in your agent's custom instructions.

Template Tips

• Keep descriptions specific — The better your template descriptions, the more accurately the AI will choose the right template at the right time
• Resync after changes — If you edit or add templates in Meta, click "Sync from Meta" again to pull the latest versions
• Test with utility templates first — They're cheaper and approved faster. Great for getting the flow right before adding marketing templates.
• Check parameter labels — After syncing, review that the parameter labels make sense. The AI uses these labels to understand what data each placeholder expects.
• Template costs — Meta charges per template message sent (rates vary by category and country). Check Meta's pricing page for current rates.

---

Troubleshooting

Messages Not Arriving

"Invalid Token" Error When Connecting

Template Messages Not Sending

"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?

• Channels Overview — Shared channel features, attachments, auto-wake, and connection management
• Telegram Channel — Connect your agent via Telegram
• Voice Channel — Connect your agent via phone calls
• Chat & Computer — The dashboard workspace for direct agent interaction