WhatsApp Business (Integrations)
This page covers the integration tile flow — how to connect, what gets stored, common errors. For day-to-day inbox behaviour (templates, the 24-hour window, bulk sends), see Chat Inbox → WhatsApp.
Connection methods
Two paths, depending on your Kinderpedia config:
Embedded Signup (recommended)
When Embedded Signup is enabled on your Kinderpedia instance, the tile shows Continue with WhatsApp. Meta walks you through Business Manager + WABA + phone number selection in ~3 minutes. We capture the WABA ID + phone number ID + system-user access token automatically.
Result: credentials saved encrypted, the integration is flagged as set up via Embedded Signup, and the webhook is auto-subscribed.
Manual paste
Available when Embedded Signup isn't enabled on your instance, or as a fallback. The tile shows Connect manually, opens a form for:
- Phone Number ID (from
business.facebook.com/wa/manage/phone-numbers) - WABA ID (same page)
- System User Access Token (from Meta Business Manager → System Users)
We validate by calling GET /{phone_number_id}?fields=display_phone_number with the token. If it works, credentials save and webhook subscription attempts run.
Either way the resulting saved credentials are structurally identical — the only difference is the connection method flag (useful for support diagnosis).
Webhook URL
https://<your-domain>/api/integrations/whatsapp/webhook. This is fixed per Kinderpedia instance, not per school — but inbound events carry the WABA ID, and we route them to the right school by that.
For Embedded Signup, subscription is automatic. For manual setup, you may need to paste the URL into Meta's Webhooks → WhatsApp config and verify with the token your Kinderpedia admin provides.
Verifying the connection
After connect, the tile shows:
- Connected phone number (display format like
+1 555 0100) - Number of approved templates synced
- Last inbound timestamp (if any)
- Subscription health: green = subscribed, amber = pending
Click Test connection to fire a GET /{phone_number_id} from the server — confirms the token still works.
Templates sync
Right on the tile: Sync templates. We call GET /{waba_id}/message_templates?status=APPROVED and mirror approved templates into your local cache. Only approved templates show up in the picker.
Auto-sync runs nightly via cron (app:whatsapp:sync-templates). Manual sync is for when you've just had a template approved and want it usable immediately.
Per-WABA limits
Meta imposes per-WABA limits:
- Conversations per day (varies by tier: 1k / 10k / 100k / unlimited)
- Phone number rate: ~80 messages/sec per number
- Template messages: no rate limit but charges per-conversation
We don't enforce these client-side — Meta returns 429s if you exceed and we surface them. For bulk sends, the 100-leads-per-batch cap is a sensible default that stays well within tier limits.
Disconnecting
Disconnect:
- Un-subscribes via
DELETE /{waba_id}/subscribed_apps. - Clears
credentials. - Row →
disconnected.
Existing threads stay in the inbox (read-only). Reconnect to enable replies again.
Common errors
| Symptom | Likely cause |
|---|---|
| Embedded Signup returns "config not found" | Embedded Signup config mismatched or revoked — contact your Kinderpedia admin. |
| Manual save rejects token as "expired" | System User token rotated. Generate fresh one. |
| Webhook subscription stuck "pending" | WABA already subscribed to another Meta App. Unsubscribe over there first. |
| Templates list is empty after sync | No approved templates yet, or wrong WABA ID. |
| Bulk send fails with rate limit | Tier limit hit. Wait 24h or upgrade Meta tier. |