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, anddatr) - The session is shared from a browser where the user is already logged in to Facebook or Messenger. Adding the optionalsbandfrcookies 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 value | Product | Description |
|---|---|---|
messaging | Personal account | The Messenger inbox of the account. Always activated. |
page | Facebook Pages | The 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:
productsrestricts the allowed products. Set it to["messaging"]to connect no Page.page_idsrestricts the Pages that can be activated. It takes Page IDs, the ones found inPAGE_<page_id>_INBOX.allow_product_selectionlets the user choose. It defaults totruein Hosted Authentication and tofalsein 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
facebookas theproviders. - By default, Hosted Authentication displays the credentials, cookies, and UniLogin methods. Use
allow_methodsin 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.
| Checkpoint | When it happens | Answer |
|---|---|---|
2FA | The account is protected by two-factor authentication. checkpoint.platform tells where the code comes from: authenticator app, SMS, or WhatsApp. | The code, in code |
OTP | Facebook sent a verification code. | The code, in code |
CAPTCHA | Facebook requires a security check. | The challenge solution, as described in the Credentials Flow |
IN_APP_VALIDATION | The 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_SCREEN | allow_product_selection is true. | See Let the user choose its Pages |
ENCRYPTED_HISTORY | The 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:
code | credential | Effect |
|---|---|---|
RECOVERY_CODE | The 40-character code | Verified, then stored with the account. Not rate-limited by Messenger. |
PIN | The Messenger PIN | Exchanged once for the recovery code, then discarded. Wrong attempts count against Messenger's own limit. |
SKIP | None | Nothing 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 codeUsers can generate it in Messenger: Profile → Privacy & safety → End-to-end encrypted chats → Message storage → Manage security methods → 40-character code.
Handle login errors
| Error | Cause | What to do |
|---|---|---|
401 provider/invalid_credentials | The 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_code | The verification code is invalid or expired. | Ask the user for a new code. |
403 provider/access_restricted | Facebook 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_error | Facebook 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.
Updated 2 days ago
What’s Next
Continue with Facebook Pages, messaging, and posts after the account is linked.