← back to reference index

WhatsApp

Owner only proposed · D145

Connect your own WhatsApp Business number so customers can chat, book and get reminders and review requests on WhatsApp (D145). Full spec: WHATSAPP.md.

STATUS: interactive demo — behavior shown here is the intended contract (nothing is saved; the Meta window is simulated)
Demo state:

Chats & leads

Messages land in the Inbox. First-time chatters are saved as leads.

Book in the chat

The AI receptionist offers your free times; the booking goes straight onto Appointments.

Reminders with buttons

Confirm or Reschedule in one tap. Fewer no-shows.

Google reviews

After the visit, one message with your Google review link. Set it up in Automations.

1 Before you start

Before you start

2 Connect

Connect

Already on the WhatsApp Business app?

Keep your number and your app. You scan a QR in the app, and chats show in both places (Meta calls it coexistence). Open the app at least once every 14 days.

New number

Any number that can get a 6-digit code by SMS or call. A number on the personal WhatsApp app has to be deleted from that app first.

Meta’s own window opens. SchedHubPH never sees your Facebook password. A number can be connected to one SchedHubPH business only.

What happens when you connect?
  1. Meta asks you to pick your business, your WhatsApp account and the number, and to allow access for this number only.
  2. SchedHubPH stores the access key encrypted and never shows it to anyone, including our staff.
  3. We tell Meta to send your number’s new messages to SchedHubPH, and set a security PIN on the number.
  4. We send our standard message templates to Meta for approval, in English and Filipino.
  5. We read your display name, quality rating and daily limit, and check no other business has this number.

Remove access any time with Disconnect here, or in Meta Business Suite under Settings › Integrations.

What it costs

  • Replies in a chat (within 24 hours of the customer’s last message): free up to Meta’s monthly allowance per number verify.
  • Booking notices and reminders (utility templates): a small fee per message, free when the chat window is open.
  • Recall and other marketing messages: the highest rate; only to customers who said yes to marketing.
  • Meta bills your card directly at its Philippine rates. SchedHubPH adds nothing on top. The delivery log shows each message’s type so you can match Meta’s invoice.

WhatsApp’s 24-hour rule, in plain words

  • Within 24 hours of a customer’s last message, you (or the AI) can reply freely.
  • After that, you can only send an approved template, such as a booking reminder or a review request. The Inbox switches to “send a template” on its own.
  • Customers who write “STOP” get no more WhatsApp messages from you (SMS or email instead); “START” turns them back on.
  • Clinics: templates never name the treatment. “Your appointment on Tue 10:00 AM”, not “your root canal” (RA 10173).
Troubleshooting
What you seeFix
“This number is already registered”Another WhatsApp tool has it, or it’s on the personal WhatsApp app. Disconnect the tool, or delete the account in the app, then try again. WhatsApp Business app numbers can stay (coexistence).
Templates stay “Pending”Meta reviews take minutes to a day. We email you when they are approved.
“Payment method needed”Add a card in Meta Business Suite › Billing & payments. Until then reminders go by SMS.
Quality turned Yellow or RedPeople blocked or reported messages. Send fewer recall messages. On Red, recall pauses by itself.
The bot went quiet in one chatSomeone replied from the WhatsApp Business app. It waits 12 hours, or press “Hand back to AI” in the Inbox.
Implementation notes for Cursor

Entities: WhatsAppConnection (waba_id, phone_number_id UNIQUE, display_name + name_status, coexistence, token_enc, pin_enc, token_status, webhook_status, quality_rating, messaging_limit, payment_method_ok, reply_mode, greeting, quick_replies, away_message), CustomerWhatsAppLink, WhatsAppOAuthState.

Key states: Embedded Signup with SchedHubPH’s configuration id; the session-info message returns waba_id + phone_number_id; exchange the code, subscribe the app, register the number with a PIN, sync profile and templates. One number per Business. Payment missing → amber state and SMS/email fallback. Quality Red pauses marketing automations. “Pilot only” until META-APP-SETUP §10 is complete.

Forbidden inventions: no unofficial WhatsApp Web automation, no pasting tokens, no reselling or marking up Meta messages, no bulk broadcasts (Campaigns stay SMS/email, D85), no tokens in the browser, no treatment names in clinic templates.

Governs: WHATSAPP.md (§3 setup, §3a security, §4a behaviour); MESSENGER.md §3a (shared webhook); META-APP-SETUP.md §10; ARCHITECTURE §20, §25, §29; D145; PLAN-425/426/431/432.