Coachful accepts custom code in several builders, but each surface has a different security boundary. Use this guide to choose the right format and avoid exposing private data or breaking a live client experience.
Most important: never put an API key, secret token, private AI key, Stripe secret, Firebase Admin credential, or webhook signing secret in HTML or browser JavaScript. Anyone who can open the page can inspect and copy browser code.
Choose the right surface
| Surface | HTML/CSS | JavaScript | Coachful actions |
|---|---|---|---|
| Funnels and coaching flows | Supported | Removed when saved | Use supported data-coachful-slot blocks |
| Custom-code resources | Supported | Supported in a sandbox | No private Coachful browser API or account access |
| Website Custom HTML | Supported | Full-document or scripted code runs in a sandbox | Use normal links and supported funnel link attributes |
| Funnel tracking settings | Not a layout surface | Tracking code only | Use for trusted analytics events |
Funnels and coaching flows
Use the Code design editor for the visual layout. Coachful sanitizes this HTML before it is stored and rendered. Scripts, inline event handlers, embedded frames, and unsafe URLs are removed. Functional parts of the journey stay under Coachful's control through slot markers.
Basic example
<section class="px-6 py-12 text-center">
<p class="text-sm uppercase tracking-wide">Quick reflection</p>
<h1 class="mt-2 text-4xl font-semibold">How are you feeling today?</h1>
<div class="mt-8" data-coachful-slot="options"></div>
<div class="mt-6" data-coachful-slot="continue_button"></div>
</section>Keep every required slot when redesigning a step. Coachful replaces the marker with the real form, payment, scheduling, or navigation component at runtime.
Supported slot markers
continue_button— advance to the next stepoptions— single- or multiple-choice answers configured for the steptext_input,textarea, andscale— answer inputsformandemail_capture— configured form and lead capturesignup_formandcode_input— account or access-code inputscalendarandevent_registration— booking and event experiencesmediaandfile_upload— configured media and uploads
The editor shows only the slots allowed for the current step. A payment, signup, booking, or other sensitive action must use its native Coachful block; custom HTML cannot imitate the server-side action.
What not to paste
<!-- Removed: browser JavaScript does not run in flow/funnel layout HTML -->
<script>fetch('/api/private-data')</script>
<!-- Removed: inline handlers are not supported -->
<button onclick="doSomething()">Continue</button>
<!-- Use the native slot instead -->
<div data-coachful-slot="continue_button"></div>Custom-code resources
A Custom code AI tool can contain a complete HTML document with CSS and JavaScript. It runs inside a sandboxed frame on the resource page. This is suitable for calculators, assessments, interactive exercises, visualizations, and small client-side tools.
Interactive example
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body { font: 16px system-ui; padding: 24px; }
button { padding: 10px 16px; border-radius: 12px; }
</style>
</head>
<body>
<h1>Momentum counter</h1>
<p id="result">0</p>
<button id="add" type="button">Add one</button>
<script>
let value = 0;
const result = document.querySelector('#result');
document.querySelector('#add').addEventListener('click', () => {
value += 1;
result.textContent = String(value);
});
</script>
</body>
</html>The frame automatically grows to fit its content. The code can update its own document, use normal browser calculations, and react to input inside the tool.
Sandbox boundary
Resource code cannot read Coachful cookies, Coachful local storage, the parent dashboard DOM, Firebase credentials, or the signed-in user's authentication session. It does not gain access to a Coachful organization simply because it is displayed on a Coachful page.
Browser requests to an external service may work only when that service allows cross-origin requests. Treat those requests as public client-side traffic. Never include a secret in the URL, headers, source code, or request body.
Website Custom HTML
Plain fragments are sanitized and rendered as part of the website. A complete HTML document or markup containing a script runs in a sandboxed frame. This prevents its JavaScript from reading the surrounding Coachful page.
Use normal HTTPS links for navigation. Buttons can open a Coachful funnel popup when the website editor supplies the supported funnel destination. Do not depend on private parent-page variables or undocumented postMessage events; those are internal and may change.
Funnel tracking code
Custom tracking code is an advanced exception: analytics snippets need to run on the live funnel page so their pixel SDK can observe page events. This code is not the sandboxed resource environment. It can read content on that funnel page and send browser requests, so only paste an unchanged snippet from a trusted analytics provider.
Prefer the dedicated Meta Pixel, Google Analytics, and Google Ads fields whenever possible. Never use tracking code to collect answers, payment details, authentication data, or other personal information, and never place a secret credential in a tracking snippet.
Security rules
- Only paste code you wrote or trust. A script can read anything a visitor types inside that custom tool and send it to an external server.
- Never place secrets in browser code. Use a server you control when an external service requires a secret credential.
- Collect the minimum data. Do not ask for health, payment, identity, or other sensitive information in a custom tool unless you have a compliant server-side flow and a clear consent basis.
- Use native Coachful blocks for privileged actions. Payments, account creation, access grants, form submission, completion, and scheduling should remain in Coachful's validated components.
- Preview before publishing. Test mobile sizing, keyboard navigation, dark backgrounds, links, and empty or unusually long answers.
- Keep third-party dependencies intentional. Every external script can observe the custom tool and can change without a Coachful release.
Can custom code access the Coachful REST API?
Not securely from the browser. The Coachful REST API uses private API keys intended for server-to-server integrations and automation platforms. Putting one in JavaScript exposes the entire key to every visitor. Build the integration on a trusted server, Zapier, OttoKit, an automation, or a supported Coachful connection instead.
Troubleshooting
- If JavaScript disappears from a flow or funnel design, that is expected. Use a native slot or build the experience as a custom-code resource.
- If an external request fails, check the browser console and the destination service's CORS policy.
- If a resource is too tall or too short, remove fixed viewport heights such as
100vhand let the document size to its content. - If a Coachful action is missing, use the editor's Add funnel block control. Do not recreate payment, signup, or scheduling logic in JavaScript.
- If code came from an AI tool, review every network request and external script before publishing it.
Current API status
Coachful does not currently expose a privileged browser SDK to custom code. Supported funnel slots are the stable interaction contract. If a future browser SDK is introduced, it will be versioned and documented on this page without exposing account credentials to the sandbox.