Developer Access

Register your interest in launching an integration for our Integrations Directory

Overview

Workplace has an Integrations Directory where customers can discover and install integrations to make Workplace more useful for them. The directory features third party integrations that have been built by developers of enterprise SaaS (Software as a Service) tools, and each integration in the directory has been vetted by the Workplace team before launching to customers.

If you're a developer building an enterprise productivity tool, and you'd like to integrate with Workplace, we want to hear from you! Register your interest today via our contact form, and a member of the Workplace team will get in touch with you to get you up and running.

It is not necessary to register your interest in order to build Custom Integrations.

If you are a system admin in a Workplace Premium community, you can create a custom integration for your community at any time.

Configuring your App

Once you've registered your interest to develop an integration for Workplace, a member of the Workplace team will create an app ID for you that you can use for development.

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 developers.facebook.com/apps.

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")
  • Deauthorization Callback 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.

Requirements for Directory Listing

To be part of the Integrations Directory, you will need to supply the following information:

  • Integration name
  • Developer / publisher Name
  • App logos and icons
  • A subtitle / tagline
  • A description of your integration
  • External links
  • Privacy policy and terms of service page URLs
  • Showcase images or screenshots

More information on what to provide can be found below.

Integration Name

A string which represents your app's name. This will be visible in the directory and wherever your app is referred to. If your integration has a bot, this will also be the bot's name.

Recommended Character Length: 30

Examples:

  • “Dropbox”
  • “Envoy”
  • “Jira”

Developer/Publisher Name

A string that represents your company/organization. Will be used alongside the integration name to help people understand who is responsible for the functionality of the integration.

Recommended Character Length: 30

Examples:

  • “Dropbox, Inc.”
  • “Recognize Services, Inc.”

App Logo & Icons

  • A 1024 x 1024 png. This will be used as the icon image for your integration in the directory, the install dialog and various other places where we need a larger icon. If your integration has a bot, this will also be the bot's icon. We will scale this down to multiple sizes.
  • A 64x64 colour app favicon (transparent PNG). This will be scaled down to 32x32 and 16x16 formats.
  • A 64x64 monochrome (black) app icon (transparent PNG). This will be scaled down to 32x32 and 16x16 formats.
  • Primary Brand Color (hex). This will be used to colorize your app's monochrome icon in certain circumstances and may be user as background/header colour where we promote your integration.

App Subtitle / Tagline

A short sentence description of what your integration does. This will be shown in the directory where we list multiple integrations together, and in the integration install dialog.

Examples:

  • “High quality video conferencing.”
  • “Quick and simple surveys via Chat.”
  • “The new standard for visitor registration.”

Recommended Character Count: 40.

Integration Description

A clear description of what your integration/app does and why people should install/enable it. This will use shown in your integration's directory listing.

Guidance: around 400 characters across up to two paragraphs.

External Links

  • “Learn More” link - a URL where users can go to learn more about what your app/product does and how your integration works. This may be a blog post which details your integration's functionality, or a help center/support article that gives more detail to people on what they can expect once your integration is added to their Workplace. For example:
  • Customer Support URL - A user-facing URL to where users/customers of your integration can go to ask questions and raise bugs.
  • Customer Support Email - A user-facing email address where users/customers of your integration can go to ask questions and raise bugs. Please endeavour to ensure that people receive a a reply within 24 hours. If you're unable to provide that turnaround, you should setup an auto-reply which directs people to another channel where they can file bugs or give feedback about your integration. Our support team will pass this email address to Workplace customers if they contact us about a problem with your integration.

URLs to Privacy Policy and Terms of Service

Two URLs that link directly to your apps Privacy Policy and Terms of Use. These will be user-visible, and will be show on your integration's directory page and on the integration install dialog. Both URLs should reliably resolve to a document that is visible without any authentication (internet-public).

Showcase Images

A set of images that showcase what your integration does. You can include a mix of mobile and desktop screenshots.

You must supply at least 3 images. Maximum of 8.

Each image must be:

  • 800px high
  • between 400px wide (min) and 1000px wide (max)
  • full-bleed PNG

Review Process

Once you've registered your interest to build a Workplace integration, you'll be provided with an app ID and access to a dashboard where you can configure the features your integration will support.

When you're ready to launch your integration, a member of the Workplace team will need to review your app before making it available in the Integrations Directory.

The review process consists of two stages:

  1. Functional Review
  2. Security Review

Functional Review

During Functional Review, your app will be tested for compliance with the Workplace Platform Policy, then given a full functional test on one or more Workplace communities.

As part of the test, we'll verify that your integration uses the minimum number of required permissions to provide the functionality as described, and check that there are no privacy issues with how Workplace information is shown via your integration. You may be given feedback on your integration at this stage.

Security Review

Once your integration passes functional review, Facebook will coordinate with an independent third party security vendor to give your app a security review, checking for common security pitfalls like Cross-Site Scripting (XSS) vulnerabilities.

Only on completion of a successful security review will your integration be launched to our directory.

Policy and Best Practice

As mentioned above, all apps in the directory will be subject to a review against the Workplace platform policies, which have been put in place to protect the security and functionality of Workplace for our customers.

Workplace Platform Policies

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.

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.

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.

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.