Meta (Facebook + Instagram)
Both Facebook Messenger and Instagram Direct connect under the same Integrations → Meta tile via a single Embedded Signup flow. The Meta connection grants access to:
- Pages (one or more Facebook Pages you administer)
- Instagram Business / Creator accounts linked to those Pages
A school can have one connection that covers both surfaces.
Connecting
Click Integrations → Meta → Continue with Facebook. Meta's hosted dialog walks you through:
- Log in to Facebook (must be admin on the target Page).
- Grant permissions:
pages_messaging— receive + send DMs on the Pagepages_show_list— list Pages you administerpages_manage_metadata— subscribe the Page to our webhookinstagram_basic— read IG account profileinstagram_manage_messages— send + receive IG DMs
- Pick the Page(s) and IG account(s) to connect.
Meta returns a short-lived user token; we exchange it for a never-expiring Page access token via /oauth/access_token?grant_type=fb_exchange_token. The token is stored encrypted per school.
If the Page has an IG business account linked, a separate integrations row is created for Instagram (provider = instagram) with its own subscription. Both share the same underlying Page token.
Webhook subscription
On connect, we auto-subscribe via:
POST /{page_id}/subscribed_apps
{
"subscribed_fields": ["messages", "messaging_postbacks", "message_reads"]
}For IG, the subscription is inherited from the Page. Inbound events land at /api/integrations/meta/webhook with signature X-Hub-Signature-256 (HMAC against the Meta app secret configured at the Kinderpedia level).
If subscription fails, the integration shows "Action needed" with a Retry subscription button.
What it enables
Once connected, the Chat Inbox at /chat/inbox shows Messenger + Instagram threads in the unified inbox. Conversations are keyed:
- Messenger:
messenger:<PSID>(Page-Scoped ID) - Instagram:
instagram:<IGID>
See the per-channel pages for behaviour specifics:
- Messenger & Instagram in the Chat Inbox
- WhatsApp Business (separate Meta integration, separate tile)
Multi-Page schools
Schools running multiple campuses with separate Facebook Pages can connect them all in one signup. Meta's dialog lets you multi-select Pages, and each gets its own integrations row.
In the inbox, threads from different Pages appear under the same channel filter ("Messenger") but with the originating Page name shown as a chip on each conversation.
24-hour window + Message Tags
Meta enforces a 24-hour customer-care window across all its surfaces. Outside the window, only MESSAGE_TAG sends are permitted — the inbox surfaces tag picker UI for out-of-window outbound. See the Messenger & Instagram doc for tag policy.
Privacy + per-Page scoping
Facebook user IDs are NOT exposed to Pages. We only ever see PSIDs (Page-Scoped IDs) — the same person on a different Page has a different PSID. This means we can't dedupe parents across Pages automatically; manual linking handles cross-page identity.
Profile info we capture (name + avatar) is pulled from GET /{psid}?fields=name,profile_pic and cached on the conversation metadata.
Disconnecting
Disconnect:
- Un-subscribes via
DELETE /{page_id}/subscribed_apps. - Clears credentials.
- Marks both Messenger + Instagram rows as
disconnected.
Existing threads remain in the inbox (read-only) — you can scroll history and reply, but replies will fail until re-connected.
Common errors
| Symptom | Likely cause |
|---|---|
| Embedded Signup popup closes immediately | Pop-up blocker or third-party-cookie restriction. |
| "Permissions error" on grant | User is not an admin on the Page they're trying to connect. |
| Inbox shows Messenger but not Instagram | IG account not converted to Business/Creator, or not linked to the Page. |
| Webhook events stop arriving suddenly | Page admin revoked Kinderpedia from business.facebook.com/settings/apps. |
| Page token returns 190 (invalid token) | Should never happen with never-expiring tokens — investigate revocation history. |