The model
- When a customer signs up in your app, create a profile and store its
_idnext to your customer record: - Every later call names that profile (
profileId) or one of its accounts (accountId).
Connecting your customer’s accounts
Two options: From your UI. CallGET /connect/{platform}?profileId=…&returnUrl=… from
your server and send your customer to the returned authUrl. Once they approve,
PlugKit redirects their browser to your returnUrl with the result in the query
string:
Your existing query parameters are kept.
returnUrl must be https (http is
accepted for localhost), at most 1,024 characters. PlugKit signs it in the
OAuth state, so it can’t be swapped for another site along the way.
Treat the redirect as a signal, not as proof: anyone can open your
returnUrl with made-up parameters. Confirm with GET /accounts/{accountId}
(or the account.connected webhook) before trusting it. returnUrl isn’t
available for Bluesky yet. Telegram and WhatsApp numbers connected by token
don’t go through a redirect.returnUrl, the flow ends on a PlugKit confirmation page.
With a connect link. POST /connect-invites with the profileId returns a
url valid 30 days. Send it to your customer: they pick their platforms on a
PlugKit-hosted page, and the accounts land in their profile. Good for agencies
onboarding clients by email.
After the connection
Each new or reconnected account fires anaccount.connected
webhook carrying accountId, profileId and platform. One authorization can
create several accounts (a Facebook login granting three Pages gives three
accounts, so three events).
Tokens can die on the platform side (password change, revoked app). The account
switches to needsReconnection: true and an account.disconnected webhook
fires with reason: "reconnection_required" — once, when it flips. Send the
customer back through GET /connect/{platform}?profileId=…&accountId=… to
reconnect the same account (its posts and conversations are kept).
Routing webhooks
Register one webhook endpoint for your whole account. Account events and post events carryprofileId. Message and comment events
carry accountId only: keep an accountId → profileId → your customer map,
filled from account.connected and refreshed from GET /accounts.
Limits to plan for
- Rate limits are per connected account: each of your customers’ accounts
gets its own 20 publications / messages / comment replies per minute, so one
busy customer doesn’t slow the others down. Requests that don’t target an
account (lists without
accountId, profile management…) share your account’s budget. Honourretry-after. See API conventions. - Platform quotas apply per connected account (e.g. 100 Instagram publications per 24 hours).
- Plan: Pro includes 30 connected accounts and bills extra accounts by band beyond that; Creator stops at 5. See Plans & billing.
- Use idempotency keys on
POST /postsand message sends, so a retry from your queue never posts twice.