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 Extension.

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.

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"
}