Use the WhatsApp inbox, floating widget and automatic notifications to reply to patients, send service messages and track delivery.
Who can do this: /app/whatsapp-inbox is role-gated to SUPER_ADMIN, BRANCH_MANAGER and RECEPTIONIST; the permission catalog includes whatsapp.use.
Where: WhatsApp Inbox (/app/whatsapp-inbox) and the floating widget on staff screens.
Before you start
- Configure
whatsapp.enabled,whatsapp.provider, access token and provider IDs. - For Meta, configure phone number ID and approved templates.
- Keep patient mobiles accurate; 10-digit Indian numbers are normalised with
91. - Remember the 24-hour service window for free-form replies.
Open and refresh the inbox
- Open WhatsApp Inbox. Result: Inbox and outbox messages load and group by phone.
- Click a conversation. Result: The message thread opens.
- Click Refresh. Result: Messages refresh immediately. The page also polls every 30 seconds.
- Review ticks: Sent, Delivered, Read or failed marker. Result: Delivery state is visible.
Reply to a patient
- Select a conversation. Result: The reply box is active.
- Check the banner: 24-hour service window active or 24-hour service window inactive. First message will go as template. Result: You know whether a free-form reply or template is expected.
- Type the reply and optionally attach media. Result: Text or media is ready.
- Click send. Result: The configured provider sends the message and outbox updates.
Use the floating widget
- Click the green WhatsApp button. Result: A compact inbox opens.
- Select a conversation and reply. Result: You can answer without leaving the current page.
- Click Open Full Page.
Result:
/app/whatsapp-inboxopens.
Automatic notifications
- Confirm
whatsapp.enabledis notfalse. Result: Master sending is allowed. - Keep category settings enabled for billing, session, appointment, payment and package alerts. Result: Workflows can trigger WhatsApp messages.
- Use normal workflows such as bill creation, payment, session check-in and package low-balance notify. Result: The backend attempts delivery and stores outbox status.
- Review failed delivery reasons. Result: Staff can manually retry or fix settings.
Templates, opt-out and fair use
- For Meta, sync approved templates into the app where configured. Result: Header, body and button parameters are built correctly.
- If Meta returns
131047, the backend retries with a template when template sending is enabled. Result: Messages outside the 24-hour window have a compliant path. - Respect STOP and START. Patients can opt out or opt back in for blockable categories. Result: Non-critical categories are blocked until resubscribe.
- Watch provider quota and quality in Meta, Twilio or Gupshup dashboards. Result: Provider fair-use limits are visible.
note
No separate in-app fair-use meter was found in this worktree. Use the provider dashboard for quota and quality monitoring.
Troubleshooting
| Problem / message | What it means | What to do |
|---|---|---|
| ?Unable to load WhatsApp messages. Please try again.? | Inbox and outbox failed. | Click Refresh or reopen. |
| ?Failed to send? | Provider send failed. | Check message reason and settings. |
| ?WhatsApp is disabled in settings? | Master toggle off. | Enable WhatsApp. |
| ?No WhatsApp provider configured? | Provider missing. | Configure Meta, Twilio or Gupshup. |
| ?Access token not configured? | Provider token missing. | Add token. |
| ?Phone Number ID not configured for Meta? | Meta phone ID missing. | Add whatsapp.phone_number_id. |
| ?Number not on WhatsApp? | Number is blacklisted after provider error. | Verify patient mobile. |
Meta code 131047 | 24-hour window closed. | Use an approved template. |
Meta code 132001 | Template missing or wrong language. | Create or approve template in Meta or update settings. |
Meta code 131026 | Recipient not allowed or not on WhatsApp. | Verify number and provider mode. |
| ?Media expired or unavailable? | WhatsApp media expired. | Ask patient to resend. |
| ?Failed to update read status? | Mark-read failed. | Refresh and retry. |