Supporting OAuth authorization

When a user successfully logs into their linked account, the 3rd-party service returns an authorization code which is then exchanged for an access token. The access token is required for subsequent requests to the 3rd-party service.

How this is done depends on the channel. For example obtaining the access token is handled for you on the Apple Business Chat channel (see Overview of account linking for Apple Business Chat) but you need to configure it for other channels such as Web Client and Facebook.

The example given below shows an approach that covers the range of channels supported by Converse.

Session variables

In the Converse session:

  • The authCode variable stores the authorization code returned by OAuth. Note that channels such as Apple Business Chat do not return this code to Converse.
  • The accessToken variable stores the access token. Converse obtains the access token in exchange for the authorization code. Apple Business Chat will obtain the access token and return it to Converse.


The following example shows how to set up authentication in such a way that both Web Client and Facebook are supported.

The following example shows out to set up authentication in such a way that all channels are supported (Web Client, Facebook and Apple Business Chat).

Some details about these interactions are given below:

Interaction Description
Account Link The account linking process starts with this interaction which provides an Account Link button. After a successful login on the Facebook or Web Client channels, the OAuth server returns an authorization code to Converse.
Is Authenticated? The interaction tests whether there's an access token in the session. The condition in this action uses the Is Not Empty operator for this.
  • If no access token exists then the bot runs the Authentication action that will request an access token.

    This action is set as part of the condition on the Settings tab.

  • If an access token exists then the bot goes to the next step (in this example Get user info).

    This interaction is set as the Next action on the Details tab – it's the default action that runs whenever the condition isn't met.

Get Access Token The interaction that requests the OAuth server for an access token. It passes the authorization code (authCode) in the body of the request and saves the returned token in the accessToken variable.
Note: If the user hasn't logged on yet (there's no authorization code in the session) then the user is prompted to log in. The interaction to go to is set in the Go here if not logged in field on the Advanced tab.
Get user info In this example, the next interaction.