Third Party Integrations for Workplace

Introduction

While Custom Integrations allow Workplace customers to build bots within their community, third party integrations can be installed on multiple Workplace communities.

We show third party integrations to Workplace customers in the Integrations Directory, where system admins can install and enable them.

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.

Integrations and Workplace Community Relationships

This diagram illustrates the high level entities and relationships between third party integrations and Workplace communities into which they are installed.

Integrations have their own metadata and configuration. Integrations are installed into Workplace communities with a scope: whole community or selected groups.

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.
  3. When the installation is complete on your site, you should redirect back to work.facebook.com/work/install_done_redirect/ so that Workplace can mark the installation as complete and cleanup the popup window.

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. You may optionally pass in a state query parameter, which if supplied, Workplace will return to you on the return redirect.
  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.
  5. When the installation is complete on your site, you should redirect back to work.facebook.com/work/install_done_redirect/ so that Workplace can mark the installation as complete and cleanup the popup window.

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. Start by redirecting here:

https://work.facebook.com/work/admin/?section=apps&app_id={your-app-id}&state={optional-state-parameter}

The state parameter is optional. If supplied, Workplace will pass you back the value verbatim without any processing or validation.

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:

GET https://graph.facebook.com/v2.9/oauth/access_token?
   client_id={app-id}
   &redirect_uri={redirect-uri}
   &client_secret={app-secret}
   &code={code-parameter}

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.

GET https://graph.facebook.com/v2.9/community/groups?
   &access_token={access-token}
   &appsecret_proof={appsecret_proof}
   &appsecret_time={appsecret_time}

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:

GET https://graph.facebook.com/v2.9/community?
   access_token={access-token}
   &appsecret_proof={appsecret_proof}
   &appsecret_time={appsecret_time}

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));
1) Create an active environment (there isn't one by default), then 2) add these three parameters, which are calculated by your pre-request script.

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.

Permissions

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

Webhooks

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}".

POST https://graph.facebook.com/v2.9/app/subscriptions?
   access_token={app_id}|{app-secret}
   &object=page
   &fields=message_deliveries,messages,messaging_postbacks,messaging_optins
   &include_values=true
   &verify_token={your-verify-token}
   &callback_url={your-callback-url}

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

Handling App Uninstalls

Your app must subscribe to receive webhook notifications related to uninstalls. You can subscribe to this webhook using the developer dashboard or via a request like this:

POST https://graph.facebook.com/app/subscriptions?
   access_token={app_id}|{app-secret}
   &object=application
   &fields=workplace_uninstall
   &verify_token={your-verify-token}
   &callback_url={your-callback-url}

When a community admin chooses to uninstall your integration, Workplace will send a webhook notification to you.

Like other webhooks, the request will include an x-hub-signature header, which you must use to validate the authenticity of the webhook. The request body will contain your app id and the community id for which the uninstall action took place.

Receipt of this request indicates that you must remove all Workplace customer data and configuration related to this community from your system.

This JavaScript code demonstrates how to verify the authenticity of the uninstall request:

      
app = express().use(body_parser.json({ verify: function(req, res, buf) {
    req.rawBody = buf;
  } })); // creates express http server     
      
app.post('/webhook', (req, res) => {
  const shaSignature = req.get('x-hub-signature');
  if (!shaSignature) {
    // Responds with '403 Forbidden' if no x-hub-signature
    res.sendStatus(403);
    return;
  }
         
  const bodySignature = crypto.createHmac('sha1', process.env.APP_SECRET)
    .update(req.rawBody, 'utf-8')
    .digest('hex');
      
  if ('sha1=' + bodySignature !== shaSignature) {
    res.status(400).send('Invalid signature');
    return;
  } 
  
  // x-hub-signature validation success
  // Proceed with uninstall logic

});
    

Third party apps are required to support and respect workplace_uninstall requests from Workplace and to delete all Workplace customer data within 30 days

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.

Next Steps

Once you're ready to build a third party integration for Workplace, register your interest so that a member of the Workplace team can create an app ID for you to develop with.

You should take some time to read the Workplace platform policy and best practices, and try out some of the existing integrations in our directory to get an idea of what's possible.

Developer AccessWorkplace Integrations Directory