Skip to main content

​
What is WhatsApp Business Integration?

WhatsApp Business Integration lets your IllumiChat assistants respond to WhatsApp messages automatically. When someone messages your WhatsApp Business number, your assistant reads the message, generates a helpful response, and sends it back — all over WhatsApp. Perfect for:
  • Customer support: Let customers message your business number for instant AI-powered help
  • Lead engagement: Capture and respond to inbound leads on the channel they already use
  • After-hours coverage: Provide instant responses even when your team is offline
  • Human handoff: Hand any conversation to a human agent in the Universal Inbox when needed
WhatsApp Business Integration connects through the Meta WhatsApp Cloud API. You can connect with one click using Embedded Signup, or paste your own credentials with Advanced Setup.

​
Getting Started

​
Prerequisites

Before connecting WhatsApp, make sure you have:
  1. An IllumiChat workspace with Admin access
  2. A Meta Business Account
  3. A WhatsApp Business Account (WABA)
  4. A registered phone number for WhatsApp Business
Each WhatsApp phone number can only be connected to one assistant at a time. If the number is already connected elsewhere, disconnect it there first.

​
1. Connect Your WhatsApp Business Number

  1. Go to your assistant’s Settings
  2. Select Channels from the sidebar
  3. Click the WhatsApp card
  4. Review the prerequisites checklist
  5. Click Connect with WhatsApp
  6. Complete the Meta popup — log in to Facebook, choose your WhatsApp Business Account and phone number, and authorize access
IllumiChat will exchange the authorization, discover your WABA and phone number, subscribe the account to webhooks, and store your access token encrypted.
Embedded Signup is the recommended path — it handles token generation and webhook subscription for you. If you don’t see the Connect with WhatsApp button, your workspace is in manual-only mode and you’ll use Advanced Setup below.

​
Advanced Setup (manual credentials)

If you manage your own Meta App, expand Advanced Setup (manual credentials) and provide:
FieldDescription
Phone Number IDThe Cloud API phone number ID for your WhatsApp Business number
WABA IDYour WhatsApp Business Account ID
System User Access TokenA long-lived System User token with WhatsApp permissions
App SecretYour Meta App secret (used to validate incoming webhooks)
Then click Connect Manually. IllumiChat validates the credentials against the Cloud API and stores them encrypted.
With a manual connection, IllumiChat verifies incoming webhooks using your App Secret, so each customer’s own Meta App can deliver events to the same shared webhook URL.

​
2. Configure Webhooks (manual connections)

Embedded Signup subscribes your account to webhooks automatically — there’s nothing extra to do. If you connected manually, configure the webhook in your Meta App Dashboard under the WhatsApp product:
  1. On the WhatsApp channel page, copy the Webhook URL shown in the Webhook Setup card (it ends in /api/channels/webhook/whatsapp)
  2. In your Meta App Dashboard, paste it as the WhatsApp Callback URL
  3. Enter your Verify Token (this must match the META_WEBHOOK_VERIFY_TOKEN configured for your deployment)
  4. Subscribe to the messages webhook field
The webhook is shared across all WhatsApp connections — you don’t need a unique URL per assistant. Incoming events are routed to the right assistant by phone number.

​
3. Configure Messaging Settings

After connecting, fine-tune how conversations are handled from the Messaging Settings card:
OptionDefaultDescription
AI replies to WhatsApp messagesOnWhen off, the AI stops replying on WhatsApp, but conversations still appear in the inbox for manual handling
Match WhatsApp users to existing contactsOffLink incoming messages to contacts with matching phone numbers
Auto-create contacts for new conversationsOffCreate a contact record for new WhatsApp users (requires contact matching)
Max message length4096Maximum characters per message — 1000, 2000, 3000, or 4096; longer responses are split
Use the Enabled toggle at the top of the WhatsApp Integration card to turn the channel on or off without disconnecting. Click Save Changes when you’re done.
Use Test on the connection card at any time to confirm the connection is active and working.

​
4. Test It Out

Send a message to your connected WhatsApp Business number. Within a few seconds, you should receive an AI-generated response.

​
How It Works

When someone sends a message to your WhatsApp Business number:
  1. Meta forwards the message to IllumiChat via the Cloud API webhook
  2. IllumiChat validates the request using the X-Hub-Signature-256 header (against the platform App Secret for Embedded Signup, or your own App Secret for manual connections)
  3. A conversation session is created (or resumed) for that user, keyed to their WhatsApp ID
  4. Your assistant generates a response if AI is enabled for the channel and the conversation
  5. The response is sent back via the Cloud API and saved to your chat history

​
The 24-Hour Customer Service Window

WhatsApp enforces a strict 24-hour customer service window. Your assistant (and human agents) can only send free-form messages within 24 hours of the customer’s last message. After that window closes, free-form replies are rejected — the customer must message you again to reopen it, or you can re-engage using an approved template message.
Unlike Messenger, WhatsApp does not offer a human-agent tag to extend the window. Outside 24 hours, a pre-approved template is the only way to message a customer.

​
Message Templates

Templates are pre-written, Meta-approved messages used for business-initiated conversations and to re-engage customers after the 24-hour window closes. Manage them from the Message Templates card on the WhatsApp channel page:
  • View templates — Each template shows its status (Approved, Pending, Rejected, etc.), category, and language
  • Create a template — Click Create Template, then provide:
    • Template Name — lowercase letters, numbers, and underscores only (e.g. order_confirmation)
    • Category — Utility, Marketing, or Authentication
    • Language — English (US/UK), Spanish, French, or Portuguese (BR)
    • Body Text — up to 1024 characters
  • Delete a template — Remove templates you no longer need
New templates are submitted to Meta for review and start as Pending. They can only be used once Meta marks them Approved — review usually takes a few minutes but can take longer.

​
Human Handoff

Human handoff for WhatsApp happens in the Universal Inbox — there is no separate WhatsApp agent screen. Your WhatsApp conversations appear in the inbox alongside Messenger, Instagram, and Live Chat, so your team works every channel from one place. From the inbox you can:
  • Take over AI on a conversation so the assistant stops replying and you respond manually
  • Claim a conversation so teammates know you’re handling it
  • Reply directly to the customer over WhatsApp
  • Resume AI to hand the conversation back to your assistant
  • Set an auto-resume timer (from 5 minutes up to 7 days) so conversations don’t stay in human mode indefinitely
Human replies are still bound by the 24-hour customer service window. If the window has expired, agent messages from the inbox cannot be sent until the customer messages again. Use an approved template to re-engage outside the window.
For full details on claiming, internal notes, and AI control, see the Universal Inbox guide.

​
WhatsApp Analytics

Track how your WhatsApp integration is performing from the WhatsApp Analytics dashboard on the channel page. Filter by Last 7 days, Last 30 days, or Last 90 days.

​
Usage Metrics

  • Total Messages: Combined inbound and outbound message counts
  • Inbound Messages: Messages received from users
  • Outbound Messages: Messages sent by your assistant or human agents
  • Delivered Messages: Messages confirmed as delivered by Meta
  • Read Messages: Messages confirmed as read by the recipient
  • Delivery Rate: Percentage of outbound messages successfully delivered
  • Read Rate: Percentage of outbound messages read by recipients

​
Conversation Metrics

  • Total Conversations: All WhatsApp conversations
  • Active Conversations: Conversations with activity in the selected period
  • Human Takeover Count: Conversations currently in human takeover mode

​
Daily Breakdown

View message volume by day to spot trends and peak usage periods, with inbound versus outbound messages over time. The dashboard also lists recent conversations for quick access.

​
Admin Configuration

All WhatsApp management requires the Admin role in the workspace. Admins can:
  • Connect and disconnect WhatsApp Business numbers
  • Enable/disable the WhatsApp channel and update messaging settings
  • Create, view, and delete message templates
  • View analytics and conversation history
  • Take over conversations and send messages as a human agent from the inbox

​
Best Practices

The one-click flow generates tokens and subscribes webhooks for you, so there’s no manual credential management. Reserve Advanced Setup for cases where you run your own Meta App.
Because templates require Meta review, create your common re-engagement messages ahead of time so they’re already Approved when the 24-hour window closes on an active conversation.
Use Utility for transactional messages (order updates, reminders), Marketing for promotions, and Authentication for one-time passcodes. Picking the wrong category is a common cause of rejection.
Add WhatsApp-specific guidance to your assistant’s system prompt, such as keeping replies concise and conversational, since WhatsApp is a fast, chat-style channel.
The connection card shows your number’s quality rating (Green/Yellow/Red). A declining rating can lead to messaging limits — keep responses helpful and avoid spammy template sends.
A low delivery rate may indicate token or quality issues; a low read rate may mean your responses need to be timelier or more engaging.

​
Troubleshooting

​
Connection failed or shows a connection issue

  • Confirm your Meta Business Account, WhatsApp Business Account, and phone number are all set up and the number is registered for WhatsApp Business
  • For manual connections, double-check the Phone Number ID, WABA ID, System User Access Token, and App Secret — an invalid or expired token is the most common cause
  • If the connection card shows a Connection issue, Disconnect and reconnect to re-authorize
  • Use the Test button to re-check that the connection is active

​
Phone number already connected

Each WhatsApp number can only be connected to one assistant. Disconnect it from the other assistant before connecting it here.

​
Not receiving messages

  • Verify the WhatsApp channel is Enabled and the connection status is active
  • For manual connections, confirm the Webhook URL is set in your Meta App Dashboard with the correct Verify Token, and that the messages field is subscribed
  • Ensure the phone number is properly registered on the Cloud API

​
Can’t send a message — window expired

If you see an error that the messaging window has expired, more than 24 hours have passed since the customer’s last message. WhatsApp does not allow free-form replies after this window. Wait for the customer to message again, or re-engage with an approved template.

​
Template rejected or stuck pending

  • Templates must be Approved by Meta before use; freshly created templates start as Pending
  • A Rejected status usually means the content or category violates WhatsApp’s policies — review Meta’s feedback, fix the body text or category, and recreate it
  • Template names must use lowercase letters, numbers, and underscores only

Need help?

Contact support for WhatsApp setup assistance