Third Party Integrations for Workplace (BETA)

Third party integrations for Workplace are currently in beta, so some of the technical details may be subject to change.


At F8, we announced new features for Custom Integrations, allowing companies to build sophisticated integrations for their Workplace communities.

We're expanding this functionality to third parties in a limited beta, allowing developers to build an integration that can be installed across multiple Workplace communities via a single app ID.

User Experience

Just like with custom integrations, third party integrations will need to be installed on a Workplace community by a System Admin. However, the System admin doesn't need to create a new Custom Integration.

Instead, they'll see your integration alongside an Install button. Pressing that button allows the admin to see the permissions being requested by the integration, and will grant API access to your app.

Configuring your App

In order to get an app ID for an installable integration, submit a request to your partner engineer, providing the name of the app and the permissions you'll need to request of customers when they install your app. We'll generate the app for you and send you the details of how you can access it.

You'll need to provide the User ID of a Facebook user who can be added as a Developer on the app, so that you can modify the app via

Once you've been added as a developer, you'll need to configure the following values:

  • App Name
  • App Icon (1024x1024, PNG format with transparent background)
  • Redirect URL (under "Facebook Login")
  • Tagline (40 chars max) (under "App Center")
  • Short Description (50 words max) (under "App Center")
  • Publisher (under "App Center")
  • Marketing URL (under "App Center")
  • Terms of Service URL (under "App Center")
  • Privacy Policy URL

Note: We'll manually be verifying and approving this information before your app will be made visible to any customers.

Install Flows

Only System Admins can install an integration for a Workplace community.

There are two different ways that an install can happen:

The install flow for a third party integration is based on the manual login flow on Facebook's platform.

Workplace-Initiated Installation

Certain featured apps will be shown within the Workplace Company Dashboard and hence can be installed starting from Workplace according to this flow:

  1. A System Administrator starts by finding your app in the Integrations tab of their Company Dashboard, and clicks the Install button.
  2. Workplace redirects the user to your app's Redirect URL, passing a code query parameter. You are then responsible for authenticating the user, authorizing them to take the installation action, and getting (and securely storing) an access token before 300 seconds elapses.

Developer-Initiated Installation

This flow is similar to the Workplace Initiated Installation, but it starts on your website:

  1. A user of your app opens your admin configuration page. You are responsible for authenticating the user and authorizing them to take the Workplace app installation action.
  2. At the appropriate point in your admin configuration flow, you redirect (or hyperlink the user) to Workplace.
  3. Workplace will then authenticate the user and ensure that the user has the System Administrator role. If so, the user will have the opportunity to review your app's metadata and requested permissions before clicking the Install button.
  4. Workplace redirects the user back to your app's Redirect URL, passing a code query parameter. You are then responsible for authenticating the user, authorizing them to take the installation action, and getting (and securely storing) an access token before 300 seconds elapses.

To begin this flow, redirect or hyperlink users to the Integration Tab, passing your app ID as a query-string parameter. This will bring up your app's install dialog, where a system admin can review the permissions and install your app.

The redirect should go to the following destination:{your-app-id}

Getting an Access Token

Regardless of whether the app installation was initiated on your site or within Workplace, to get an access token from the Oauth code param passed to you, make a GET request to the /oauth/access_token endpoint on the Graph API, passing the code as a param, and including your app ID, app secret and a redirect URI, as follows:


When this call returns, it'll include an access token that you can use to make API calls for the Workplace community on which your app was installed.

Getting the install flow right is important. When we pass the code to your install endpoint, you'll want to make sure you exchange it for a token and store that token for the user that's logged into your service, before the code expiry period (5 minutes) is up. If your service supports multiple user sessions on a single browser, make sure you let the installing user choose which account they want to use when installing your app on their Workplace community.

We have a basic install round-trip implementation in node.js that you can use for testing:

Install Example on GitHub

Token Security

Access tokens for Workplace don't expire. To ensure the security of customer data, and to ensure that API calls are only ever made from server-side code, an expiring app-secret proof will be required along with a customer's access token when making API calls.

To generate an expiring app-secret proof, you'll need to concatenate your customer's access token with a unix timestamp, separated by a pipe symbol |, then create a SHA-256 hash of the concatenated string, using your app secret as the key. Here's an example in PHP:

$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret); 

To make API calls with your app-secret proof, pass the generated hash via the appsecret_proof parameter, along with the appsecret_time set to the timestamp you used when hashing the app secret, along with your access token.


Time-stamped app secret proofs will be considered expired after 5 minutes, so it's recommended that you generate a new proof in-line when making each Graph API call.

Verifying your Install

You may want to start with a verification call to check which community the token belongs to. You could do this as follows:


Workplace App Installation Model

Your app will only have one access token per installed community, but the scope of the groups and users that are visible is dynamic based on the installation configuration.

Exploring API Functionality with Postman

Postman is a widely used tool for working with web APIs. You may find it convenient to explore the Workplace API using Postman, but the $appsecret_proof parameter presents a complication - since this value must be calculated and expires after five minutes, it would simplify matters if Postman could generate the value at request time. In fact Postman can do so using its Prerequests Scripts & Params features. This script can be used as a starting point:

// Add to Postman's Pre-request Script Tab
var access_token = "replace-me";
var app_secret = "replace-me";
var time = (new Date().getTime()/1000|0);
postman.setEnvironmentVariable("access_token", access_token)
postman.setEnvironmentVariable("appsecret_time", time);
postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));

Available Functionality

Third-party apps enjoy most of the same API access as custom integrations. This means that if you've built a custom integration for your own Workplace community, it should be easy to port the code to allow it to be installed on other Workplace communities.


Third-party apps can request most of the same permissions as custom integrations. There are two notable omissions:

  • Third-party apps can't request Impersonate permissions
  • Third-party apps can't request Workplace Security permissions yet, but this is coming soon


All webhook payloads will now include a community ID, allowing you to use a single webhook callback URL across all community installs.

You'll need to subscribe for webhooks programmatically, as we don't have a UI for managing subscriptions on third-party apps. You can do this via the /app/subscriptions edge on Graph API, which requires your app's own app access token in the format "{app_id}|{app_secret}".


Webhook subscriptions only need to be configured once per app. It's not necessary to set up new subscriptions for each customer install.

Refer to our custom integration documentation for a comprehensive list of Webhook topics and fields available for subsciption

Workplace validates any changes to your webhook subscription changes against the callback URL you supply.

App-Scoped User IDs

When making API calls to fetch user info, you'll receive IDs that are scoped to your app. This means that the user ID for a user on Workplace is different to the ID for that user seen on the Graph API.

If you need to match a Workplace user to their account on your app, you can use email addresses as a shared identity. Most of the time, the email address will be the same across multiple systems.

Review Process

Before your integration will be made available to customers, it will be subject to review, where its features will be checked against the Workplace Platform Policies and assessed on general app quality.

While you should spend some time reading the full policy document, below are some guidelines to help you prepare for review as you develop your app.


Build integrations that make Workplace a safer and more useful place to collaborate.

Request only the minimum permissions necessary for your integration to be useful.

Follow all relevant local laws and industry regulations.

Provide meaningful customer support for you app, including a way for customers to easily contact you.

Localize your application strings according to the recipient user's locale.


Harvest data from Workplace for use in another tool.

Use contact info (email, phone numbers etc) obtained from Workplace APIs for communication on another channel (e.g. mailing lists).

Emulate Workplace functionality.


Enable circumvention of group / community privacy rules.


Make data obtained from one Workplace Customer available to another Workplace Customer or aggregate data from multiple Workplace Customers together (for example, to create cross-Customer benchmarks or comparisons).

Violate the names or trademarks of other brands.


Message or tag all users once enabled, unless this is an admin-triggered feature of your integration.

Expose Workplace access tokens in any way (e.g. in the UI or in HTTP GET / POST parameters), either during app installation or in your admin surfaces.


  • For bots in Work Chat, use in-built templates and quick replies wherever possible, rather than asking the user for text input.
  • Fail gracefully when a user does something wrong. For example, if a user enters the wrong text input, acknowledge it and let them try again.
  • Respond to an initial message from the user (e.g., with information about the bot), even if the bot isn't designed for user-initiated interaction.
  • Make sure your integration feels responsive. Acknowledge when an action was performed successfully, in the form of a comment reply or message response as appropriate.
  • If your integration lets users create content in other tools, link to that content when it's created, via a comment or a message reply.
  • Try to provide help in-product. For example, if a user asks for help via message, provide them a link to user support at a minimum.
Workplace Platform Policies