ConversaLabs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Custom Scripts SDK

Open in
View as Markdown Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Oct 21, 2026

Overview

Custom Scripts let you inject JavaScript/CSS into specific platform surfaces — the dashboard, the Help Center portal and the chat widget. They're useful for small behavior and style customizations without changing the codebase.

Prerequisites

  • Administrator permission to manage Custom Scripts.
  • JavaScript/CSS knowledge.

Step by step

  1. Open the Custom Scripts module.
  2. Create a script and choose the surface (dashboard, portal or widget).
  3. Set the type (JS or CSS) and when it should run.
  4. Use the ctx context provided by the runtime to interact with the surface safely.
  5. Implement teardown to clean up what the script created, when applicable.

Settings & options

  • Surface: dashboard / portal / widget.
  • Type: JS or CSS.
  • Execution: rules for when the script runs.
  • Settings (ctx.settings): they are the configuration defined by the operator and are meant for reading only. Each run of the script receives its own copy, which lasts only for that run. A change the script makes to that copy is not kept for the next run and does not modify the saved configuration. To keep state, use ctx.storage on the surfaces that offer it: the dashboard, the portal and the widget. The public login, signup and password-reset pages do not offer ctx.storage.

Use cases

  • Add a button or notice on a specific screen.
  • Tweak targeted styles of a surface.
  • Log usage events for internal analysis.

Tips, limits & best practices

  • Write idempotent scripts with teardown to avoid duplication.
  • Avoid heavy dependencies; prefer lean code.
  • Test in a controlled environment before publishing.

Troubleshooting

  • Script doesn't run: confirm the surface and execution rules.
  • Duplicated behavior: check teardown and idempotency.

See also