← StafFixHR home

WhatsApp notifications

Mirror your in-app HR notifications to WhatsApp so employees actually see them.

For employees — how to opt in

  1. Open My WhatsApp.
  2. Tick the opt-in box and enter your WhatsApp number in E.164 format (e.g. +919876543210).
  3. Save. You'll start receiving payslip, leave-decision, and travel-decision messages on WhatsApp.

You can opt out anytime — in-app notifications continue regardless. Your number is used only for sending HR messages from your employer's verified business account.

For HR / owner — initial server setup

One-time setup, ~30 minutes total. Once done, every tenant on the portal can use it.

  1. Go to business.facebook.com and create / open your Meta Business account.
  2. Add a WhatsApp Business app at Meta for Developers → My Apps → Create App → "Other" → Business type.
  3. Add a dedicated phone number for sending. This number cannot already be on consumer or Business app WhatsApp.Once added, it cannot go back to consumer use.
  4. Copy the four values onto your Railway environment:
    • WHATSAPP_PHONE_NUMBER_ID — found on the app's WhatsApp → API Setup page.
    • WHATSAPP_BUSINESS_ACCOUNT_ID — same page (used for template management on Meta side).
    • WHATSAPP_TOKEN — generate a permanent system-user token (NOT the 24-hour dev token). Permissions: whatsapp_business_messaging + whatsapp_business_management.
    • WHATSAPP_VERIFY_TOKEN — any random string you invent. Used by Meta's webhook handshake.
  5. On the Meta app's Webhooks settings, set the callback URL to https://YOUR-DOMAIN/api/whatsapp/webhook and the verify token to the same WHATSAPP_VERIFY_TOKEN. Subscribe to messages field.
  6. Redeploy. Visit Admin → WhatsApp — the banner should say "WhatsApp Cloud API configured".

Creating message templates in Meta

Meta requires every business-initiated WhatsApp message to use a pre-approved template (free-text messages are only allowed within 24 hours of a user reply). Approval is usually under an hour.

Create these three templates in your Meta WhatsApp Manager → Message Templates:

Template name
payslip_ready
Body
Hi {{1}}, your payslip for {{2}} is ready. View: {{3}}
Template name
leave_decision
Body
Hi {{1}}, your leave request for {{2}} was {{3}}.
Template name
travel_decision
Body
Hi {{1}}, your travel claim '{{2}}' was {{3}}. {{4}}

Then go to Admin → WhatsApp and add the mappings — pick a notification kind from the dropdown, type the template name, save.

What happens with no creds (mock mode)

If WHATSAPP_TOKEN or WHATSAPP_PHONE_NUMBER_ID is missing, the portal still works — sends are logged as MOCK in the recent-sends table. Useful for local dev and for previewing the flow before you've finished Meta setup.

Costs

Meta charges per conversation (a 24-hour window), not per message. In India, business-initiated utility-template conversations are around ₹0.40 each, with the first 1,000 / month free at the time of writing. Check Meta's pricing page for the current rates.

Privacy

We store the employee's WhatsApp number only when they explicitly opt in. The number is used only for sending notifications — never shared, sold, or used for marketing. Employees can revoke opt-in anytime from /me/whatsapp, and we keep a per-message audit log so HR can prove only consented messages were sent.

Questions: hr@staffixhr.com.