WhatsApp setup
Connect WhatsApp Business messaging, including the one Meta requirement that most often breaks the integration.
WhatsApp routes messages from the WhatsApp Business Cloud API to your agent and sends replies back.
WhatsApp has more setup than other channels, and most of it happens on Meta's side rather than in KlicForge. Read the critical requirement below before you start — it's the reason most WhatsApp integrations silently stop working.
Prerequisites
- A Meta Business (Business Manager) account. If you don't already have a WhatsApp Business number, Meta's signup flow lets you create one during setup.
- A phone number that isn't currently active on the WhatsApp consumer app or Business app on another device — see the warning in Connecting below.
- A plan that includes the WhatsApp channel.
The one thing that breaks WhatsApp
Your agent cannot start a conversation. Meta blocks any business-initiated message outside the 24-hour customer service window unless it uses a pre-approved message template. Send the first template message from WhatsApp Manager to open the window; the agent can then reply freely until it closes.
Connecting
Start the connection
Open the agent's Channels tab and select Connect WhatsApp.
Continue with Meta
Click Continue with Meta. This opens a Meta window — as a popup or a new browser tab, depending on your browser — where you choose your Meta Business portfolio, select an existing WhatsApp number or create a new one, and verify it. You're returned to KlicForge automatically once that's done; keep the Meta window open until it finishes.
If the number is already on the WhatsApp Business App, connecting deactivates it on that device. If it's on personal WhatsApp, uninstall WhatsApp there first. If you're migrating from another provider, existing conversations do not transfer.
Choose a reply mode
| Mode | What happens |
|---|---|
| Observe only | Messages are stored but the agent doesn't reply — useful while you review setup. |
| Draft replies | The agent drafts a reply to every message; you approve it before it sends. |
| Auto reply | The agent replies automatically. Requires confirming the agent is assigned, its knowledge base is accurate, escalation is configured, tone has been reviewed, and a test conversation has succeeded. |
You can change this at any time from the channel's settings.
Test
Message your WhatsApp business number and confirm the agent replies.
If the number's status shows Pending after connecting, KlicForge already attempted to register it with Meta automatically — open the channel's settings and click Register with Meta to retry.
Expected result
Messages to your business number are answered by the agent, and conversations appear in the dashboard.
Attachments
Customers can send photos, documents and voice notes to your WhatsApp number, and the agent handles each the same way it does on the web widget:
- Photos are described to the agent when image analysis is enabled for the agent.
- Documents are read when file upload is enabled, up to the agent's configured size and count limits.
- Voice notes are transcribed automatically.
Each one counts as an extra interaction against your usage — see interaction counting.
Slash commands
WhatsApp has no command menu, so these are recognised in the message text — a contact types them like any other message.
| Command | What it does |
|---|---|
/start | Starts a new conversation, keeping what the agent remembers about the contact |
/reset | Starts a new conversation and excludes the session from memory |
/help | Lists the commands available on this channel |
Commands are always answered directly, even when the connection is set to draft replies for human review — the reply is a fixed acknowledgement, not something an agent wrote.
The 24-hour window
Meta allows free-form business replies only within 24 hours of the customer's last message. Outside that window you must use an approved template.
This affects scheduled tasks: a task delivering to WhatsApp requires an approved template, because there is no guarantee the window is open when it runs.
Templates and quality
Message templates are created and approved in WhatsApp Manager, not in KlicForge. Meta also applies quality ratings and messaging limits to your number, which can restrict how many conversations you can start. Those rules change regularly — check Meta's own documentation for current limits rather than relying on any figure reproduced here.
Opting out of marketing messages
A customer can reply STOP to any of your WhatsApp numbers and will stop receiving marketing
templates from that workspace. unsubscribe, optout, opt out and berhenti do the same.
They can reply START — or unstop, subscribe, resume — to start receiving them again.
Either way KlicForge sends a short confirmation, and the agent does not see the message.
Only marketing templates are suppressed. Utility and authentication templates — payment reminders, appointment notices, verification codes — keep going out to someone who has opted out, because they are transactional rather than promotional.
Which of those a template is, is Meta's decision, not yours: the category is assigned when the template is approved and Meta can change it afterwards. Check a template's category in WhatsApp Manager if you are unsure whether an opt-out will suppress it.
The keyword has to be the whole message. "Stop by the shop tomorrow" is an ordinary message and
reaches the agent normally. cancel, quit and end are deliberately not opt-out words — they
are ordinary things to say to an agent, and a booking agent that offers "reply CANCEL to cancel
your appointment" would otherwise unsubscribe the customer instead.
Opt-outs apply across every WhatsApp connection in the workspace, however it was set up, and they apply to audience messages as well as to anything an agent sends.
Restricting who can chat
Anyone who has your WhatsApp number can message the agent. To limit it to a known audience, set the channel to Restricted on its Allow List tab and add the people who may use it.
Entries can be contacts who have messaged before, or rows from a data table with a
whatsapp_id or phone column — which is how you authorise a customer who has not messaged
yet. Pick Everyone in this table and the list follows the table: add a customer row and they
can message, without anyone touching the channel. See
access control.
The picker offers only data tables this agent has read permission on. If a table you expect is missing, grant it from the table's Permissions tab — see permissions.
Store the number in the column the way the field type expects — a whatsapp_id column holds
digits only, a phone column holds the international form beginning +. Either matches an
incoming sender.
Disconnecting
From the agent's Channels tab, select Disconnect.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Number stuck showing Pending | Automatic registration didn't complete — retry with Register with Meta in the channel's settings |
| Agent cannot message a customer first | Expected — this needs an approved template and an open window |
| Scheduled task to WhatsApp does not send | The task has no approved template selected |
| Replies stop after a day of silence | The 24-hour window closed |
| Nobody gets a reply | The channel is Restricted and the allow list matches nobody |
| A customer on the allow list is refused | Their number is stored in a format the column does not expect |
| A customer stopped getting marketing | They replied STOP — utility templates still reach them |
| A data table is missing from the picker | The agent has no read permission on it |