Connect a WhatsApp Business number to your agent. People message the number on WhatsApp, and your agent answers with the same knowledge, guardrails, history, and message limits as every other channel.
For example, a hair salon connects its WhatsApp Business number. A client writes "Do you have a slot on Friday afternoon?", and the agent answers with the salon's booking rules within seconds.
WhatsApp is available for public agents only. A WhatsApp sender is not signed in to Chatvia, so a protected agent cannot answer there. To make an agent public, open Security → Identity and turn on Make agent public. See Messaging channels for what all channels have in common.
Setup has two parts:
- Once per install: the person who runs your Chatvia server sets up one Meta app in the admin panel. Every workspace on the install connects through it.
- Per agent: someone in the workspace clicks Connect with Facebook and picks a number. Nobody pastes tokens or secrets.
Until the first part is done, the WhatsApp card on the agent's Channels page is greyed out and says "Not set up on this server".
Registering a real number
A phone number registered with the WhatsApp Business Platform can no longer be used in the WhatsApp or WhatsApp Business phone apps. Meta gives you a free test number first. Use it until you are ready to commit a real number.
For the server admin: set up the Meta app
You do this once. You need a Meta (Facebook) account with a business portfolio, and access to the Chatvia admin panel.
Step 1: Create a Meta app
Go to developers.facebook.com/apps and click Create App. On the Use cases step, select Connect with customers through WhatsApp. Pick your business portfolio and finish the wizard.
Step 2: Create a Facebook Login for Business configuration
WhatsApp Embedded Signup opens a Facebook Login for Business configuration. Create one for WhatsApp Embedded Signup in your Meta app, and copy its configuration ID.
Step 3: Enter the app in Chatvia
Open the admin panel and go to Settings → Channels → WhatsApp (see Channels settings). Fill in:
- App ID and App secret: from App settings → Basic in your Meta app.
- Webhook verify token: any random string. You paste the same value in Meta in the next step.
- Login configuration ID: from Step 2.
- Number registration PIN: optional. Six digits that register connected numbers for the Cloud API. Don't use
000000.
Save. The card shows the Webhook callback URL: {APP_URL}/whatsapp/webhook.
Step 4: Point the webhook at Chatvia
In your Meta app, open the WhatsApp use case's webhook settings. Paste the Webhook callback URL and the Webhook verify token, and save. Then subscribe the webhook to the messages field.
Meta verifies the URL instantly. If it shows an error, check that you pasted the full callback URL with no extra spaces, and the same verify token as in Chatvia.
One webhook serves every number on the install. Chatvia sends each message to the right agent by its phone number ID.
For the workspace: connect a number
Step 1: Connect with Facebook
In Chatvia, open your agent, click Channels in the left menu, and click Setup on the WhatsApp card. Click Connect with Facebook.
A Meta popup opens. Sign in, pick your business portfolio and WhatsApp Business Account, and pick or add a phone number. When the popup closes, Chatvia links the WhatsApp Business Account to the install's Meta app. If your admin set a Number registration PIN, Chatvia also registers the number with Meta. The card then shows Connected with the number's name and phone number.
If the popup closes without a number, add a phone number to your WhatsApp Business Account in the popup and try again.
Step 2: Test it
Send a WhatsApp message to your number (for a test number: from one of the verified phone numbers). Your agent marks the message as read, shows a typing indicator while it thinks, and replies. The conversation appears in your agent's Chatlog with a WhatsApp badge.
To stop, click Disconnect on the card.
Troubleshooting
| Problem | Likely cause |
|---|---|
| The WhatsApp card is greyed out, or a message says WhatsApp isn't set up yet | The admin has not entered the Meta app in Settings → Channels. |
| "Add a phone number to your WhatsApp Business Account in the popup, then try again." | The popup closed before a number was picked or added. |
| "We couldn't read your WhatsApp account from Facebook." | The popup finished without sharing the account. Try connecting again. |
| "Meta couldn't complete the WhatsApp connection." | Meta refused the connection, or the number could not be read. Try again. If it keeps failing, ask your admin to check the Meta app. |
| Connected, but no replies on a real number | The number may not be registered with Meta. Ask your admin to set a Number registration PIN, then disconnect and connect again. |
| Webhook verification fails | Wrong verify token, or the callback URL was not copied fully. |
| No reply to messages | The webhook is not subscribed to the messages field. |
| "That WhatsApp number is already connected to another agent" | Disconnect it from the other agent first. |
| Test number can't reach a phone | The recipient is not in the test number's verified recipient list (maximum 5). |
| "This assistant isn't available on WhatsApp right now." | The agent was made protected after connecting. Make it public again on Security → Identity. |
How replies behave
- Replies are sent as one message (or several, if longer than WhatsApp's 4,096-character limit).
- The agent's formatting is converted to WhatsApp's own style: bold, italic, lists, and quotes all render natively. Links are sent as their text with the URL after it, which WhatsApp makes tappable.
- Chatvia only replies to incoming messages. It never starts a conversation, so its replies always fall inside WhatsApp's 24-hour customer service window.
- Each person has one ongoing conversation with the agent, so it remembers earlier messages.
- Only text messages are answered. Photos, voice notes, stickers, documents, locations and reactions are ignored.
- One number can power one agent at a time. Disconnect stops the agent from answering. Past conversations stay in your Chatlog.