## Overview

**Custom Scripts** let you inject custom **JavaScript** and **CSS** into three surfaces of the
platform:

- **Dashboard**: the panel used by your support team.
- **Portal**: the public Help Center site.
- **Widget**: the chat embedded on your website.

This lets you add behaviors (e.g., track events, show a notice) or styling tweaks (e.g.,
hide/highlight elements) without changing the platform's code. It's a powerful feature, which is why
it lives in **platform administration**.

## Prerequisites

- **Operator/super administration** access to the platform.
- JavaScript/CSS knowledge (the script runs in the browser of whoever uses the chosen surface).
- An environment to test before publishing (ideally outside production).

## Step by step

1. Access the **platform administration** panel and open the **Custom Scripts** area.
2. Create a new script with: **surface** (dashboard, portal or widget), **type** (JS or CSS) and when
   it should run (**run on**).
3. Paste your code. In JS scripts, use the context object (`ctx`) provided by the platform to
   interact safely with the surface.
4. **Teardown**: scripts that add elements/listeners should remove them when requested, to avoid
   accumulating side effects in SPA navigation.
5. Save, enable and **test** on the matching surface before rolling out to everyone.

## Settings & options

- **Surface**: choose which environment the script runs in (dashboard, portal or widget).
- **Type**: JavaScript (behavior) or CSS (style).
- **When to run (run on)**: controls the execution moment/context.
- **Active/Inactive**: turn a script on or off without deleting it.

## Use cases

- Add a temporary notice/banner on the team dashboard.
- Hide or restyle a portal element to match your brand.
- Fire an analytics event when the widget opens.

## Tips, limits & best practices

- Keep scripts **small and idempotent**; always implement the **teardown**.
- Avoid heavy external dependencies — they affect the surface's performance.
- Version your code outside the platform and document what each script does.
- Because it's code injection, treat it as **high impact**: review before publishing.

## Troubleshooting

- **The script doesn't run**: check the chosen surface, that it's active, and the run-on moment.
- **Something broke on screen**: disable the script and use the browser console to see errors.
- **The effect duplicates on navigation**: the **teardown** is missing — remove added
  elements/listeners.
- **I can't find the Custom Scripts area**: it's in platform administration — ask the installation
  owner for access.

## See also

- [Whitelabel (your own brand)](/hc/ajuda/articles/administration-whitelabel-en)
- [Integrations](/hc/ajuda/articles/administration-integracoes-en)
- [Administration overview](/hc/ajuda/articles/administration-overview-en)
- [Guided Tours](/hc/ajuda/articles/administration-guided-tours-en)