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.

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.

Permissions

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

• Third-party apps may not have Impersonate permissions

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.

Graph API

• The Workplace Graph API is an an HTTP-based API that allows you to read, create, update, and delete data within Workplace
• Workplace's Graph API is based upon the same technology as Facebook's Graph API, so most of the concepts are the same. You can learn more about the basics of this API by reading the Graph API Overview and Using the Graph API pages.

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

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
3. Configure app settings as shown below:

Ensure that your app's settings are configured as shown below to ensure that the install process works as expected.

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 link the user to Workplace, opening a pop up window for the install flow. 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 close the popup window using a JavaScript call.

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

https://work.workplace.com/work/admin/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 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 link the user to Workplace, opening a pop up window for the install flow. 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 close the popup window using a JavaScript call.

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

GET work.workplace.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.workplace.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.workplace.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}/workplace/settings/):

NB. The redirect_uri needs to exactly match one of the "Valid OAuth Redirect URIs", as configured in your app's 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
        &app_id={application_id}
        &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.

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

DO:

DO NOT:

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.