Skip to main content
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 or via live chat on platform.botbrains.io.
We’re not perfect and you might encounter unexpected CSP blocks in the browser console. Please report them to support@botbrains.io.
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. CSPs are applied 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 backend 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 some images may be blocked 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 for more details. 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;
  • unsafe-inline for CSS cannot be changed currently. Reach out to 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>.
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 will NOT match example.com but will match any subdomain, including nested subdomains (e.g., two.one.example.com).
DirectiveDescription
default-src 'self'Restricts all unspecified resource types to the current origin
script-srcAllows scripts only from configured domains
style-srcPermits loading styles from given domains / inline-mode
img-srcAllows images from given domains
font-srcPermits loading fonts from given domains
connect-srcEnables communication with given domains. Note that protocols must be stated
frame-srcRestricts iframe loading to given domains
object-src 'none'Prevents embedding objects (e.g., Flash, plugins)
base-uri 'self'Ensures forms cannot be hijacked by preventing changes to the document base URL
form-action 'self'Ensures forms are only submitted to the same origin
upgrade-insecure-requestsForces all HTTP requests to be upgraded to HTTPS
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.