Develop a Third Party App for Workplace

Introduction

While Custom Integrations allow Workplace customers to access APIs within their own community, only Third Party Apps are allowed to act as SaaS integrations that can be installed by multiple Workplace customers.

Our platform policies prohibit SaaS and PaaS products from integrating with Workplace via Custom Integrations; these products must instead use Third Party apps and pass our review processes.

If you don't have a third party app yet, you can submit an app creation request.

Workplace Third Party App Technology

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. This page describes the basic concepts you'll need to be familiar with to develop a Workplace integration and provides guidance about our policies and best practices.

App Administration

Workplace apps are managed using developers.facebook.com/apps. When you submit your app creation request, you will specify one or more of your company's personnel to be admins of your app. Your app admin can also add and remove other individuals as Developers on your app. Refer to our developer documentation if you want to know more about app roles.

App roles can only be assigned to Facebook (as opposed to Workplace) user accounts.

Permissions

Third-party apps can request most of the same permissions as custom integrations. There is only one difference:

App Installation

Workplace customers add you app to their instance via an installation flow, which is described in detail below.

API Credentials

When you make API calls to the Workplace Graph API, you must supply API credentials, referred to as access tokens. There are two kinds:

  1. App access token - Your app has an access token, which is used primarily when you manage webhook subscriptions. Unlike an installation access token, of which there is one per installation, there is only one app access token for your app. The format of an app access token is {app_id}|{app_secret}, where you can find the app_id and app_secret values at developers.facebook.com/apps/. This token does not expire automatically, but you can rotate the app_secret using the app dashboard if you desire.

  2. Workplace installation access token - this is the most commonly-used type of access token. You receive one token for each installation of your app by a Workplace admin. These tokens are valid as long as your app installation remains active.

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, a short-lived app-secret proof is required along with a customer's access token when making API calls.

You must store and use your API Credentials only in your own server environment and ensure that these values are never copied or transmitted elsewhere, e.g., to mobile apps or web browser clients.

Graph API

Webhooks

Webhooks provide the capability of sending your app notifications when a relevant event happens within Workplace.

  1. Start by creating event processing handlers in your system
  2. Then register subscriptions for the events that are pertinent to your app
  3. Once your app is installed by Workplace admins, you will start to receive POST requests for each relevant event

We recommend subscribing to webhooks programmatically via the /app/subscriptions edge on Graph API. Remember to use your App access token for these invocations. Here's an example for a Chat Bot subscribing to the page object:

POST https://graph.facebook.com/v3.3/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.

All webhook payloads include a community ID, allowing you to correlate the payload of the request with the associated customer.

Note: If you need to modify your Page webhook subscriptions after your app goes live, be aware that these changes will not automatically be effective for pre-existing installs of your app. In this case, you will need to subscribe each existing install to the new fields for the page object as well. Here's an example:

POST https://graph.facebook.com/v3.3/{page-id}/subscribed_apps?
subscribed_fields=messages

Further details are available on the /page/subscribed_apps reference docs.

To learn more about webhooks, refer to our reference documentation for a comprehensive list of Webhook topics and fields.

App Uninstalls

The Workplace Platform Terms mandate that your app must always be subscribed to the workplace_uninstall event, which will send you a notification if a Workplace admin decides to uninstall your app.

To subscribe to this webhook event, send a POST request like this:

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

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

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});

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.

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 within Workplace is different than the ID your app gets for that user via the Graph API and webhooks.

If you need to match a Workplace user to their account on your app, you may be able to use email addresses as a shared identity. Alternatively, you can build an account-linking flow using Work Chat.

App Installation

Only Workplace System Admins can install third party integrations. Installations can either be initiated from your website, referred to as Developer-Initiated Installation, or from the Workplace Integration Directory (if your app qualifies for inclusion there), referred to as Workplace-Initiated Installation. In either case, a successful installation results in you having obtained an access token granting you permission to call Workplace's APIs on behalf of that customer.

This section describes the flows you are required to support, depending on your app's configuration.

I. Configure Your App Redirect URL

This step pertains to all third party apps.

  1. Open your app's Facebook Login Details page: https://developers.facebook.com/apps/{app-id}/fb-login/settings/
  2. Input a single redirect_url into the Valid OAuth Redirect URIs field - this is the URL we will redirect Workplace System Admins to when they choose to install this integration

IIa. Developer-Initiated Installation, For Apps Limited to One-Install Per Customer

This flow 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. If not, the installation attempt will fail here.
  4. On the System Administrator's consent, 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 then fetching and securely storing an access token before 300 seconds elapses. If more than 300 seconds elapses, the code parameter will have expired and you should prompt the user to retry by starting step #2 again.
  5. Finally, when the installation is complete on your site, you should redirect the user to work.facebook.com/work/install_done_redirect/ so that Workplace can mark the installation as complete and cleanup the popup window.

For step #2, redirect or hyperlink users to this destination:

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.

IIb. Developer-Initiated Installation, For Apps with Whitelabeling enabled

This flow applies to apps that can be installed multiple times per Workplace instance along with apps that can be renamed upon installation.

This flow 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, passing an array of requested app permissions as query parameters. You may also 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. If not, the installation attempt will fail here.
  4. On the System Administrator's consent, 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 then fetching and securely storing an access token before 300 seconds elapses. If more than 300 seconds elapses, the code parameter will have expired and you should prompt the user to retry by starting step #2 again.
  5. Finally, when the installation is complete on your site, you should redirect the user to work.facebook.com/work/install_done_redirect/ so that Workplace can mark the installation as complete and cleanup the popup window.

For step #2, redirect or hyperlink users and pass in the required parameters following this pattern:

GET work.facebook.com/v3.3/dialog/work/app_install/
?app_id={app-id}
&redirect_uri={redirect_uri}
&permissions={permission1},{permission2}
&suggested_page_name={app_name}
&state={state}

Example

GET work.facebook.com/v3.3/dialog/work/app_install/
?app_id=1895498094091945
&redirect_uri=https://app.integration.com/install
&permissions=bot_mention,message
&suggested_page_name=Great bot
&state=tytvvvsdtthsd

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

IIc. Workplace-Initiated Installation, For Apps Limited to One-Install Per Customer

Certain featured apps will be shown within the Workplace Admin Panel or Integration Directory. In this case, a System Admin may begin installation within Workplace:

  1. A System Administrator starts by finding your app in the Integrations tab of their Admin Panel or within the Workplace Integration Directory. In either case the user can click an 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.

III. Getting an Access Token

Irrespective of how the installation flow is initiated, you need to exchange the code parameter for an access token to complete the installation. 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.

To get the access token:

  1. Make a GET request to our /oauth/access_token endpoint
  2. Include the code param that Workplace sent you via redirect during the installation flow
  3. Also include your app-id, app-secret (both found in your' app's basic settings in the app dashboard at /apps/{your-app-id}/settings/basic/, and redirect URI (which you configure at https://developers.facebook.com/apps/{app-id}/fb-login/settings/):
GET graph.facebook.com/v3.3/oauth/access_token?
        client_id={app-id}
        &redirect_uri={redirect-uri}
        &client_secret={app-secret}
        &code={code-parameter}

When this call completes successfully, Workplace considers the installation complete. According to the permissions of your app, you will now be able to make API invocations and Workplace will immediately begin sending relevant webhooks to you for this Workplace instance.

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

IV. Verifying your Install

You may want to start with a verification call to check which community the token belongs to, which you can do by making a request like this:

GET graph.facebook.com/v3.3/community?
        fields=install
        &access_token={access-token}
        &appsecret_proof={appsecret_proof}
        &appsecret_time={appsecret_time}

This will return data in the following format:

{
    "install": {
        "install_type": {install_type}, //full community or just some groups
            "permissions": {granted_permissions}, //list of granted permissions for this install
            "id": {install_id}
        },
    "id": {community_id}
}

Use the /me endpoint to get the page ID for the install. The page ID will be included in webhooks associated to that page (e.g. message and mentions)

GET graph.facebook.com/v3.3/me?
        &access_token={access-token}
        &appsecret_proof={appsecret_proof}
        &appsecret_time={appsecret_time}

This will return data in the following format:

{
    "name": {page_name},
    "id": {page_id}
}

V. Permissions elevation

An app with Whitelabeling enabled can use the permissions elevation flow to acquire additional permissions than those granted at install time. This results in the current access token being invalidated and a new access token being created for this install.

GET /v3.0/dialog/work/app_upgrade/?
        install_id={install-id}
        &redirect_uri={redirect-uri}
        &permissions={incremental permissions (comma separated)} //e.g. message,bot_mention
        &state={state} //optional 

When a Workplace System Administrator is directed to this URL, they will be shown a dialogue to confirm the additional permissions. If successful, the user will be redirected to to the redirect_uri specified, with a code provided in the same way as during the install flow. This code must be redeemed immediately for a new access token. There is only a short period after the System Administrator confirms the new permissions when the previous access token will still work.

Policy and Best Practice

All Third Party ISVs must comply with the Workplace Platform Policies, which exist to protect Workplace customers who choose to grant third party access to their data via APIs.

Workplace Platform Policies

While you must understand the whole set of policies, below are some guidelines to consider when developing your app.

DO:

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.

Encrypt all Workplace customer data in transit and at rest.

DO NOT:

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.

Examples

Enable circumvention of group / community privacy rules.

Examples

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.

Examples

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.

Offer your SaaS app to Workplace customers via Custom Integrations.

Share any Workplace customer data with a third party service without the Workplace team's explicity approval.

Allow your Workplace app-uninstall webhook subscription to lapse or allow your uninstall listener to become unstable/unresponsive.

BEST PRACTICES:

  • 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.

Next Steps

When your app development is complete, you'll need to prepare it for app review