# Account Linking



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.

Use the [ `getContext()`](https://developers.facebook.com/documentation/business-messaging/messenger-platform/webview/context) function in Messenger Extensions to securely get your app user&#039;s Page-scoped ID. Bots can then use that to link the user&#039;s account or personalize the experience.

### Limitations

Account Linking is only supported on iOS and Android Messenger apps.

Account Linking can only be started via [Log In buttons](https://developers.facebook.com/documentation/business-messaging/messenger-platform/send-messages/buttons). It cannot be started from a [persistent menu](https://developers.facebook.com/documentation/business-messaging/messenger-platform/send-messages/persistent-menu), a [URL buttons](https://developers.facebook.com/documentation/business-messaging/messenger-platform/send-messages/buttons), or an already-opened webview flow.

## Linking Process &#123;#linking_process&#125;

The Account Linking flow follows few simple steps.

1. Register a callback URL using [Log In Button](https://developers.facebook.com/documentation/business-messaging/messenger-platform/send-messages/buttons).
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&#039;s page-scoped ID (PSID) using the [account linking endpoint](#endpoint). This step should only be used in special cases when you need the user&#039;s PSID as part of the linking process.

Account Unlinking can be initiated:

* By the user when tapping a [Log Out button](https://developers.facebook.com/documentation/business-messaging/messenger-platform/send-messages/buttons) sent by the developer
* By the business using the [Account Unlink endpoint](#unlink)

## Set your account linking URL

Before using account linking, you must set the `account_linking_url` property in your bot&#039;s [Messenger Profile](https://developers.facebook.com/documentation/business-messaging/messenger-platform/reference/messenger-profile-api). You must have the Administrator role for the Page associated with the bot.

```json
&#123;
  &quot;account_linking_url&quot;: &quot;&lt;YOUR_ACCOUNT_LINKING_URL&gt;&quot;
&#125;
```

## Callback &#123;#callback&#125;

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

```
&lt;yourAccountLinkingUrl&gt;
  ?account_linking_token=ACCOUNT_LINKING_TOKEN
  &amp;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:

```
&lt;redirect_uri&gt;
  &amp;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 &#123;#parameters&#125;

| 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.  &lt;br&gt;You can call the [PSID retrieval endpoint](#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&#039;s PSID as the [Account Linking webhook event](https://developers.facebook.com/documentation/business-messaging/messenger-platform/webhooks/webhook-events/messaging_account_linking). Failing to pass this parameter will cause the linking process to abort. |

## Webhook event &#123;#webhook&#125;

A successful linking flow triggers the [Account Linking event](https://developers.facebook.com/documentation/business-messaging/messenger-platform/webhooks/webhook-events/messaging_account_linking) to deliver the user&#039;s page-scoped ID (PSID).

**Warning:** You must register to the [account linking callback](https://developers.facebook.com/documentation/business-messaging/messenger-platform/webhooks/webhook-events/messaging_account_linking) event. Not acknowledging this webhook event will cause the linking process to abort.

## PSID retrieval endpoint &#123;#endpoint&#125;

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&#039;s PSID given a valid and unexpired `account_linking_token`.

### Request

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

### Response

```
&#123;
  &quot;id&quot;: &quot;PAGE_ID&quot;,
  &quot;recipient&quot;: &quot;PSID&quot;
&#125;
```

## Account Unlink Endpoint &#123;#unlink&#125;

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&#039;s account given a valid PSID.

### Request

```
curl -X POST -H &quot;Content-Type: application/json&quot; -d &#039;&#123;
   &quot;psid&quot;:&quot;PSID&quot;
&#125;&#039; &quot;https://graph.facebook.com/v2.6/me/unlink_accounts?access_token=PAGE_ACCESS_TOKEN&quot;
```

### Response

```
&#123;
  &quot;result&quot;: &quot;unlink account success&quot;
&#125;
```

## Best Practices &#123;#best_practices&#125;
✅ Use Account Linking when you have a user account system that extends beyond Messenger.

✅ Let people create an account from within Messenger, so it&#039;s available elsewhere.

✅ Prompt for login when it&#039;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&#039;t use Account Linking if people will _only_ interact with you via Messenger. You can store account information via thread ID.

❌ Don&#039;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.


---

Full documentation index for this product: https://developers.facebook.com/documentation/business-messaging/messenger-platform/llms.txt
