Connect WhatsApp Business

Connecting the company’s WhatsApp Business number takes about one hour, plus Meta’s template approval (usually minutes, sometimes a day). After that, workers can message the AI assistant on WhatsApp and the system sends shift, leave and pay notifications there. Meta bills WhatsApp conversations to your own account.

Before you start

• A Meta Business account (business.facebook.com) owned by the company, ideally business-verified.
• A phone number that can receive an SMS or call and is not active on the normal WhatsApp or WhatsApp Business app (remove it from the app first).
• A payment card added in WhatsApp Manager — Meta charges per conversation.
• An admin login, with the whatsapp and chat_premium modules switched on (Settings → Modules).
• For the AI assistant: an OpenAI, Anthropic or Azure OpenAI API key.
• Every worker’s WhatsApp number saved on their employee profile.

Step 1 — Set up the Meta side

You finish this step holding five values: Phone Number ID, Business Account ID, a permanent access token, the App Secret and a verify token you invent.

1. Go to developers.facebook.com → My Apps → Create app, choose the Business type and link it to the company’s Business account.
2. In the app, Add product → WhatsApp → Set up.
3. Open WhatsApp → API Setup. Under From, add the phone number, enter the display name and verify the number by SMS or call.
4. On the same page copy the Phone number ID and the WhatsApp Business Account ID.
5. Create a permanent token: Business Settings → Users → System users → Add (role Admin) → Assign assets (the app with full control, and the WhatsApp account) → Generate new token, pick the app, never-expiring, with the permissions whatsapp_business_messaging and whatsapp_business_management. Copy the token now — Meta shows it once.
6. Open App settings → Basic and copy the App Secret (press Show).
7. Make up a verify token — any long random phrase. You will paste it in two places.

Step 2 — Enter the values

Open Settings → Integrations → WhatsApp, fill the form, then save.

The token and secret are hidden after saving; leave the boxes empty later to keep them. Press Test Connection — it should confirm the number.

Step 3 — Connect the webhook

The webhook is how worker messages reach the system.

1. In the Meta app open WhatsApp → Configuration → Webhook → Edit.
2. Callback URL: https://<your company address>/webhook/whatsapp — the WhatsApp settings page shows the exact URL under the verify token.
3. Verify token: the same phrase you saved in step 2. Press Verify and save — Meta checks it instantly.
4. Under Webhook fields, press Manage and subscribe to messages. This one field carries both worker messages and delivery receipts.

Every incoming call is checked against the App Secret signature; a missing or wrong secret is refused.

Step 4 — Create the message templates

WhatsApp only lets a business start a conversation with a pre-approved template. The system uses about 50 of them (shift published, leave approved, payslip ready, document expiring, login code and more).

1. On the WhatsApp settings page press Create all missing. Every template is submitted to Meta with its wording, heading, footer and an Open Dashboard button.
2. Press Check status after a few minutes. Most templates are approved within minutes; marketing ones (welcome, birthday) can take longer.
3. A rejected template: press Delete, wait about a minute, then create it again.
4. Create one template by hand in WhatsApp Manager: name action_alert, category Utility, language as above, body with three variables in this order — {{1}} recipient name, {{2}} event, {{3}} details. Staff alerts (new case, leave or advance requested) use it.

Step 5 — Switch on the AI assistant and staff alerts

• AI assistant: Settings → Integrations → AI assistant. Choose the provider (OpenAI, Anthropic or Azure), paste the API key, pick the answer model and default language, and set Autonomy to auto (replies on its own) or suggest (drafts for staff to send). Press Test.
• Playbook: add the company’s rules — see AI assistant and playbook.
• Staff alerts: Chat settings → Alerts. Create a route, tick the events (case created, ticket created, bot escalated, leave requested, advance requested) and list the staff numbers that should get a WhatsApp alert, one per line as number, label.
• Human takeover: staff reply from the Chat screen; the assistant goes quiet in that conversation and hands back automatically after the set number of hours (default 4), unless a case is still open.

WhatsApp’s 24-hour rule is handled for you: if a worker hasn’t written for a day, staff replies are held and a template invites the worker back; the held replies are delivered when they answer.

Step 6 — Test end to end

• Test Connection on the WhatsApp page succeeds.
• From a phone saved on an onboarded employee’s profile, send “When is payday?” — the assistant answers by name within seconds.
• Send “I need leave next Monday” — a leave request appears in Leaves for approval.
• Approve it — the worker receives the leave-approved template.
• From the Chat screen, reply as staff — the worker receives it and the assistant stays quiet.
• Check WhatsApp → Logs for any failed sends.

Workers are recognised by the last 9 digits of their number against the WhatsApp or phone number on their profile; only onboarded employees are matched, and two employees sharing a number match nobody.

Troubleshooting