Messenger Platform

Account Linking

Account Linking is separate from the other webview features available in Messenger Platform. It can only be started via Log In buttons, and not from the bot's persistent menu, from URL buttons, or from within an already-opened webview flow or Chat Plugin.

Developers using these features can now get the user's ID in a secure fashion using the getContext() function in Messenger Extensions. Bots can then use that to link the user's account or personalize the experience.

Account Linking is currently only supported on iOS and Android Messenger app.

When a user starts a conversation with your business, you may want to identify him or her as a customer who already has an account with your business. To help with this, we have created a secured protocol to link and unlink the Messenger user identity with your business user identity.

Account Linking allows you to invite users to log-in using your own authentication flow, and to receive a Messenger page-scoped ID (PSID) upon completion. You can then provide a more secure, personalized and relevant experience to users.

Contents

Linking Process

The Account Linking flow follows few simple steps.

  1. Register a callback URL using Log In Button.
  2. Messenger Platform invokes the registered URL when a user starts the account linking flow. The redirect_uri and account_linking_token parameters are appended to your registered callback.
  3. Once linking is complete, redirect users to the location provided by redirect_uri and append a authorization_code parameter (defined by you) to confirm linking.
  4. Optionally retrieve the user's page-scoped ID (PSID) using the account linking endpoint. This step should only be used in special cases when you need the user's PSID as part of the linking process.

Account Unlinking can be initiated:

Callback

Account linking URL is invoked by Messenger Platform when a user triggers account linking. The redirect_uri and account_linking_token parameters are appended to the URL callback.

<yourAccountLinkingUrl>
  ?account_linking_token=ACCOUNT_LINKING_TOKEN
  &redirect_uri=CALLBACK_URL

If account linking is successful, you need to complete the flow by redirecting the browser to the URL specified in the redirect_uri parameter and appending an authorization_code parameter defined by you. Note that the URL may already contain parameters, so you should append the authorization code accordingly:

<redirect_uri>
  &authorization_code=AUTHORIZATION_CODE

If account linking failed, redirect the browser to the redirect_uri passed to you as a parameter but do not append the authorization_code.

Parameters

Parameter Name Description

redirect_uri

Redirect URI which will be added by Messenger, you must redirect the browser to this location at the end of the authentication flow. It may contain URL encoded parameters.

account_linking_token

Short-lived token passed by Messenger which you need to pass back as part of the redirect scheme. This token is only valid for 5 minutes, it is encrypted and unique per user.
You can call the PSID retrieval endpoint with this token to fetch the corresponding PSID.

authorization_code

Code provided by you to confirm a successful linking. Messenger Platform will pass back this code along with the user's PSID as the Account Linking webhook event. Failing to pass this parameter will cause the linking process to abort.

Webhook event

A successful linking flow triggers the Account Linking event to deliver the user's page-scoped ID (PSID).

You must register to the account linking callback event. Not acknowledging this webhook event will cause the linking process to abort.

PSID retrieval endpoint

In certain cases you need to retrieve the user page-scoped ID (PSID) during the linking flow. To help with this situation we are providing a PSID retrieval endpoint allowing you to fetch the user's PSID given a valid and unexpired account_linking_token.

Request

curl -X GET "https://graph.facebook.com/v2.6/me?access_token=PAGE_ACCESS_TOKEN \
      &fields=recipient \
      &account_linking_token=ACCOUNT_LINKING_TOKEN"

Response

{
  "id": "PAGE_ID",
  "recipient": "PSID"
}

In certain cases you need to unlink the user page-scoped ID (PSID) programmatically from your backend. To help with this situation we are providing a PSID unlinking endpoint allowing you to unlink the user's account given a valid PSID.

Request

curl -X POST -H "Content-Type: application/json" -d '{
   "psid":"PSID"
}' "https://graph.facebook.com/v2.6/me/unlink_accounts?access_token=PAGE_ACCESS_TOKEN"

Response

{
  "result": "unlink account success"
}

Best Practices

Use Account Linking when you have a user account system that extends beyond Messenger.

Let people create an account from within Messenger, so it's available elsewhere.

Prompt for login when it's contextually relevant—that is, when your bot user can see the benefit of doing it.

Consider how your bot should behave if a user declines login.

Provide clear confirmation and a friendly welcome after login.

Don't use Account Linking if people will only interact with you via Messenger. You can store account information via thread ID.

Don't require Account Linking right away if you can avoid it; let people get a sense for your bot first.

Recommended Design Flow

  1. Prompt for login with a message that includes our Account Linking button.
  2. Show your login page (including a Create Account option) in the Account Linking webview. Ensure it looks good and works well on mobile screens.
  3. After successful login, display a confirmation message in the webview. Users will need to dismiss it themselves afterward.
  4. Follow up with a friendly thank-you and/or next steps in the thread, including a Log Out option.