Migrating From Custom Integrations to Third Party Apps


This page summarizes the key activities for ISVs that need to migrate a Workplace integration from Custom Integrations to Third Party Apps, which is mandatory for all SaaS and PaaS products.

If you don't have a third party app yet, you must submit an app creation request. Submit a distinct request for each product that you would like to offer to Workplace customers.

Technical Considerations

While most of the functional API calls (e.g., messaging, iterating feeds) are shared between Custom Integrations and Third Party Apps, there are some key technical differences between the two app types, which are summarized here.

  • Installation Flow

Custom Integrations rely on a System Admin manually generating an access token within the Workplace UI and then providing that value to the API client through some configuration scheme.

In contrast, Third Party Apps eliminate the need for this manual step. Instead, you need to build software to implement one or more Third Party App install flows so that your software can retrieve an access token using a server-to-server API call when an admin chooses to install your product.

  • Access Tokens

Custom Integrations have a single App ID and a single access token. The access token can be used by itself to authenticate API calls.

In contrast, Third Party Apps have a single App ID but many access tokens -- one per installation. This implies that you will need a mechanism to read/write the access token for a particular install when appropriate. Note that you can fetch metadata about an install after you've retrieved the access token.

Third party apps also require an app-secret proof to be supplied along with the access token itself to authenticate API calls.

  • Webhooks

Custom Integrations may establish webhook subscriptions, if necessary. Each webhook subscription is associated with the Custom Integration and has its own callback_url. In effect, this means that each "installation" of a Custom Integration can have its own set of callback URLs.

In contrast, Third Party Apps have one set of webhook subscriptions for all installations of that app. To distinguish webhook POST requests from one customer to another, Workplace includes the community_id (and if relevant, the page_id) within the webhook request body.

  • User IDs

Custom Integrations see native user IDs via the APIs and webhooks (e.g., the same ID as is included in a user's profile URL in Workplace (e.g., https://work.workplace.com/profile.php?id=100010000000000).

In contrast, Third Party Apps see App-Scoped IDs via the APIs and webhooks, which means that you may need to do a data conversion upon changing from a Custom Integration to Third Party app install.

  • Converting a Custom Integration Install to a 3rd Party App Install

To minimize disruption to your customers, Workplace has two endpoints that will allow you to convert existing Custom Integrations into 3rd Party App installations.

The conversion endpoints are only available to whitelisted apps and are usable only for a limited time. Reach out to the Workplace team via Direct Support for more information

To convert an installation:

POST /app/installed_communities ?custom_integration_token={access_token_of_original_ci} &access_token={3rd_party_app_id}|{3rd_party_app_secret} HTTP/1.1 Host: graph.workplace.com { "access_token": "FQVJ0Q..." }

The resulting 3rd party app install will have the same permissions as the converted custom integration, as long as those permissions have been granted to the third party app.

If there are any permissions on the custom integration but not granted to the third party app, these permissions will be removed as part of the conversion. Similarly, if there are permissions granted to the third party app, but not present on the custom integration, these will also not be present on the custom integration.

For any permissions missing after the conversion, the permissions elevation flow can be used to add more permissions to the third party app install.

To convert cached user ids from global to app-scoped:

GET /community/app_scoped_ids
Host: graph.workplace.com

    "app_scoped_ids": [
            "global_id": 1234,
            "app_scoped_id": 4321,

This endpoint will only be usable for a short time after conversion, so please convert all relevant global IDs promptly after custom integration conversion.

Only apps that are configured for whitelabeling can call the /community/app_scoped_ids endpoint.

  • App Uninstalls

Third Party apps are required to subscribe to the uninstall webhook event, which notifies you if an admin decides to remove your app from Workplace.

When you receive this event, you must delete all Workplace customer data and configuration related to this community from your system unless you are required to keep this data by law or because of a separate agreement with the customer.