## 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.

### Login background and public scripts

The login, signup and password-reset request pages run enabled dashboard Custom Scripts that match their route. The managed login background uses `ctx.dom.css`; `ctx.log` and cleanup helpers also work. On these public pages, `ctx.store`, `ctx.api` and `ctx.storage` are unavailable, account-scoped scripts are excluded, and execution status is not sent to account APIs. Scripts remain trusted operator JavaScript, not sandboxed code.

Use `run_on: route_change` with `/app/login*` for login-only styling; its managed resources are removed when leaving that route. Password editing remains excluded, including when reached through SPA navigation. If the initial page is password editing, reload a permitted page to load its scripts. After applying branding, reload the login page; public pages do not subscribe to authenticated hot reload.

## 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.

### Execution reports

Browser error reports send only the execution status and error message, not the stack trace,
raw page URL or run-on metadata. Reproduced storm incidents keep their sanitized page path;
managed branding scripts retain their exemption from automatic disabling. Review messages before
sharing them: a script can include its own data in an error message.

## 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)