Publish an app to Workplace

Workplace by Facebook is a powerful tool to communicate and interact with employees at work. Adding apps to your workplace community can add great value for several scenarios.

There are two ways to integrate any app with Workplace:

  •  Custom Integrations
  •  Third Party Apps

Basically, It depends on our requirement, which one we need to choose for app development.

With Custom integration, the installed app will be available in a specific community only. App developers can control the distribution of the app, it is more suitable where we have only a handful of clients with a B2E onboarding setup.

Alternatively, when an app is published as a Third-party App, it will be discoverable to all workplace communities. Community admin can just browse for apps and install them (more like a self-service model)

In this article, we will talk about Custom Integrations

Custom Integrations :

Log in with your Workplace community credentials. On the home page, click on the Admin Panel icon from the sidebar. Then go to the Integrations tab.

On the Integrations page, you will see the Custom Integrations section.

Clicking on Create Custom Integration button, a popup will appear.

After creating, you will be redirected to the app page.

Now, we can see the App Id & App Secret row, and Create Access Token button. We will come back to this point later. First, let’s configure our Webhooks ( we can see in the sidebar section)

So, Webhooks basically are the API endpoints, which we will use when some action happens on our app.

In this article, we will be focusing on page events.

Now, let’s configure webhooks

In the callback URL, we will add our API endpoint, which will trigger the page events.

  • Let say, we named our endpoint as – “your-api-end-point.com/webhooks/page”
  • So, on above endpoint we will receive a GET method and POST method request
  • On GET method, we will implement our verification part
  • on POST method, we will implement our action part.

In the Verify token, we can use a secret key, through which we will validate our request is coming through Workplace.

Store the verified token in DB or any secret place. Now let’s write an endpoint to verify the requests.

Below is the GET endpoint(“webhooks/page”) written in Nest JS (Node JS framework).

    /**
     * Called by Workplace when request for page events subscription is sent.
     * @param hubMode
     * @param hubVerifyToken
     * @param hubChallenge - a specific token sent by Workplace present in hub.challenge query param. If this is not returned, subscription fails.
     * @returns hubChallenge
     */
    @Get()
    verifySubscription(
        @Query('hub.mode') hubMode: string,
        @Query('hub.verify_token') hubVerifyToken: string,
        @Query('hub.challenge') hubChallenge: string
    ): string {
        if (
            hubMode === 'subscribe' &&
            hubVerifyToken === workplaceConfig.workplaceSubscriptionVerifyToken
        ) {
            return hubChallenge;
        } else {
            this.logHelperService.logError(
                'Failed workplace subscription validation for page event. Make sure the validation tokens match.',
                new Error()
            );
            throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
        }
    }

The above request is GET, which will be used for verification.

And now, we can add another endpoint with the POST method, on which we will receive the request body from Workplace. To send back responses to our Workplace app, we need to use the Workplace graph API.

We will be needing an app secret key and access token for graph API.

Below is the request URL to send a response to Workplace :

 const appsecretTime = Math.floor(Date.now() / 1000);
 const appsecretProof = crypto
            .createHmac('sha256', appSecret)
            .update(workplaceAccessToken + '|' + appsecretTime)
            .digest('hex'); 


const apiUrl = "https://graph.facebook.com/v3.3/" + 'me/messages?' + 'access_token=' + workplaceAccessToken
                + '&appsecret_proof=' + appsecretProof
                + '&appsecret_time=' + appsecretTime;

Here are some references, for more details about Workplace app integration

Found this relevant to your business?

If you need any additional details in this regard then feel free to chat with our live agent at impledge.com

Thank you !!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s