Link accounts

Learn how to link a Facebook account and choose its Pages with Unipile API.

How does it work ?

To link a Facebook account with Unipile, you can offer users these authentication methods:

  • Using credentials (email or username & password) - A dedicated session is created for Unipile. Facebook may ask for additional verification during login.
  • Using cookies (xs, c_user, and datr) - The session is shared from a browser where the user is already logged in to Facebook or Messenger. Adding the optional sb and fr cookies can improve session stability.
  • Using UniLogin (Hosted Authentication only) - The active browser session is connected through the UniLogin extension.

If Facebook invalidates the session, the account status changes to disconnected (🟡 Authentication required).


Facebook products

A Facebook account is connected with the following products:

products valueProductDescription
messagingPersonal accountThe Messenger inbox of the account. Always activated.
pageFacebook PagesThe Pages administered by the account. Each activated Page runs as its own product, page_<page_id>.

Both products are allowed by default. Use these configuration fields to change what can be activated:

  • products restricts the allowed products. Set it to ["messaging"] to connect no Page.
  • page_ids restricts the Pages that can be activated. It takes Page IDs, the ones found in PAGE_<page_id>_INBOX.
  • allow_product_selection lets the user choose. It defaults to true in Hosted Authentication and to false in Custom Authentication, where every allowed Page is then activated automatically.

If Unipile cannot list the Pages of the account during login, the account is still linked, without its Pages. Learn how to use them in Facebook Pages.


Link with Hosted Authentication

To link Facebook accounts using Hosted Authentication, follow the Authenticate with Hosted Auth guide.

At the Create Auth Link step:

  • Set facebook as the providers.
  • By default, Hosted Authentication displays the credentials, cookies, and UniLogin methods. Use allow_methods in the Facebook configuration to display fewer.

After login, Hosted Authentication displays the product selection screen, then offers to unlock the encrypted message history.

Server code

// ...

const response = await unipile
  .hostedAuth
  .createAuthLink({
    providers: "facebook",
    expires_on: dayjs().add(10, 'minutes').toISOString(),
    redirect_uri: "https://myapp.com/link-account/callback",
    config: {
      facebook: {
        allow_methods: ["credentials", "cookies"],
      }
    }
  });

// ...
# ...

response = hosted_auth_api.create_auth_link(
    {
        "providers": "facebook",
        "expires_on": "2025-05-05T00:00:00.000Z",
        "redirect_uri": "https://myapp.com/link-account/callback",
        "config": {
            "facebook": {
                "allow_methods": ["credentials", "cookies"],
            }
        },
    }
)

# ...
curl --request POST \
     --url https://api.unipile.com/v2/auth/link \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "providers": "facebook",
  "redirect_uri": "https://myapp.com/link-account/callback",
  "expires_on": "2025-05-05T00:00:00.000Z",
  "config": {
    "facebook": {
      "allow_methods": ["credentials", "cookies"]
    }
  }
}
'

Link with Custom Authentication

To build a custom authentication wizard for Facebook accounts, follow the Credentials Flow guide.

Client code

const data = await startAuthIntent({
  provider: "facebook",
  credentials: {
    username,
    password,
  },
});

To let users authenticate with cookies, create a form that takes the cookies. Forward them instead of the username and password, along with the exact user agent of the browser they come from.

Client code

const data = await startAuthIntent({
  provider: "facebook",
  user_agent: navigator.userAgent,
  credentials: {
    xs,
    c_user,
    datr,
  },
});

Handle Facebook checkpoints

Your wizard must handle the checkpoints below. Facebook does not support Request Checkpoint or Resend Checkpoint: both return 501 api/not_implemented.

CheckpointWhen it happensAnswer
2FAThe account is protected by two-factor authentication. checkpoint.platform tells where the code comes from: authenticator app, SMS, or WhatsApp.The code, in code
OTPFacebook sent a verification code.The code, in code
CAPTCHAFacebook requires a security check.The challenge solution, as described in the Credentials Flow
IN_APP_VALIDATIONThe login must be approved from another device. When checkpoint.code is present, the user must match this number during the approval.None: wait for the approval, as described in the Credentials Flow
CONSENT_SCREENallow_product_selection is true.See Let the user choose its Pages
ENCRYPTED_HISTORYThe login succeeded and Unipile offers to unlock past encrypted messages.See Unlock the encrypted history

Let the user choose its Pages

To let the user choose, set allow_product_selection to true. Unipile returns a CONSENT_SCREEN checkpoint after login, even when the account administers no Page.

const data = await startAuthIntent({
  provider: "facebook",
  credentials: {
    username,
    password,
  },
  config: {
    allow_product_selection: true,
  },
});

checkpoint.products lists messaging and one page_<page_id> entry per Page. Display them, then send the selected IDs as a JSON-stringified array in the code of Solve a Checkpoint. The messaging product stays activated even if it is not selected.

curl --request POST \
     --url https://api.unipile.com/v2/auth/checkpoint \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "intent_id": "acc_123456789",
  "code": "[\"messaging\",\"page_1357020157484056\"]"
}
'

Unlock the encrypted history

Once login has succeeded, Unipile returns an ENCRYPTED_HISTORY checkpoint. The answer decides whether past messages of end-to-end encrypted chats can be read. New messages arrive either way.

Send the selected option in code and, when it needs one, the secret in credential:

codecredentialEffect
RECOVERY_CODEThe 40-character codeVerified, then stored with the account. Not rate-limited by Messenger.
PINThe Messenger PINExchanged once for the recovery code, then discarded. Wrong attempts count against Messenger's own limit.
SKIPNoneNothing is stored. New messages still arrive, but past messages stay unreadable.
curl --request POST \
     --url https://api.unipile.com/v2/auth/checkpoint \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "intent_id": "acc_123456789",
  "code": "RECOVERY_CODE",
  "credential": "YOUR_40_CHARACTER_RECOVERY_CODE"
}
'

If the secret is refused, the same checkpoint is returned with updated options[].attempts_remaining and a last_attempt.error:

  • INVALID_CREDENTIAL: the secret did not unlock the history.
  • REFUSED_TO_PROTECT_BACKUP: the PIN was not submitted because Messenger allows too few attempts, and a wrong PIN could lock the backup for good. Ask for the recovery code instead.

The account is only created once the user has settled, so always keep SKIP available.

👍

Prefer the recovery code

Users can generate it in Messenger: Profile → Privacy & safety → End-to-end encrypted chats → Message storage → Manage security methods → 40-character code.


Handle login errors

ErrorCauseWhat to do
401 provider/invalid_credentialsThe email, username, or password is wrong, or the cookies are invalid or expired.Ask the user for new credentials or fresh cookies.
401 provider/invalid_checkpoint_codeThe verification code is invalid or expired.Ask the user for a new code.
403 provider/access_restrictedFacebook requires an action on its website, the account appears suspended, or the login was not approved in time. The error details the reason.Ask the user to log in on facebook.com and complete what is requested, then try again.
502 api/proxy_errorFacebook could not be reached through the proxy, or is blocking the login from this IP.Try again later, or with another proxy.

A 403 provider/access_restricted error can notably mean that Facebook asks the user to choose between a subscription and using it for free with ads. This choice can only be made on facebook.com.


Reconnect an account

When an existing account is reconnected without products, page_ids, or allow_product_selection, the Pages already activated are kept. To add a Page, set allow_product_selection to true: every Page is offered again.

Learn more about reconnection in Status & Lifecycle.


What’s Next

Continue with Facebook Pages, messaging, and posts after the account is linked.

Did this page help you?