formbricks/apps/docs/app/self-hosting/integrations/page.mdx

import { MdxImage } from "@/components/MdxImage";

import CreateNewIntegration from "./images/airtable/create-new-integration.webp";
import OpenDeveloperHub from "./images/airtable/open-developer-hub.webp";
import RegisterNewIntegration from "./images/airtable/register-new-integration.webp";
import SelectScopes from "./images/airtable/select-scopes.webp";

import AddApiKey from "./images/n8n/add-api-key.webp";
import AddDiscord from "./images/n8n/add-discord.webp";
import AddFormbricksTrigger from "./images/n8n/add-formbricks-trigger.webp";
import CreateNewCredentialBtn from "./images/n8n/create-new-credential-btn.webp";
import DiscordResponse from "./images/n8n/discord-response.webp";
import FillDiscordDetails from "./images/n8n/fill-discord-details.webp";
import ListenForEvent from "./images/n8n/listen-for-event.webp";
import SelectEvent from "./images/n8n/select-event.webp";
import SelectSurvey from "./images/n8n/select-survey.webp";
import SelectedSurveys from "./images/n8n/selected-surveys.webp";
import SubmitTestResponse from "./images/n8n/submit-test-response.webp";
import SuccessConnection from "./images/n8n/success-connection.webp";
import TestResponseSuccess from "./images/n8n/test-response-success.webp";

import AddNewZap from "./images/zapier/add-new-zap.webp";
import ChooseEvent from "./images/zapier/choose-event.webp";
import ConnectWithFB1 from "./images/zapier/connect-with-formbricks-1.webp";
import ConnectWithFB2 from "./images/zapier/connect-with-formbricks-2.webp";
import SuccessConnectionZapier from "./images/zapier/success-connected.webp";

export const metadata = {
  title: "Setting up Integrations for Self Hosted Formbricks",
  description: "Configure third-party integrations with your self-hosted Formbricks instance.",
};

# Integrations

### Overview

We have step-by-step guides to configure our third-party integrations with a self hosted Formbricks instance. We currently support the below integrations, click on them to see their individual guides:

- [Airtable](#airtable)
- [Google Sheets](#google-sheets)
- [Notion](#notion)
- Make: We do not support for self-hosted instances yet.
- [n8n](#n8n)
- [Slack](#slack)
- Wordpress: Wordpress setup is similar to the [Cloud setup](/developer-docs/integrations/wordpress), just change the API Host to your self-hosted URL.
- [Zapier](#zapier)

<Note>
  {" "}
  Once you’ve configured your integration, See our Integration sections to see how to use them within your Formbricks
  app [here](/developer-docs/integrations/airtable)
</Note>

### Step by Step Guides

## Airtable

Enabling the Airtable Integration in a self-hosted environment requires creating an airtable account and changing the environment variables of your Formbricks instance.

1. Go to the [Airtable](https://airtable.com) and create a new account if you dont already have one.

2. Click on user icon on top left and open to **Developer hub**

<MdxImage
  src={OpenDeveloperHub}
  alt="List of linked tables"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

3. Navigate to OAuth integrations and click on **Register an OAuth integrations**

<MdxImage
  src={CreateNewIntegration}
  alt="List of linked tables"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

3. Select a name for you integration and also add a redirect URL which will be `<YOUR_WEBAPP_URL>/api/v1/integrations/airtable/callback`

   <MdxImage
     src={RegisterNewIntegration}
     alt="List of linked tables"
     quality="100"
     className="max-w-full rounded-lg sm:max-w-3xl"
   />

4. Now fill some basic details about your integrations and then go to scope section. You need to **enable** 5 scopes:

   - data.records:read
   - data.records:write
   - schema.bases:read
   - schema.bases:write
   - user.email:read

<MdxImage
  src={SelectScopes}
  alt="List of linked tables"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

5. Click on the "Save" button and you are done
6. Now just copy **Client ID** for your integration & add it to your **Formbricks environment variables** as in the docker compose file:

- `AIRTABLE_CLIENT_ID`

Voila! You have successfully enabled the Airtable integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Airtable Integration with Formbricks](/developer-docs/integrations/airtable) section to link an Airtable with Formbricks.

## Google Sheets

Integrating Google Sheets with a self-hosted Formbricks instance requires configuring Google Cloud and updating your environment variables.

1. Go to the **[Google Cloud Console](https://console.cloud.google.com/)** and **create a new project**.
2. Enable necessary APIs:
   - Now select the project you just created and go to the **APIs & Services** section.
   - Click on the **Enable APIs and Services** button and search for **Google Sheets API** and enable it.
3. Configure OAuth Consent Screen:
   - Go to **OAuth Consent screen** and select the appropriate User Type (External or Internal). Select **Internal** if you want only the users of your Google Workspace to be able to use the integration.
   - Fill the required details:
     - App name: Name displayed during OAuth authentication.
     - User support email and Developer contact information: Your contact details for support.
   - Click on **Save and Continue**.
4. Add required Scopes:

- Click on the **Add or Remove Scopes** button and add the scopes:
  - `https://www.googleapis.com/auth/userinfo.email`
  - `https://www.googleapis.com/auth/spreadsheets`
- Click on the **Update** button. Verify the scopes and click on the **Save and Continue** button.
- Skip the **Test Users** section and click on the **Save and Continue** button.

5. View the OAuth Consent Screen summary and click on the **Back to Dashboard** button.
6. Register OAuth Client:

- Navigate to **Credentials** > **Create Credentials** > **OAuth Client ID**.
- Select **Web Application** and set:
  - Name: Name of the OAuth Client ID.
  - Authorized JavaScript Origins: `https://<your-public-facing-url>`
  - Authorized redirect URIs: `https://<your-public-facing-url>/api/google-sheet/callback`
- Save and note the Client ID and Client Secret.

7. Copy the Client ID and Client Secret and set them as environment variables in your Formbricks instance:
   - `GOOGLE_SHEETS_CLIENT_ID`
   - `GOOGLE_SHEETS_CLIENT_SECRET`
   - `GOOGLE_SHEETS_REDIRECT_URL`

Now just copy **GOOGLE_SHEETS_CLIENT_ID**, **GOOGLE_SHEETS_CLIENT_SECRET** and **GOOGLE_SHEETS_REDIRECT_URL** for your integration & add it to your **Formbricks environment variables** as in the docker compose file:

- `GOOGLE_SHEETS_CLIENT_ID`
- `GOOGLE_SHEETS_CLIENT_SECRET`
- `GOOGLE_SHEETS_REDIRECT_URL`

Voila! You have successfully enabled the Google Sheets integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Google Sheets Integration with Formbricks](/developer-docs/integrations/google-sheets) section to link a Google Sheet with Formbricks.

## Notion:

Enabling the Notion Integration in a self-hosted environment requires a setup using Notion account and changing the environment variables of your Formbricks instance.

1. Sign up for a **[Notion](https://www.notion.so/)** account, if you don't have one already.
2. Go to the **[my integrations](https://www.notion.so/my-integrations)** page and click on **New integration**.
3. Fill up the basic information like **Name**, **Logo** and click on **Submit**.
4. Now, click on **Distribution** tab on the sidebar. A text will appear which will ask you to make the integration public. Click on that toggle button. A form will appear below the text.
5. Now provide it the details such as requested. Under **Redirect URIs** field:
   - If you are running formbricks locally, you can enter `http://localhost:3000/api/v1/integrations/notion/callback`.
   - Or, you can enter `https://<your-public-facing-url>/api/v1/integrations/notion/callback`
6. Once you've filled all the necessary details, click on **Submit**.
7. Now just copy from the screen the **Client ID** and **Client secret** for your integration & add it to your **Formbricks environment variables** as in the docker compose file:
   - `NOTION_OAUTH_CLIENT_ID` - OAuth Client ID
   - `NOTION_OAUTH_CLIENT_SECRET` - OAuth Client Secret

Voila! You have successfully enabled the Notion integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Notion Integration with Formbricks](/developer-docs/integrations/notion) section to link your Notion with Formbricks.

## n8n

Enabling the n8n integration in a self-hosted environment requires a new workflow setup using n8n and changing the environment variables of your Formbricks instance.

1.Setup your n8n workflow: Go to [n8n.io](https://n8n.io) and create a new workflow. Search for “Formbricks” to get started:

<MdxImage
  src={AddFormbricksTrigger}
  alt="Add Formbricks Trigger"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

2.Connect Formbricks with n8n: Now, you have to connect n8n with Formbricks via an API Key:

<MdxImage
  src={CreateNewCredentialBtn}
  alt="Create new credential button"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

3. Click on Create New Credentail button to add your host and API Key

<MdxImage
  src={AddApiKey}
  alt="Add host and api key"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Now you need an API key. Please refer to the [API Key Setup](/additional-features/api#how-to-generate-an-api-key) page to learn how to create one.

Once you copied it in the API Key field, hit Save button to test the connection and save the credentials.

<MdxImage
  src={SuccessConnection}
  alt="Successful Connection"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

4. Select Event: Next, you can choose the event you want to trigger the node on. You can select multiple events:

<MdxImage src={SelectEvent} alt="Select Event" quality="100" className="max-w-full rounded-lg sm:max-w-3xl" />

Here, we are adding `Response Finished` as an event, which will trigger when the survey has been filled out.

5. Select Survey: Next, you can choose from all the surveys you have created in this environment. You can select multiple surveys:

<MdxImage
  src={SelectSurvey}
  alt="Select Survey"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Here, we are selecting two surveys.

<MdxImage
  src={SelectedSurveys}
  alt="Selected Surveys"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

6. Test your trigger: In order to set up n8n you'll need a test response in the selected survey. This allows you to select the individual values of each response in your workflow. If you have Formbricks running locally and you want to set up an app survey, you can use our [Demo App](/contributing/demo) to trigger a survey and submit a response.

<MdxImage
  src={SubmitTestResponse}
  alt="Submit Test Response"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Next, click on Listen for event button.

<MdxImage
  src={ListenForEvent}
  alt="Listen for event"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Then, go to the survey which you selected. Fill it out, and wait for the particular event to trigger (in this case it's `Response Finished`). Once the event is triggered you will see the response that you filled out in the survey.

<MdxImage
  src={TestResponseSuccess}
  alt="Test Response Success"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Now you have all the data you need at hand. The next steps depend on what you want to do with it. In this tutorial, we will send submissions to a discord channel:

7. Add discord to your workflow: Click on the plus and search `Discord`.

<MdxImage src={AddDiscord} alt="Add Discord" quality="100" className="max-w-full rounded-lg sm:max-w-3xl" />

Fill in the `Webhook URL` and the `Content` that you want to receive in the respective discord channel. Next, click on `Execute Node` button to test the node.

<MdxImage
  src={FillDiscordDetails}
  alt="Fill Discord Details"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Once the execution is successful, you'll receive the content in the discord channel.

<MdxImage
  src={DiscordResponse}
  alt="Discord Response"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Voila! You have successfully enabled the n8n integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Formbricks](/developer-docs/integrations/n8n) Integrations section to know more about the capabilities with Formbricks with n8n.

## Slack

Enabling the Slack Integration in a self-hosted environment requires a setup using slack workspace account and changing the environment variables of your Formbricks instance.

<Note> Make sure your self hosted Formbricks instance works with SSL as Slack requires it. </Note>

1. Create a Slack workspace if you don't have one already.
2. Go to the [Your apps](https://api.slack.com/apps) page and **Create New App**.
3. Click on **From Scratch** and provide the **App Name** and select your workspace in **Pick a workspace to develop your app in:** dropdown. Click on **Create App**.
4. Go to the **OAuth & Permissions** tab on the sidebar and add the following **Bot Token Scopes**:

   - `channels:read`
   - `groups:read`
   - `chat:write`
   - `chat:write.public`
   - `chat:write.customize`

5. Add the **Redirect URLs** under **OAuth & Permissions** tab. You can add the following URLs:

   - If you are running formbricks locally, you can enter `https://localhost:3000/api/v1/integrations/slack/callback`.
   - Or, you can enter `https://<your-public-facing-url>/api/v1/integrations/slack/callback`

6. Now, click on **Install to Workspace** and **Allow** the permissions.
7. Go to the **Basic Information** tab on the sidebar and copy the **Client ID** and **Client Secret**. Copy them & add it to your **Formbricks environment variables** as in the docker compose file:

- `SLACK_CLIENT_ID` - OAuth Client ID
- `SLACK_CLIENT_SECRET` - OAuth Client Secret

8. Now, you need to enable the public distribution of your app. Go to the **Basic Information** tab and click on the **Manage distribution** button and click on the "Distribute App".
9. Scroll down to the **Share your app with other workspaces** section, complete the checklist and click on the **Activate public distribution** button.

Voila! You have successfully enabled the Slack integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Slack Integration](/developer-docs/integrations/slack) section to link a Slack workspace with Formbricks.

## Zapier

1. Setup your Zap: Go to [zapier.com](https://zapier.com/) and create a new Zap. Search for “Formbricks” to get started:

<MdxImage src={AddNewZap} alt="Add New Zap" quality="100" className="max-w-full rounded-lg sm:max-w-3xl" />

Then, choose the event you want to trigger the Zap on:

<MdxImage src={ChooseEvent} alt="Choose Event" quality="100" className="max-w-full rounded-lg sm:max-w-3xl" />

1. Connect Formbricks with Zapier: You have to connect Zapier with Formbricks via an API Key:

<MdxImage
  src={ConnectWithFB1}
  alt="Connect with Formbricks - 1"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>
<MdxImage
  src={ConnectWithFB2}
  alt="Connect with Formbricks - 2"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Now you need an API key. Please refer to the [API Key Setup](/developer-docs/rest-api##how-to-generate-an-api-key) page to learn how to create one.

Once you copied it in the newly opened Zapier window, you will be connected:

<MdxImage
  src={SuccessConnectionZapier}
  alt="Successful Connection"
  quality="100"
  className="max-w-full rounded-lg sm:max-w-3xl"
/>

Voila! You have successfully configured Zapier to work with your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Zapier Integration](/developer-docs/integrations/zapier) section to connect it with your Formbricks app and see it live.

---