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.
The Account Linking flow follows few simple steps.
redirect_uri
and account_linking_token
parameters are appended to your registered callback.redirect_uri
and append a authorization_code
parameter (defined by you) to confirm linking.Account Unlinking can be initiated:
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
.
Parameter Name | Description |
---|---|
| 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. |
| 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. |
| 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. |
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.
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
.
curl -X GET "https://graph.facebook.com/v2.6/me?access_token=PAGE_ACCESS_TOKEN \ &fields=recipient \ &account_linking_token=ACCOUNT_LINKING_TOKEN"
{ "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.
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"
{ "result": "unlink account success" }
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.