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

# Configure CSPs

> Content Security Policy configuration for botBrains website integration

<Note>
  **If you do not have CSPs configured, they do not interfere with botBrains.** If you have some in place, you must update them when integrating botBrains. If you don't know what CSPs are, you likely don't have them configured.

  CSPs require deep browser understanding and configuring a single character wrong can trip you up. We are here to help-reach out to [support@botbrains.io](mailto:support@botbrains.io) or via live chat on [platform.botbrains.io](https://platform.botbrains.io).
</Note>

<Tip>
  We're not perfect and you might encounter unexpected CSP blocks in the browser console. **Please report** them to [support@botbrains.io](mailto:support@botbrains.io).
</Tip>

This guide covers the Content Security Policy (CSP) requirements for integrating with botBrains Chat Bubble service. It outlines the key endpoints we communicate with and the necessary CSP configurations.

## What are CSPs?

Content Security Policies (CSPs) are security measures implemented by web browsers to prevent various types of attacks, particularly cross-site scripting (XSS) and data injection attacks. They work by allowing servers to specify exactly which sources of content browsers should consider trustworthy for loading resources like scripts, stylesheets, images, fonts, and more. Servers apply CSPs through HTTP response headers or HTML meta elements, creating a security layer that blocks potentially malicious content from executing.

## How do I know if we use CSPs?

Check if your server returns this header on the main HTML document served:

```
Content-Security-Policy:
```

## Why do I need to change CSPs when integrating botBrains?

When integrating botBrains (via the HTML/JS snippet), your CSPs may block our functionality. Because we run in your domain context, strict CSPs can prevent script execution, API communications, or dynamic content generation. You must update your CSP directives to explicitly allow botBrains to operate correctly.

## Main Endpoints

While we bundle our dependencies with version pinning, some libraries communicate with their systems to load additional features such as Session Replay on demand. To ensure proper functionality, your CSP must allow communication with the following endpoints:

### botBrains - Assets, API and Open Graph Previews

* `https://api.botbrains.io` - Primary API for back-end communication
* `https://chat.botbrains.io` - Used for chat functionality and script loading
* `https://*.botbrains-cdn.com` - Used for assets loading and proxying 3rd party assets
* `data:...` - Used to load image and audio data

Our system may load images and URLs dynamically for link previews. While we plan to proxy asset requests through our CDN, we currently load them directly from their respective sources. Images from your allowed domains work as expected, but the browser may block some images until we implement CDN proxying.

### Error Monitoring

* `https://*.sentry.io` - Ingestion API used for error reporting and logging

### Analytics & User Behavior Tracking

* `https://*.i.posthog.com` - API used for feature flags, analytics and event tracking

See [PostHog CSP documentation](https://posthog.com/docs/advanced/content-security-policy) for more details.

## Recommended CSP Configuration

In addition to your current rules, add these directives:

```
Content-Security-Policy:
  script-src 'self' 'unsafe-inline' https://*.botbrains.io;
  style-src 'self' 'unsafe-inline' https://*.botbrains.io;
  img-src 'self' https://*.botbrains.io data:;
  connect-src 'self' https://*.botbrains.io wss://*.botbrains.io https://*.sentry.io https://*.i.posthog.com;
  frame-src 'self' https://*.botbrains.io;
  form-action 'self' https://*.botbrains.io;
```

<Note>
  * `unsafe-inline` for CSS cannot be changed currently. Reach out to [support@botbrains.io](mailto:support@botbrains.io) if this is a deal-breaker.
  * `unsafe-inline` for `script-src` can be replaced by `'nonce-{SERVER-GENERATED-NONCE}'` if you add a nonce to the loader script: `<script nonce='{SERVER-GENERATED-NONCE}'>$botbrains = []; ...</script>`.
</Note>

This configuration only shows the necessary additions for botBrains to work. You need to merge it with your existing configuration.

## Explanation of Directives

The wildcard `*` matches multi-level domains. For example, `*.example.com` won't match `example.com` but will match any subdomain, including nested subdomains (for example, `two.one.example.com`).

| Directive                   | Description                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `default-src 'self'`        | Restricts all unspecified resource types to the current origin                       |
| `script-src`                | Allows scripts only from configured domains                                          |
| `style-src`                 | Permits loading styles from given domains / inline-mode                              |
| `img-src`                   | Allows images from given domains                                                     |
| `font-src`                  | Permits loading fonts from given domains                                             |
| `connect-src`               | Enables communication with given domains. Note that you must state protocols         |
| `frame-src`                 | Restricts iframe loading to given domains                                            |
| `object-src 'none'`         | Prevents embedding objects (for example, Flash, plugins)                             |
| `base-uri 'self'`           | Prevents attackers from hijacking forms by blocking changes to the document base URL |
| `form-action 'self'`        | Ensures forms are only submitted to the same origin                                  |
| `upgrade-insecure-requests` | Forces the browser to upgrade all HTTP requests to HTTPS                             |

<Warning>
  Please reach out to us if you struggle to set up the correct CSPs and our support team will help you out. CSPs are difficult to get right and the exact configuration depends on your exact setup.
</Warning>