Skip to content

Widget configuration

The PageClerk widget is configured by a single global object, window.pageclerkConfig, that you define before loading the widget script.

<script>
window.pageclerkConfig = {
chatbotId: "YOUR_CHATBOT_ID"
};
</script>
<script src="https://pageclerk.com/api/widget.js" defer></script>

Type: string · Required

The 32-character ID of the chatbot to load. Find it in your dashboard under Chatbots → Settings or on the Embed & Share tab.

If chatbotId is missing, the widget logs an error and does not render:

PageClerk: pageclerkConfig object or chatbotId not defined

Type: boolean · Default: false

Don’t show the chat bubble. Open the chat from your own button with PageClerk.open() instead. Implies lazy.

Type: boolean · Default: false

Keep the bubble, but don’t load the chat until it’s likely needed. It warms up when the visitor hovers or focuses the bubble (or any element with a data-pageclerk-open attribute), so visitors who never use the chat never load it. Makes your page lighter. If the chat isn’t ready when opened, the bubble shows a spinner and the window appears once it’s fully drawn.

Type: string · Default: your page’s <html lang>, then the visitor’s browser language

The language of the widget’s own text, such as “Send message”, “Jump to latest” and the contact form labels: en, es, fr, de, it, pt or nl. Other languages fall back to English. Text you write yourself (greetings, suggestions, the input placeholder) is shown as you wrote it, and replies follow the language the visitor writes in.

The widget exposes window.PageClerk with open, close and toggle. Calls made before the script has loaded are queued:

<script>
window.PageClerk = window.PageClerk || [];
</script>
<button onclick="window.PageClerk.push ? PageClerk.push(['open', { message: 'Hi, I have a question about pricing' }]) : PageClerk.open({ message: 'Hi, I have a question about pricing' })">
Talk to us
</button>

message pre-fills the visitor’s input box (up to 500 characters). It is never sent on their behalf: they review it and press send.

Everything that is not chatbotId — appearance, greeting, avatar, and allowed domains — is managed in the dashboard and fetched by the widget at load time:

  • Appearance — launcher colors, avatar, greeting, and light, dark or device-matched theme. The first greeting line also appears beside the launcher a few seconds after the page loads, unless you turn the preview bubble off; visitors who close it don’t see it again for the rest of their visit.
  • Allowed domains — restrict where the widget may load.

Because of this, dashboard changes apply to every embedded site immediately, with no embed-code edits.

window.pageclerkConfig must be assigned before widget.js executes. Loading the script with defer in the same document satisfies this as long as the inline config script appears first.