Connecting with People Across Apps and Bots in Messenger

It's common for a business to use multiple channels to communicate with its customers, e.g., a website, a mobile app, and Messenger. When a person uses Facebook Login on a website or a mobile app, an ID is created for the specific Facebook app, which is called app-scoped ID. When a person interacts with a business via Messenger, an ID is created for the specific Page associated with the bot in Messenger, which is called Page-scoped ID. This means, for the same person, the IDs across different communication channels are different. Keep in mind, app-scoped IDs are created when a user logs on with your app, so you won't see app-scoped IDs for users that haven't installed, and signed in with, your app.

A business may want to provide a seamless experience for people across different channels. For example, when someone is communicating with a business through a bot in Messenger, the experience could be more personalized if the business recognizes that the person is an existing customer in their Facebook app (e.g. a website or mobile app with Facebook Login). We provide an API for retrieving IDs for the same person across apps and bots in Messenger that are owned by the same business.

First, you must let Facebook know that your apps and the Pages associated with your bot in Messenger are owned by the same business entity. To do this you will need to use Meta Business Manager to:

Then you can query the ids_for_apps edge or ids_for_pages edge for the user node in order to retrieve IDs.

This document covers:

Use Cases
Example Queries
Policy

Use Cases

There are a few primary use cases for this API:

Given a user ID for a bot in Messenger, retrieve the IDs for apps owned by the same business

User Node: An ID scoped to the Page that is associated with a bot in Messenger.
Edge: ids_for_apps
Requirements: This requires a page access token and an appsecret_proof, both of which need to be generated using the app that manages the Page. Additionally, the app managing the page and the other app(s) to connect must be owned by the same business and the user must have installed the app making the request.

Examples:

This returns the IDs for all the apps owned by the same business

GET /{user-psid}/ids_for_apps
    ?access_token=[page_access_token]
    &appsecret_proof=[appsecret_proof]

This returns the ID for the specific app with the app ID 10152368852405295

GET /{user-psid}/ids_for_apps
    ?app=10152368852405295
    &access_token=[page_access_token]
    &appsecret_proof=[appsecret_proof]

Given a user ID for an app, retrieve the IDs for bots in Messenger owned by the same business

User Node: An ID scoped to the app.
Edge: ids_for_pages
Requirements: This requires a app access token and an appsecret_proof, both of which need to be generated using the app that manages the Page(s), and that the ID is scoped to. Additionally, the app and the Page(s) must be owned by the same business.

Examples:

This returns IDs for all bots in Messenger whose associated Page is owned by the same business

GET /{user-asid}/ids_for_pages
    ?access_token=[app_access_token]
    &appsecret_proof=[appsecret_proof]

This returns the ID for the specific bot in Messenger whose associated Page has the page ID 380374449010653

GET /{user-asid}/ids_for_pages
    ?page=380374449010653
    &access_token=[app_access_token]
    &appsecret_proof=[appsecret_proof]

Given a user ID for an app, retrieve the IDs for other apps owned by the same business

User Node: The user node is an ID scoped to the app.
Edge: ids_for_apps
Requirements: This requires an app access token, which is generated by using the app that the ID is scoped to. Additionally, the apps must be owned by the same business.

Examples:

This returns the IDs for all the apps owned by the same business

GET /{user-asid}/ids_for_apps
    ?access_token=[app_access_token]

This returns the ID for the specific app with the app ID 10152368852405295

GET /{user-asid}/ids_for_apps
    ?app=10152368852405295
    &access_token=[app_access_token]

Given a user ID for a Page (associated with a bot), retrieve the IDs for other Pages owned by the same business

User Node: An ID scoped to the Page that is associated with a bot in Messenger.
Edge: ids_for_pages
Requirements: This requires a page access token, which is generated by using the app that the ID is scoped to. Additionally, the Pages must be owned by the same business.

Examples:

This returns the IDs for all the Pages owned by the same business

GET /{user-psid}/ids_for_pages
    ?access_token=[page_access_token]
    &appsecret_proof=[appsecret_proof]

This returns the ID for the specific Page with the app ID 380374449010653

GET /{user-psid}/ids_for_pages
    ?app=380374449010653
    &access_token=[page_access_token]
    &appsecret_proof=[appsecret_proof]

Example Queries

Retrieve associated IDs from an ID for an app

GET /{user-asid}
    ?fields=name,age_range,ids_for_apps,ids_for_pages
    &access_token=[app_access_token]

Example response:

{
  "name": "John Smith",
  "age_range": {
    "min": 21
  },
  "ids_for_apps": {
    "data": [
      {
        "id": "10152368852405295",
        "app": {
          "category": "Business",
          "link": "https://www.facebook.com/games/?app_id=1419232575008550",
          "name": "John's Game App",
          "id": "1419232575008550"
        }
      },
      {
        "id": "645195294",
        "app": {
          "link": "https://apps.facebook.com/johnsmovieappns/",
          "name": "JohnsMovieApp",
          "namespace": "johnsmovieappns",
          "id": "259773517400382"
        }
      }
    ],
    "paging": ...
  },
  "ids_for_pages": {
    "data": [
      {
        "id": "12345123", // The psid for the user for that page
        "page": {
          "category": "Musician",
          "link": "https://www.facebook.com/Johns-Next-Great-Thing-380374449010653/",
          "name": "John's Next Great Thing",
          "id": "380374449010653"
        }
      }
    ],
    "paging": ...
  },
  "id": "645195294"
}

Retrieve associated IDs from an ID for a bot in Messenger

GET /{user-psid}
    ?fields=name,is_payment_enabled,ids_for_apps,ids_for_pages
    &access_token=[page_access_token]
    &appsecret_proof=[appsecret_proof]

Example response:

{
  "name": "John Smith",
  "is_payment_enabled": true,
  "ids_for_apps": {
    "data": [
      {
        "id": "10152368852405295",
        "app": {
          "category": "Business",
          "link": "https://www.facebook.com/games/?app_id=1419232575008550",
          "name": "John's Game App",
          "id": "1419232575008550"
        }
      },
      {
        "id": "645195294",
        "app": {
          "link": "https://apps.facebook.com/johnsmovieappns/",
          "name": "JohnsMovieApp",
          "namespace": "johnsmovieappns",
          "id": "259773517400382"
        }
      }
    ],
    "paging": ...
  },
  "ids_for_pages": {
    "data": [
      {
        "id": "12345123", // The psid for the user for that page
        "page": {
          "category": "Musician",
          "link": "https://www.facebook.com/Johns-Next-Great-Thing-380374449010653/",
          "name": "John's Next Great Thing",
          "id": "380374449010653"
        }
      }
    ],
    "paging": ...
  },
  "id": "645195294"
}

Policy

The API may only be used by a business to connect the IDs for that business's app or Page to another app or Page owned by and maintained on behalf of the same business. For example, service providers may not use the API to support multiple customers.

For potential violations of this policy, your API requests will be subject to a review and return an error message “(#200) Your business is currently going through review to access this API.”