Set up a generic OAuth integration

OAuth is a service that is used to grant access to applications without using a password. In FlowBuilder, you can now set up a generic OAuth integration to make authenticated requests to third-party applications.

Requirements

• A MessageBird account

• Flow Builder

• A Teamleader account (optional)

• A Zoho account (optional)

Step one: Create a new configuration

1. Go to the integrations page in your MessageBird Dashboard

2. Under OAuth, click Add integration. A form will appear with fields that you need to fill in to set up a new OAuth2 integration

3. Enter a Name. Choose a descriptive name for this integration that makes it easy to find and identify. This name will be shown in a dropdown in Flow Builder when you use the integration

4. Enter the OAuth client ID. This is the client ID provided by the third-party application. Copy and paste it from the app settings

5. Enter the OAuth client secret. This is the client secret provided by the third-party application. Copy and paste it from the app settings

6. Enter OAuth Scopes. This defines the resources that you will be allowed to access. To determine which scopes you may need, see the documentation of the application you are adding the integration for

7. Enter the OAuth endpoint authorization URL. This Is the URL where you will login to authorize FlowBuilder to access the application. This can be found in the documentation of the application. See Table 1 below for the authorization URLs of some commonly used applications, or copy and paste it from the app settings

8. Enter the OAuth endpoint authorization token. This is the URL that FlowBuilder will call in order to exchange your authorization code with an access token. This can be found in the documentation of the application. See Table 1 below for the authorization tokens of some commonly used applications, or copy and paste it from the app settings. Table 1

   Application	Authorization URL	Authorization Token
   Google	https://accounts.google.com/o/oauth2/auth	https://oauth2.googleapis.com/token
   Zoho	https://accounts.zoho.com/oauth/v2/auth or https://accounts.zoho.eu/oauth/v2/auth (depending on data center)	https://accounts.zoho.com/oauth/v2/token or https://accounts.zoho.eu/oauth/v2/token
   Intercom	https://app.intercom.com/oauth	https://api.intercom.io/auth/eagle/token
   Teamleader	https://app.teamleader.eu/oauth2/authorize	https://app.teamleader.eu/oauth2/access_token

9. Check the User authorization callback URL. This field is automatically filled for you. The authorization callback URL, also called a redirect URL, should be copied and pasted to your application so that after successful login, the application redirects back to MessageBird in order for us to complete the integration setup

10. After filling in the fields and copying the callback URL, click Save to save the configuration

11. Next, you need to authorize the configuration. Click Authorize. You will be taken to the URL that you specified in the OAuth endpoint authorization URL field, where you will be prompted to log in

12. After you've successfully logged in, you'll be asked to give access to the Flow Builder application. Confirm this access, then you will be redirected back to the Integrations page to complete set up

13. If your application has been successfully authorized, you'll see a banner reading "All set! Your authorization is complete!". Click Save and finish. Now, when you go to Flow Builder, you'll be able to use this integration! 🎉

Step two: Using the integration in Flow Builder

You can use the generic OAuth integration in the Fetch variables step and the HTTP request step in Flow Builder.

To use OAuth2 integration in one of these steps, go to the step's settings, and select your integration from the OAuth integration dropdown menu.

NOTE: Only authorized integrations will be listed here. Integrations that have been created but not authorized are 'incomplete' and will not be listed here, as they cannot be used.

Use case: Teamleader

Let's take a look at how we would set up a generic OAuth Integration for Teamleader. We want to fetch a contact's last name using the Teamleader contact ID in Flow Builder. Follow these steps to set this up:

1. Go to the Integrations page in your MessageBird Dashboard

2. Under OAuth, click Add integration. A form will appear with fields that you can complete

3. In the Name field, write '"teamleader" so that the integration is easy to find later

4. Now, we need to find the Client ID and the Client secret by creating an integration in Teamleader. Start by going to the Teamleader Marketplace

5. Click Create new integration and enter a name, such as "flows"

6. Once you've created the integration, you'll be able to see the Client ID and the Client secret, as well as an input field for valid redirect URLs. Leave this empty for now, as we will come back to it in Step 12

   
7. Copy the Client ID and Client secret from Teamleader, and paste them into their respective fields in the OAuth integration form back in your MessageBird Dashboard. Don't close the page yet! There are still a few more things we need to do

8. In the OAuth scopes field, we'll need to enter a scope, which will allow us to fetch contact information from Teamleader. This scope is called 'contacts', so enter contacts into the scopes field. To choose the contacts scope from Teamleader, we'll also need to select the contacts checkbox in OAuth scopes, as shown in the image below

   
9. Next, we'll need to fill in the OAuth endpoint authorization URL and OAuth endpoint authorization token fields in the OAuth integration form. To get these values, refer to the Teamleader API documentation

10. Enter this URL in the OAuth endpoint authorization URL field: https://app.teamleader.eu/oauth2/authorize

11. Enter this URL in the OAuth endpoint authorization token field: https://app.teamleader.eu/oauth2/access_token

12. You’ll see that the User authorization callback URL field is already filled for you. Copy this URL and paste it into the Valid redirect URLs field in the Teamleader marketplace integration page that we left empty in Step 6

13. Click Save changes in the Teamleader marketplace. The OAuth integration form should now look like this:

    
14. Click Save to save the integration

15. Click Authorize, and you'll be redirected to the Teamleader application. Login to Teamleader, grant access to Flow Builder, and you'll be redirected back to the Integrations page on the MessageBird Dashboard, where you'll see a banner that lets you know that your integration is complete! Click Save and finish. Congratulations, your integration is set up! 🎉

    
16. Now the OAuth integration is set up, we can use it to make authenticated requests from Flow Builder. Configure it as follows:

    
17. Go to Flow Builder and create or edit a flow with a Fetch variables step

18. Add https://api.teamleader.eu/contacts.info?id={{id}} into the URL field. For this to work, you will need to set up a flow to ask users to enter a Teamleader contact ID

19. Select the Teamleader integration from the Select OAuth integration drop-down menu

20. We can see in the Teamleader documentation that the response will have a last_name field nestled under data. This can be used to reply to the user with the last name that is fetched from Teamleader. To start the flow, send a conversation message:

    
21. As you can see from the screenshot above, FlowBuilder was able to make an authenticated request to Teamleader without requiring your credentials when invoking the flow! 🎉

Use case: Zoho

For Zoho, you can extract the information that you need from the following articles:

• Go to https://www.zoho.com/crm/developer/docs/api/v2/scopes.html to get the proper scope definition. For each API that you access, you will need to have the proper scope. For example, if you want to access https://www.zoho.com/crm/developer/docs/api/v2/get-org-data.html then you need to add the ZohoCRM.org.ALL or ZohoCRM.org.READ scopes

• Go to https://www.zoho.com/crm/developer/docs/api/v2/register-client.html to create the needed client on the Zoho side (a Server-based Applications application is needed)

• Go to https://www.zoho.com/crm/developer/docs/api/v2/access-refresh.html to get the link for the authorization token URL

• Go to https://www.zoho.com/crm/developer/docs/api/v2/refresh.html to get the link for the refresh URL

See how we've set up the Zoho app configuration. The redirect URL is the one copied from the Message Bird OAuth integration definition page.

Troubleshooting Zoho OAuth integration

Zoho operates multiple data centers, that cannot communicate with each other, so if your organization is on zoho.eu, you must replace all of the links in their documentation .eu links

This applies to both the OAuth configuration, OAuth endpoint authorization URL: https://accounts.zoho.com/oauth/v2/auth becomes https://accounts.zoho.eu/oauth/v2/auth and to the actual links you are calling at runtime https://www.zohoapis.com/crm/v2/org becomes https://www.zohoapis.eu/crm/v2/org