# 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's Page-scoped ID. Bots can then use that to link the user'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 {#linking_process}

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'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'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'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
{
  "account_linking_url": "<YOUR_ACCOUNT_LINKING_URL>"
}
```

## Callback {#callback}

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.

```
<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 {#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.  <br>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'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 {#webhook}

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'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 {#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"
}
```

## Account Unlink Endpoint {#unlink}

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 {#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.