Messenger Platform

 
 
 

Authentication

The account linking flow follows few simple steps.

  1. Register a callback URL using a Account Linking 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 appened to the URL callback.
  3. Once linking is complete, redirect users to the location provided by redirect_uri and append a authorization_code parameter 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.

Example

URL invoked by Messenger Platform when a user triggers account linking

https://www.example.com/v1/authorize
      ?redirect_uri=CALLBACK_URL
      &account_linking_token=ACCOUNT_LINKING_TOKEN

If account linking is successful, redirect the browser to the redirect_uri specified in your callback to complete the linking flow, and append the authorization_code parameter

https://www.facebook.com/messenger_platform/account_linking
      ?account_linking_token=ACCOUNT_LINKING_TOKEN
      &authorization_code=AUTHORIZATION_CODE

If account linking failed, redirect the browser to the redirect_uri specified in your callback but do not append the authorization_code

https://www.facebook.com/messenger_platform/account_linking
      ?account_linking_token=ACCOUNT_LINKING_TOKEN

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.

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 Account Linking 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 to the account linking callback.
Failing to pass this parameter will cause the linking process to abort.

Callback

A successful linking flow triggers the account linking callback 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.

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