Skip to content
warmupDocs

Connect a social network

A project publishes to the networks connected to it: Facebook (a Page), Instagram (a professional account) and Threads. Connecting always needs the account owner to approve access in a browser — it can’t be done with API calls alone.

Flow

Section titled “Flow”

  1. Start the connection:

    Terminal window
    curl -X POST https://api.warmup.social/projects/$PROJECT_ID/connections/instagram/start \
      -H "Authorization: Bearer $WARMUP_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "timezone": "Europe/Berlin" }'
    { "authUrl": "https://www.facebook.com/…/dialog/oauth?…" }

    timezone is optional; daily account refreshes are scheduled in it.

  2. Open authUrl in a browser, sign in to Meta and approve the permissions.

  3. Meta returns the browser to Warmup, which redirects to the project page in the dashboard:

    • ?connect=instagram&result=ok — connected;
    • ?connect=instagram&result=error&code=… — failed, see the codes below;
    • ?connect=facebook&select=<selectionId> — the Facebook account has several Pages, pick one (next section).

  4. Check the result: GET /projects/{id} returns connections.instagram with status: "active".

Choose a Facebook Page

Section titled “Choose a Facebook Page”

When the Facebook account manages several Pages, the user can pick one in the dashboard, or you can do it through the API with the selectionId from the URL:

Terminal window
curl https://api.warmup.social/projects/$PROJECT_ID/connections/facebook/pending/$SELECTION_ID \
  -H "Authorization: Bearer $WARMUP_TOKEN"


curl -X POST https://api.warmup.social/projects/$PROJECT_ID/connections/facebook/select \
  -H "Authorization: Bearer $WARMUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "selectionId": "'$SELECTION_ID'", "pageId": "1234567890" }'

Pages with enabled: false can’t be connected; disabledReason explains why. The selection expires after a short time — start over if it does.

Connection status

Section titled “Connection status”
Status Meaning
active Ready to publish.
needs_reauth Access was lost in Meta. Call …/start again for the same network and approve access.
revoked Access was revoked. Reconnect to use the network again.

missingScopes lists permissions the user declined; publishing may fail without them.

Error codes after sign-in

Section titled “Error codes after sign-in”
Code Meaning
oauth_denied The user cancelled or declined access.
instagram_not_professional The Instagram account must be a Business or Creator account.
no_facebook_pages The Facebook account doesn’t manage any Pages.
account_already_connected This account is already connected to another project.
platform_already_connected The project already has a different account for this network.
oauth_state_invalid The sign-in link expired or was used twice. Start again.
meta_unavailable Meta is temporarily unavailable.

Disconnect

Section titled “Disconnect”
Terminal window
curl -X DELETE https://api.warmup.social/projects/$PROJECT_ID/connections/facebook \
  -H "Authorization: Bearer $WARMUP_TOKEN"