> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typebot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> [!NOTE]
>
> If you're self-hosting Typebot, [sponsoring
> me](https://github.com/sponsors/baptisteArno) is a great way to give back to
> the community and to contribute to the long-term sustainability of the
> project. It also comes with some perks like priority support and private
> workshops. ❤️

Parameters marked with \* are required.

## General

| Parameter | Default | Description |
| - | - | - |
| DATABASE\_URL \* | | The database URL |
| ENCRYPTION\_SECRET \* | | A 256-bit key used to encrypt sensitive data. It is strongly recommended to [generate](https://docs.typebot.com/self-hosting/deploy/docker.md#2-add-the-required-configuration) a new one. The secret should be the same between builder and viewer. |
| NEXTAUTH\_URL \* | | The builder base URL. Should be the publicly accessible URL (i.e. `https://typebot.domain.com`) |
| NEXT\_PUBLIC\_VIEWER\_URL \* | | The viewer base URL. Should be the publicly accessible URL (i.e. `https://bot.domain.com`) |
| ADMIN\_EMAIL | | The email that will get an `UNLIMITED` plan on user creation. The associated user will be able to bypass database rules. You can provide multiple emails separated by a comma without spaces. |
| DEFAULT\_WORKSPACE\_PLAN | FREE | Default workspace plan on user creation or when a user creates a new workspace. Possible values are `FREE`, `STARTER`, `PRO`, `LIFETIME`, `UNLIMITED`. The default plan for admin user is `UNLIMITED` |
| DISABLE\_SIGNUP | false | Disable new user sign ups. Invited users are still able to sign up. |
| NEXT\_PUBLIC\_ONBOARDING\_TYPEBOT\_ID | | Typebot ID used for the onboarding. Onboarding page is skipped if not provided. |
| TYPEBOT\_DEBUG | false | If enabled, the server will print valuable logs to debug config issues. |
| NEXT\_PUBLIC\_BOT\_FILE\_UPLOAD\_MAX\_SIZE | | Limits the size of each file that can be uploaded in the bots (i.e. Set `10` to limit the file upload to 10MB) |
| CHAT\_API\_TIMEOUT | | The chat API execution timeout (in ms). It limits the chat API exection time. Useful to avoid getting stuck into an unwanted infinite loop. Note that it does not apply to known long-running blocks like OpenAI or else. |

For previews, the first URL in `NEXT_PUBLIC_VIEWER_URL` must use a different hostname from `NEXTAUTH_URL`. A different port is not enough because browser cookies ignore ports. For example, locally use `NEXTAUTH_URL=http://localhost:3000` and `NEXT_PUBLIC_VIEWER_URL=http://127.0.0.1:3001`.

## Email (Auth, notifications)

Used for sending email notifications and authentication

| Parameter | Default | Description |
| - | - | - |
| SMTP\_USERNAME | | SMTP username |
| SMTP\_PASSWORD | | SMTP password |
| SMTP\_HOST | | SMTP host. (i.e. `smtp.host.com`) |
| SMTP\_PORT | 25 | SMTP port |
| NEXT\_PUBLIC\_SMTP\_FROM | | From name and email (i.e. `'Typebot Notifications' <notifications@host.com>`) |
| SMTP\_SECURE | false | If true the connection will use TLS when connecting to server. If false (the default) then TLS is used if server supports the STARTTLS extension. In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false |
| SMTP\_IGNORE\_TLS | undefined | If true and SMTP\_SECURE is false then TLS is not used while connecting to server even if server supports STARTTLS extension. |
| SMTP\_AUTH\_DISABLED | false | To disable the authentication by email but still use the provided config for notifications |

## SMTP configuration tests in the builder

The Send Email block's SMTP configuration test permits public SMTP destinations by default. To permit an internal IPv4 SMTP relay, add its exact hostname to `SSRF_ALLOWED_HOSTS` (comma-separated), for example `SSRF_ALLOWED_HOSTS=smtp.internal.example`. This existing setting only permits RFC1918 ranges (10/8, 172.16/12 and 192.168/16, including IPv4-mapped addresses). It never permits metadata, loopback, link-local, IPv6 unique-local or other blocked special-use destinations, even in development. This instance-wide exception makes that relay available to every authenticated user who can test an SMTP configuration; it is not a workspace permission.

Every DNS answer must pass the policy. The test connects to the first validated IP, preserving the hostname for TLS certificate verification and STARTTLS. Automatic fallback to another IP is disabled; if the first address is unreachable, the test fails. Use an ASCII/punycode hostname or an IP literal and an integer port between 1 and 65535. The notification/authentication SMTP settings above and execution of stored Send Email credentials are separate paths and are unchanged by this test endpoint policy.

## Google Auth

> [accordion] Requirements
>
> 1. Head over the Credentials tab: [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials)
>
> 2. Create a OAuth client ID. This will be your `GOOGLE_AUTH_CLIENT_ID` and `GOOGLE_AUTH_CLIENT_SECRET`
>
>    Make sure to set the following scopes: `userinfo.email`
>
>    The "Authorized redirect URIs" used when creating the credentials must include your full domain and end in the callback path:
>
>    * For production:
>      * https\://\<YOUR\_DOMAIN>/api/auth/callback/google
>    * For development:
>      * [http://localhost:3000/api/auth/callback/google](http://localhost:3000/api/auth/callback/google)

| Parameter | Default | Description |
| - | - | - |
| GOOGLE\_AUTH\_CLIENT\_ID | | The Client ID from the Google API Console |
| GOOGLE\_AUTH\_CLIENT\_SECRET | | The Client secret from the Google API Console |

## Google Sheets

> [accordion] Requirements
>
> 1. Enable the following APIs in the Google Cloud Console: Google Sheets API, Google Picker API
>
> 2. Head over the Credentials tab: [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials)
>
> 3. Create an API key. This will be your `NEXT_PUBLIC_GOOGLE_SHEETS_API_KEY`
>
> 4. Create a OAuth client ID. This will be your `GOOGLE_SHEETS_CLIENT_ID` and `GOOGLE_SHEETS_CLIENT_SECRET`
>
>    Make sure to set the following scopes located in your OAuth Consent Screen: `spreadsheets`, `drive.file`
>    [https://developers.google.com/identity/protocols/oauth2/scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
>
>    The "Authorized redirect URIs" used when creating the credentials must include your full domain and end in the callback path:
>
>    * For production:
>      * https\://\<YOUR\_DOMAIN>/api/credentials/google-sheets/callback
>    * For development:
>      * [http://localhost:3000/api/credentials/google-sheets/callback](http://localhost:3000/api/credentials/google-sheets/callback)
>
> 5. To avoid having to always reconnect a Google Sheets credentials every 7 days, you need to promote your OAuth client to production ([https://developers.google.com/nest/device-access/reference/errors/authorization#refresh\_token\_keeps\_expiring](https://developers.google.com/nest/device-access/reference/errors/authorization#refresh_token_keeps_expiring))

| Parameter | Default | Description |
| - | - | - |
| GOOGLE\_SHEETS\_CLIENT\_ID | | The Client ID from the Google API Console |
| GOOGLE\_SHEETS\_CLIENT\_SECRET | | The Client secret from the Google API Console |
| NEXT\_PUBLIC\_GOOGLE\_SHEETS\_API\_KEY | | The API Key from the Google API Console |

## Gmail

> [accordion] Requirements
>
> 1. Enable the following APIs in the Google Cloud Console: Google Sheets API, Google Picker API
>
> 2. Head over the Credentials tab: [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials)
>
> 3. Create a OAuth client ID. This will be your `GMAIL_CLIENT_ID` and `GMAIL_CLIENT_SECRET`
>
>    Make sure to set the following scopes located in your OAuth Consent Screen: `gmail.send`, `gmail.labels`, `userinfo.profile`, `userinfo.email`
>    [https://developers.google.com/identity/protocols/oauth2/scopes](https://developers.google.com/identity/protocols/oauth2/scopes)
>
>    The "Authorized redirect URIs" used when creating the credentials must include your full domain and end in the callback path:
>
>    * For production:
>      * https\://\<YOUR\_DOMAIN>/oauth/redirect
>    * For development:
>      * [http://localhost:3000/oauth/redirect](http://localhost:3000/oauth/redirect)
>
> 4. To avoid having to always reconnect credentials every 7 days, you need to promote your OAuth client to production ([https://developers.google.com/nest/device-access/reference/errors/authorization#refresh\_token\_keeps\_expiring](https://developers.google.com/nest/device-access/reference/errors/authorization#refresh_token_keeps_expiring))
>
> | Parameter | Default | Description |
> | - | - | - |
> | GMAIL\_CLIENT\_ID | | The Client ID from the Google API Console |
> | GMAIL\_CLIENT\_SECRET | | The Client secret from the Google API Console |

## Google Fonts

Used authentication in the builder and for the Google Sheets integration step.

> [accordion] Requirements
>
> 1. Enable the following API in the Google Cloud Console: Web Fonts Developer API
>
> 2. Head over the Credentials tab: [https://console.developers.google.com/apis/credentials](https://console.developers.google.com/apis/credentials)
>
> 3. Create an API key with access to the Web Fonts Developer API. This will be your `NEXT_PUBLIC_GOOGLE_FONTS_API_KEY`

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_GOOGLE\_FONTS\_API\_KEY | | The API Key from the Google API Console |

## GitHub (Auth)

Used for authenticating with GitHub. By default, it uses the credentials of a Typebot-dev app.

You can create your own GitHub OAuth app [here](https://github.com/settings/developers). The Authorization callback URL should be `$NEXTAUTH_URL/api/auth/callback/github`

| Parameter | Default | Description |
| - | - | - |
| GITHUB\_CLIENT\_ID | | Application client ID. Also used to check if it is enabled in the front-end |
| GITHUB\_CLIENT\_SECRET | | Application secret |

## GitLab (Auth)

Used for authenticating with GitLab.
Follow the official GitLab guide for creating OAuth2 applications [here](https://docs.gitlab.com/ee/integration/oauth_provider.html).
The Authorization callback URL should be `$NEXTAUTH_URL/api/auth/callback/gitlab`

| Parameter | Default | Description |
| - | - | - |
| GITLAB\_CLIENT\_ID | | Application client ID. Also used to check if it is enabled in the front-end |
| GITLAB\_CLIENT\_SECRET | | Application secret |
| GITLAB\_BASE\_URL | [https://gitlab.com](https://gitlab.com) | Base URL of the GitLab instance |
| GITLAB\_REQUIRED\_GROUPS | | Comma-separated list of groups the user has to be a direct member of, e.g. `foo,bar` |
| GITLAB\_NAME | GitLab | Name of the GitLab instance, used for the SSO Login Button |

## Facebook (Auth)

You can create your own Facebook OAuth app [here](https://developers.facebook.com/apps/create/).
The Authorization callback URL should be `$NEXTAUTH_URL/api/auth/callback/facebook`

| Parameter | Default | Description |
| - | - | - |
| FACEBOOK\_CLIENT\_ID | | Application client ID. Also used to check if it is enabled in the front-end |
| FACEBOOK\_CLIENT\_SECRET | | Application secret |

## Azure AD (Auth)

If you are using [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/) for the authentication you can set the following environment variables.
The Authorization callback URL should be `$NEXTAUTH_URL/api/auth/callback/azure-ad`

| Parameter | Default | Description |
| - | - | - |
| AZURE\_AD\_CLIENT\_ID | | Application client ID |
| AZURE\_AD\_CLIENT\_SECRET | | Application client secret. Can be obtained from Azure Portal. |
| AZURE\_AD\_TENANT\_ID | | Azure Tenant ID |

## Keycloak (Auth)

Used for authenticating with Keycloak.
Follow the official Keycloak guide for creating OAuth2 applications [here](https://www.keycloak.org/).

| Parameter | Default | Description |
| - | - | - |
| KEYCLOAK\_CLIENT\_ID | | Application client ID. |
| KEYCLOAK\_CLIENT\_SECRET | | Application secret |
| KEYCLOAK\_REALM | | Your Keycloak Realm |
| KEYCLOAK\_BASE\_URL | | Base URL of the Keycloak instance |

## Custom OAuth Provider (Auth)

Your provider needs to support the [OpenID Connect](https://openid.net/connect/) standards.

| Parameter | Default | Description |
| - | - | - |
| CUSTOM\_OAUTH\_CLIENT\_ID \* | | OAuth client ID. |
| CUSTOM\_OAUTH\_CLIENT\_SECRET \* | | OAuth client secret. |
| CUSTOM\_OAUTH\_ISSUER \* | | OAuth issuer URL (i.e. `https://auth.domain.com/openid`) |
| CUSTOM\_OAUTH\_NAME | Custom OAuth | Provider name. Will be displayed in the sign in form. |
| CUSTOM\_OAUTH\_WELL\_KNOWN\_URL | `CUSTOM_OAUTH_ISSUER`/.well-known/openid-configuration | Provider .well-known URL |
| CUSTOM\_OAUTH\_USER\_ID\_PATH | id | Claim path used to map the user ID |
| CUSTOM\_OAUTH\_USER\_NAME\_PATH | name | Claim path used to map the user name |
| CUSTOM\_OAUTH\_USER\_EMAIL\_PATH | email | Claim path used to map the user email |
| CUSTOM\_OAUTH\_USER\_IMAGE\_PATH | image | Claim path used to map the user image |
| CUSTOM\_OAUTH\_SCOPE | openid profile email | OAuth scope |
| CUSTOM\_OAUTH\_USE\_USERINFO | false | Use the provider's UserInfo endpoint for profile claims |

For `*_PATH` parameters, you can use dot notation to access nested properties (i.e. `account.name`).
By default, profile claims come from the ID Token. Set `CUSTOM_OAUTH_USE_USERINFO=true` to use UserInfo instead. This changes the claim source used by the configured `*_PATH` values; claims are not merged.

The Authorization callback URL should be: `$NEXTAUTH_URL/api/auth/callback/custom-oauth`

## S3 Storage (Media uploads)

Used for uploading images, videos, etc... It can be any S3 compatible object storage service (Minio, Digital Oceans Space, AWS S3...)

| Parameter | Default | Description |
| - | - | - |
| S3\_ACCESS\_KEY | | S3 access key. Also used to check if upload feature is enabled |
| S3\_SECRET\_KEY | | S3 secret key. |
| S3\_BUCKET | typebot | Name of the bucket where assets will be uploaded in. |
| S3\_PORT | | S3 Host port number |
| S3\_ENDPOINT | | S3 endpoint (i.e. `s3.domain.com`). |
| S3\_SSL | true | Use SSL when establishing the connection. |
| S3\_REGION | | S3 region. |
| S3\_PUBLIC\_CUSTOM\_DOMAIN | | If the final URL that is used to read public files is different from `S3_ENDPOINT` |

Note that for AWS S3, your endpoint is usually: `s3.<S3_REGION>.amazonaws.com`

In order to function properly, your S3 bucket must be configured. Make sure to read through the [S3 configuration](https://docs.typebot.com/self-hosting/guides/s3.md) doc.

## Giphy (GIF picker)

Used to search for GIF. You can create a Giphy app [here](https://developers.giphy.com/dashboard/)

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_GIPHY\_API\_KEY | | Giphy API key |

## Unsplash (image picker)

Used to search for images. You can create an Unsplash app [here](https://unsplash.com/developers)

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_UNSPLASH\_APP\_NAME | | Unsplash App name |
| NEXT\_PUBLIC\_UNSPLASH\_ACCESS\_KEY | | Unsplash API key |

## Pexels (video picker)

Used to search for videos. You can create a Pexels app [here](https://www.pexels.com/api/key/)

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_PEXELS\_API\_KEY | | Pexels API key |

## Tolgee (i18n contribution dev tool)

> [!NOTE]
>
> If you'd like to join contribute to Typebot's translation join the [Discord
> server](https://discord.gg/xjyQczWAXV) and ask for an access to Tolgee in the
> [#contributors
> channel](https://discord.com/channels/1155799591220953138/1155883114455900190).

Set up these environment variables to enable [Tolgee dev tool](https://tolgee.io/features/dev-tools).

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_TOLGEE\_API\_KEY | | Your Tolgee API key |
| NEXT\_PUBLIC\_TOLGEE\_API\_URL | [https://tolgee.server.baptistearno.com](https://tolgee.server.baptistearno.com) | The Tolgee API base URL |

## WhatsApp (Preview)

In order to be able to test your bot on WhatsApp from the Preview drawer, you need to set up a WhatsApp business app.

> [accordion] Requirements
>
> ## 1. [Create a WhatsApp Meta app](https://docs.typebot.com/deploy/whatsapp/create-meta-app.md)
>
> ## 2. Get the App Secret and System User token
>
> 1. Go to your app's `App settings > Basic` page and copy the App Secret. This will be used as `WHATSAPP_PREVIEW_APP_SECRET` in your builder configuration.
>
> 2. Go to your [System users page](https://business.facebook.com/settings/system-users) and create a new system user that has access to the related.
>
> * Token expiration: `Never`
>
> * Available Permissions: `whatsapp_business_messaging`, `whatsapp_business_management`
>
> 3. The generated token will be used as `META_SYSTEM_USER_TOKEN` in your viewer configuration.
> 4. Click on `Add assets`. Under `Apps`, look for your app, select it and check `Manage app`
>
> ## 3. Get the phone number ID
>
> 1. Go to your WhatsApp Dev Console
>
>    ![WhatsApp dev console](https://mintcdn.com/typebot/D5R4vjlxdJ2YwlGK/images/whatsapp/dev-console.png?fit=max\&auto=format\&n=D5R4vjlxdJ2YwlGK\&q=85\&s=5b6276c5505c528cfa1c9e031e470e7f)
>
> 2. Add your phone number by clicking on the `Add phone number` button.
>
> 3. Select the newly created phone number in the `From` dropdown list and you will see right below the associated `Phone number ID` This will be used as `WHATSAPP_PREVIEW_FROM_PHONE_NUMBER_ID` in your viewer configuration.
>
> ## 4. Set up the webhook
>
> 1. Head over to `Quickstart > Configuration`. Edit the webhook URL to `$NEXTAUTH_URL/api/v1/whatsapp/preview/webhook`. Set the Verify token to `$ENCRYPTION_SECRET` and click on `Verify and save`.
> 2. Add the `messages` webhook field.
>
> ## 5. Set up the message template
>
> 1. Head over to `Messaging > Message Templates` and click on `Create Template`
> 2. Select the `Utility` category
> 3. Give it a name that corresponds to your `WHATSAPP_PREVIEW_TEMPLATE_NAME` configuration.
> 4. Select the language that corresponds to your `WHATSAPP_PREVIEW_TEMPLATE_LANG` configuration.
> 5. You can format it as you'd like. The user will just have to send a message to start the preview.

| Parameter | Default | Description |
| - | - | - |
| META\_SYSTEM\_USER\_TOKEN | | The system user token used to send WhatsApp messages |
| WHATSAPP\_PREVIEW\_FROM\_PHONE\_NUMBER\_ID | | The phone number ID from which the message will be sent |
| WHATSAPP\_PREVIEW\_APP\_SECRET | | The Meta app secret used to verify preview webhook signatures |
| WHATSAPP\_PREVIEW\_TEMPLATE\_NAME | | The preview start template message name |
| WHATSAPP\_PREVIEW\_TEMPLATE\_LANG | en\_US | The preview start template message name |
| WHATSAPP\_CLOUD\_API\_URL | [https://graph.facebook.com](https://graph.facebook.com) | The WhatsApp Cloud API base URL |
| WHATSAPP\_INTERACTIVE\_GROUP\_SIZE | 3 | The array size of items to send to API on choice input. You can't choose a number higher than 3 if you are using the official cloud API URL. |

## Redis

In Typebot, Redis is optional and is used to:

* Rate limit the sign in requests based on user IP
* Enable multiple media upload on WhatsApp

| Parameter | Default | Description |
| - | - | - |
| REDIS\_URL | | The database URL. i.e. `redis://<username>:<password>@<host>:<port>` |

## PartyKit

PartyKit is optional and is used to make the webhook block work. The relay is a [PartyServer](https://github.com/cloudflare/partykit/tree/main/packages/partyserver) Worker located in the `packages/partykit` folder and configured by its `wrangler.jsonc`. Set its secret with `bunx wrangler secret put WEBHOOK_RELAY_SECRET`, then deploy it to your Cloudflare account with `bunx wrangler deploy --domain <your-domain>` from that folder.

If you previously deployed it with `partykit deploy` to your own Cloudflare account, deploy with `bunx wrangler deploy --env partykit --domain <your-domain>` instead. It reuses the same Worker, Durable Object class, rooms and the `WEBHOOK_RELAY_SECRET` set with `partykit env`. Hosted `*.partykit.dev` projects can't be reused: deploy a new Worker and update `NEXT_PUBLIC_PARTYKIT_HOST`.

| Parameter | Default | Description |
| - | - | - |
| NEXT\_PUBLIC\_PARTYKIT\_HOST | | PartyKit host. i.e. `partykit.typebot.io` |
| WEBHOOK\_RELAY\_SECRET | | Required for Webhook blocks, including previews and WhatsApp. Use the same server-only secret in builder, viewer and PartyKit, generated from at least 32 random bytes. See the [upgrade instructions](https://github.com/baptisteArno/typebot.io/blob/main/CHANGELOG.md#webhook-signing-secret-and-coordinated-upgrade). |

## Others

The related environment variables are listed here but you are probably not interested in these if you self-host Typebot.

> [accordion] Vercel (custom domains)
>
> | Parameter | Default | Description |
> | - | - | - |
> | VERCEL\_TOKEN | | Vercel API token |
> | NEXT\_PUBLIC\_VERCEL\_VIEWER\_PROJECT\_NAME | | The name of the viewer project in Vercel |
> | VERCEL\_TEAM\_ID | | Vercel team ID that contains the viewer project |

> [accordion] Telemetry
>
> | Parameter | Default | Description |
> | - | - | - |
> | MESSAGE\_WEBHOOK\_URL | | Webhook URL called to receive important system messages |
> | USER\_CREATED\_WEBHOOK\_URL | | Webhook URL called whenever a new user is created |

> [accordion] OpenTelemetry
>
> | Parameter | Default | Description |
> | - | - | - |
> | OTEL\_EXPORTER\_OTLP\_ENDPOINT | | OTLP HTTP endpoint used to export telemetry. Typebot sends traces to `/v1/traces` and logs to `/v1/logs`. |
> | OTEL\_EXPORTER\_OTLP\_HEADERS | | Comma-separated OTLP headers passed to the exporter. Format: `key=value,another=value`. |
> | OTEL\_EXPORTER\_OTLP\_SIGNALS | `traces` | Which signals to export. Possible values are `traces`, `logs`, `both`. Set `logs` if you only want Effect logs. |

> [accordion] PostHog
>
> | Parameter | Default | Description |
> | - | - | - |
> | NEXT\_PUBLIC\_POSTHOG\_KEY | | PostHog API Key |
> | POSTHOG\_API\_HOST | [https://eu.posthog.com](https://eu.posthog.com) | PostHog API Host |
> | POSTHOG\_PERSONAL\_API\_KEY | | PostHog personal API Key |
> | POSTHOG\_PROJECT\_ID | | PostHog project ID |

> [accordion] System labels
>
> | Parameter | Default | Description |
> | - | - | - |
> | NEXT\_PUBLIC\_VIEWER\_404\_TITLE | 404 | |
> | NEXT\_PUBLIC\_VIEWER\_404\_SUBTITLE | The bot you're looking for doesn't exist | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.