---
title: "WhatsApp setup"
url: "/channels/whatsapp"
description: "Connect WhatsApp Business messaging, including the one Meta requirement that most often breaks the integration."
productArea: channels
audience: ["business-user", "admin"]
plan: business
tags: ["channels", "whatsapp"]
lastReviewed: 2026-09-09
---
# WhatsApp setup (/channels/whatsapp)
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 [#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 [#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 [#connecting]
### Start the connection [#start-the-connection]
Open the agent's **Channels** tab and select **Connect WhatsApp**.
### Continue with Meta [#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 [#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 [#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 [#expected-result]
Messages to your business number are answered by the agent, and conversations appear in the
dashboard.
## Attachments [#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](/reference/interaction-counting).
## Slash commands [#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](/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 [#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](/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 [#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](https://developers.facebook.com/docs/whatsapp) for current limits
rather than relying on any figure reproduced here.
## Opting out of marketing messages [#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](/scheduled-tasks/audience-messages) as well as to anything an
agent sends.
## Restricting who can chat [#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](/channels#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](/data-tables#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 [#disconnecting]
From the agent's **Channels** tab, select **Disconnect**.
## Troubleshooting [#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 |
## Related pages [#related-pages]
* [Channels overview](/channels)
* [Scheduled tasks](/scheduled-tasks)
* [Audience messages](/scheduled-tasks/audience-messages)
* [Contacts](/contacts)