Ferndesk SDK Reference

The Ferndesk SDK is a lightweight JavaScript library that provides programmatic control over the Self-Service Widget. Once embedded, it exposes a global Ferndesk object on window.Ferndesk that allows you to initialize the widget, open articles, trigger searches, and manage visibility, all from your site's JavaScript code.

Getting started

Installation

First, embed the Ferndesk SDK script in your HTML (or copy from the Ferndesk dashboard):

<!-- Step #1. Install the Ferndesk SDK -->
<script>
    !(function (e, t) {
        var n = 'ferndesk-sdk',
            r = e.FERNDESK_SDK_SRC || 'https://static.ferndesk.com/dist/sdk.js',
            c = 'Ferndesk',
            s = t.currentScript;
        function a() {
            if (!t.getElementById(n)) {
                var e = t.createElement('script');
                ((e.id = n),
                    (e.src = r),
                    (e.async = !0),
                    s && s.nonce && ((e.nonce = s.nonce), e.setAttribute('nonce', s.nonce)));
                var c = t.getElementsByTagName('script')[0];
                c.parentNode.insertBefore(e, c);
            }
        }
        if ('function' != typeof e[c]) {
            var i = [],
                o = function () {
                    i.push(arguments);
                };
            ((o.q = i), (e[c] = o));
        }
        'complete' === t.readyState || 'interactive' === t.readyState
            ? a()
            : t.addEventListener('DOMContentLoaded', a);
    })(window, document);
</script>

Initialization

Initialize the widget with your widget ID:

<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' })
</script>

Once initialized, the widget appears as a floating button on your page, and all SDK methods become available.

The widgetId parameter is required.

Core methods

Init

Initialize the Ferndesk widget.

Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', open: true })

Parameters:

widgetId (string, required): Your widget ID from the Ferndesk dashboard.
open (boolean, optional): If true, the widget opens automatically on page load. Default: false.
hideLauncher (boolean, optional): If true, hides the floating widget button. The widget stays hidden until you call open() or toggle(). Default: false.
locale (string, optional): Set the widget language using an ISO 639-1 language code (e.g., 'fr', 'es', 'de'). Overrides browser language detection and help center defaults. Supported: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Default: auto-detected from browser.
changelogAnnouncements (boolean, optional): Controls announcement prompts for changelog updates. true shows announcements to every visitor, including anonymous ones. false suppresses announcement prompts and unseen badges while keeping the changelog feed and direct navigation available.

Returns: None. Triggers widget initialization.

Example: Custom help button with hidden launcher:

<button onclick="Ferndesk('open')">Get Help</button>

<script>
Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  hideLauncher: true
});
</script>

Example — Force French language regardless of browser settings:

Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  locale: 'fr'
});

Users click your custom button to open the widget. The default floating button never appears.

If you set hideLauncher to true, make sure to provide another way for users to open the widget (like a custom button). Otherwise they won't be able to access your help center.

Console errors:

Ferndesk: init requires a widgetId — widgetId parameter is missing.
Ferndesk widget failed to load widget configuration — The widget ID is invalid or not found.

Hide

Hide the widget button and disable interaction.

Ferndesk('hide')

Parameters: None.

Returns: None.

Behavior: Hides the widget button and closes any open panels. Users cannot access the widget until show() is called.

Example use case: Hide the widget on pages where help isn't needed:

if (window.location.pathname === '/checkout') {
  Ferndesk('hide');
}

Show

Display the widget button and make it interactive.

Ferndesk('show')

Parameters: None.

Returns: None.

Behavior: Makes the widget button visible. If already visible, no change occurs.

Example use case: Show the widget after a user performs a certain action:

document.getElementById('help-button').addEventListener('click', () => {
  Ferndesk('show');
});

Open

Open the widget help panel programmatically.

Ferndesk('open')

Parameters: None.

Returns: None.

Behavior: Opens the main widget panel without navigating to a specific article. Users see the help center home.

Example use case: Open help when a user clicks a "Get Help" button:

document.getElementById('get-help').addEventListener('click', () => {
  Ferndesk('open');
});

OpenHome

Reset widget navigation to the home view.

Ferndesk('openHome')

Parameters: None.

Returns: None.

Behavior: Opens the widget and navigates to the home view. If the widget is already open but showing another view (like the AI assistant or contact form), this resets navigation back to the home view. Use this when you want to return users to the main help center view from any other widget state.

// Button to reset widget to home view
document.getElementById('reset-help').addEventListener('click', () => {
  Ferndesk('openHome');
});

When to use:

You want to programmatically return to the home view from another widget state.
You need a reliable way to reset widget navigation regardless of current view.
You're building custom navigation that includes a "home" action.

The open command opens the widget to the home view if closed. Use openHome when you want to explicitly reset to home from another view like the AI assistant or contact form.

OpenAssistant

Open the widget directly to the AI assistant view.

Ferndesk('openAssistant')

Parameters: None.

Returns: None.

Behavior: Opens the widget and navigates directly to the AI assistant chat view, where users can ask questions and receive AI-powered answers from your help center content. Use this when you want users to immediately start a conversation with the AI assistant, rather than browsing articles.

Example use case: Open the AI assistant from a dedicated "Ask a question" button:

document.getElementById('ask-question').addEventListener('click', () => {
  Ferndesk('openAssistant');
});

Example use case: Open the assistant from a contextual help link:

<a href="#" onclick="Ferndesk('openAssistant')">Ask AI for help</a>

OpenContact

Open the widget directly to the contact form view.

Ferndesk('openContact')

Parameters: None.

Returns: None.

Behavior: Opens the widget and navigates directly to the contact form view, where users can submit a support request. The contact form behavior depends on your widget settings: it may show an email form, redirect to an external link, or hand off to an integrated chat platform like Intercom or Zendesk.

Example use case: Open the contact form from a "Contact support" button:

document.getElementById('contact-support').addEventListener('click', () => {
  Ferndesk('openContact');
});

Example use case: Combine prefill with openContact for logged-in users:

// After user clicks a "Report a problem" button
Ferndesk('prefill', {
  name: user.fullName,
  email: user.email,
  subject: 'Problem report'
});
Ferndesk('openContact');

The openContact command respects your configured contact method. If you set contact to an external link or integration, the widget will route accordingly instead of showing an email form.

Close

Close the open widget panel.

Ferndesk('close')

Parameters: None.

Returns: None.

Behavior: Closes any open widget panel, sidebar, or modal. The widget button remains visible and clickable.

Destroy

Remove the widget completely and free resources.

Ferndesk('destroy')

Parameters: None.

Returns: None.

Behavior: Removes the widget from the page, clears event listeners, and resets state. To use the widget again, call init() with a new widget ID.

Example use case: Clean up the widget on page unload in single-page apps:

window.addEventListener('beforeunload', () => {
  Ferndesk('destroy');
});

SetLocale

Change the widget language after initialization.

Ferndesk('setLocale', 'es')

Parameters:

locale (string or null, required): ISO 639-1 language code (e.g., 'de', 'ja') or null to reset to auto-detection.

Returns: None.

Behavior: Immediately switches the widget UI and content to the specified language. Reloads widget translations and re-fetches content in the new language. Pass null to restore automatic browser-based language detection.

Supported languages: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr.

Example — Language switcher:

<select id="lang-picker">
  <option value="en">English</option>
  <option value="fr">Français</option>
  <option value="es">Español</option>
</select>

<script>
document.getElementById('lang-picker').addEventListener('change', (e) => {
  Ferndesk('setLocale', e.target.value);
});
</script>

Example — Reset to browser language:

// User clicks "Use my browser language" button
Ferndesk('setLocale', null);

The locale setting persists across page loads via localStorage. Users won't need to select their language again on return visits.

Identify

Authenticate and identify a user with a JWT token.

Ferndesk('identify', { jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' })

Parameters:

jwt (string, required): A signed JWT token containing user identity information.

Returns: None.

Behavior: Authenticates the user in the widget, enabling personalized help content and secure identification. The token must be generated server-side and signed with your Ferndesk secret key.

The identify method must be called from the same domain as your help center or from a 1-level subdomain (e.g., if your help center is at help.example.com, you can call identify from help.example.com or app.example.com, but not from different-domain.com).

Example — Identify logged-in user:

// After user logs in, get JWT from your backend
const userToken = await fetch('/api/ferndesk-token').then(r => r.text());

Ferndesk('init', { widgetId: 'your-widget-id' });
Ferndesk('identify', { jwt: userToken });

Call identify after init and before opening the widget. The token should include user ID, email, and any custom attributes you want to track.

For a complete guide on setting up silent user identification, see JWT Authentication.

Console errors:

Ferndesk: identify requires a jwt — jwt parameter is missing.
Ferndesk: identify failed - invalid jwt — The JWT token is malformed or signature verification failed.
Ferndesk: identify must be called from the same domain or 1-level subdomain — Domain mismatch detected.

Prefill

Save your users time by auto-filling their name and email so they don't have to type it every time they contact you.

Ferndesk('prefill', { name: 'Jane Doe', email: '[email protected]', subject: 'Billing Issue', message: 'Details here...' })

If your users are already logged in, why make them fill out the contact form from scratch? The prefill method automatically populates their information, making it easier for them to get help quickly.

Parameters: Object with optional string fields:

name (string, optional): User's name
email (string, optional): User's email address
subject (string, optional): Ticket subject line
message (string, optional): Message body

Returns: None.

How it works: When the user opens the contact form, any fields you've prefilled will already have their information. It only fills empty fields, so it won't overwrite anything they've already typed. You can call prefill before init completes and the data will be queued.

Prefill only works when your widget contact method is set to "form" (not "link"). Check your dashboard settings under Widget > Contact.

Example — Auto-fill logged-in user details:

Ferndesk('init', { widgetId: 'your-widget-id' });
Ferndesk('prefill', {
  name: user.fullName,
  email: user.email
});
Ferndesk('open');

Example — Pre-populate error reports:

// On crash page
Ferndesk('prefill', {
  subject: 'App Error',
  message: 'Error: ' + error.message
});
Ferndesk('open');

Call prefill after init but before opening the widget for best results. The prefilled data stays in place even if the user opens and closes the widget multiple times, but it clears after they submit the form.

Console warnings:

Ferndesk: 'prefill' ignored because the widget has not been initialised — Call init() first.

OpenArticle

Open a specific article in the widget.

Ferndesk('openArticle', { shortId: 'help-123', presentation: 'widget' })

Parameters:

shortId (string, required): The last part of the article's.
presentation (string, optional): How to display the article. Options: 'widget' (default), 'sidebar', 'modal', 'inline'.
anchor (HTML element, optional): Required for 'inline' presentation. The element to anchor the article near.

Returns: None.

Presentation modes:

widget (default): Article opens inside the main help widget.
sidebar: Article slides in from the right edge as a side panel.
modal: Article opens in a centered full-screen overlay.
inline: Article expands near the anchor element (requires anchor parameter).

Example — Open article in modal on button click:

document.getElementById('faq-button').addEventListener('click', () => {
  Ferndesk('openArticle', { shortId: 'faq-pricing', presentation: 'modal' });
});

Example — Open article inline next to an element:

const anchorElement = document.getElementById('billing-info');
Ferndesk('openArticle', {
  shortId: 'billing-faq',
  presentation: 'inline',
  anchor: anchorElement
});

Console errors:

Ferndesk: openArticle requires a shortId — shortId is missing.
Ferndesk: Inline floating article requires an anchor element — presentation: 'inline' but no anchor provided.
Ferndesk: openArticle ignored because the widget has not been initialised — init() hasn't been called yet.

OpenCollection

Open a specific collection in the widget.

Ferndesk('openCollection', { shortId: 'getting-started' })

Parameters:

shortId (string, required): The collection's short ID from your help center.

Returns: None.

Behavior: Opens the collection inside the widget help panel, displaying all articles in that collection.

Example — Browse troubleshooting articles:

Ferndesk('openCollection', { shortId: 'xFqsqw' });

Search

Populate the widget search and display results.

Ferndesk('search', { query: 'billing issues' })

Parameters:

query (string, required): The search query. Must be non-empty.

Returns: None.

Behavior: Opens the widget and displays search results matching the query. If no results match, displays "No results found."

Example — Search when user presses a key combination:

document.addEventListener('keydown', (e) => {
  if (e.key === '?' && e.ctrlKey) {
    Ferndesk('search', { query: 'download videos' });
  }
});

Console errors:

Ferndesk: search requires a non-empty query — query parameter is empty or missing.

Changelog methods

OpenChangelog

Open a changelog in the widget.

Ferndesk('openChangelog')

Ferndesk('openChangelog', { shortId: 'abc123' })

Ferndesk('openChangelog', 'abc123')

Parameters:

shortId (string, optional): The changelog's short ID, passed as an object property or a bare string. Without it, the widget opens the visitor's default visible changelog.

Returns: None.

Behavior: Opens the widget to the changelog view. If no visible changelog exists, the command does nothing and logs Ferndesk: This help center has no visible changelog.

GetChangelogStatus

Read whether a changelog is available and has unseen updates.

Ferndesk('getChangelogStatus')

Returns: { available: boolean, unseen: boolean }, or null before the widget has reported status. available is true when a changelog is visible to the current visitor; unseen is true when an announced entry is newer than the visitor's seen state.

Data attributes for inline triggers

In addition to SDK methods, you can use HTML data attributes to trigger widget actions without JavaScript:

data-ferndesk-article

Open an article in widget mode when clicked.

<button data-ferndesk-article="help-123">Learn More</button>

Clicking this button opens the article with ID "help-123" in the main widget panel.

Open an article in modal mode when clicked.

<a href="#" data-ferndesk-article-modal="pricing-faq">View Pricing FAQs</a>

Clicking this link opens the article in a centered modal overlay.

data-ferndesk-article-sidebar

Open an article in sidebar mode when clicked.

<button data-ferndesk-article-sidebar="troubleshooting">Troubleshoot</button>

Clicking opens the article in a slide-in sidebar.

data-ferndesk-article-inline

Open an article in inline mode anchored to the clicked element.

<button id="my-button" data-ferndesk-article-inline="quick-help">Quick Help</button>

Clicking this button opens the article inline near the button. If no anchor is found, the browser console warns and falls back to modal mode.

data-ferndesk-changelog

Open a changelog when clicked.

<button data-ferndesk-changelog>What's new</button>

With a value, the value is the changelog's short ID; without one, the widget opens the visitor's default changelog. When the changelog status is available and unseen, matching triggers show a small badge dot.

Error handling and logging

The SDK logs errors and warnings to the browser console (not shown to end-users). Common messages include:

Message	Cause	Solution
`Ferndesk: init requires a widgetId`	Missing widgetId parameter	Provide your widget ID in the init call
`Ferndesk widget failed to load widget configuration`	Invalid or expired widget ID	Verify the ID in the dashboard; regenerate if needed
`Ferndesk service not found`	SDK script didn't load (blocked by ad blocker, CSP, etc.)	Check network requests; whitelist Ferndesk domain in CSP
`Ferndesk: search requires a non-empty query`	Empty or missing search query	Provide a non-empty string for the query parameter
`Ferndesk: Inline floating article requires an anchor element`	Using inline presentation without anchor	Provide an HTML element in the anchor parameter
`Ferndesk: 'method' ignored because the widget has not been initialised`	Called a method before init() completed	Ensure init() is called before other methods (or wait for SDK load)
`Ferndesk: unknown command 'method'`	Called a non-existent method	Check the method name and spelling against the SDK reference

Content Security Policy (CSP) compliance

If your site uses a strict Content Security Policy, you may need to allowlist the Ferndesk domain:

Example CSP header:

script-src 'self' https://static.ferndesk.com;

If the SDK script is blocked by CSP, the console logs a CSP violation error. Add https://static.ferndesk.com to your script-src directive to allow it.

Performance considerations

Async loading: The SDK script loads asynchronously in the background. Your page continues loading while the SDK initializes.
Shadow DOM isolation: The widget uses shadow DOM to encapsulate styles and prevent conflicts with your site's CSS.
Lazy content loading: Articles and search results load on demand, not all at once.

Examples

Basic setup

<html>
  <body>
    <!-- Your page content -->
    
    <script src="https://static.ferndesk.com/dist/sdk.js"></script>
    <script>
      Ferndesk('init', { widgetId: 'your-widget-id' });
    </script>
  </body>
</html>

Open article on button click

<button id="help-btn">Get Help</button>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('help-btn').addEventListener('click', () => {
  Ferndesk('openArticle', {
    shortId: 'faq-overview',
    presentation: 'modal'
  });
});
</script>

Search on user input

<input id="search-input" type="text" placeholder="Search help..."/>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('search-input').addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    Ferndesk('search', { query: e.target.value });
  }
});
</script>

Context-aware help in a React app

import { useEffect, useState } from 'react';

export default function App() {
  const [currentPage, setCurrentPage] = useState('home');

  useEffect(() => {
    // Initialize SDK
    const script = document.createElement('script');
    script.src = 'https://static.ferndesk.com/dist/sdk.js';
    script.async = true;
    document.body.appendChild(script);

    script.onload = () => {
      window.Ferndesk('init', { widgetId: 'your-widget-id' });
    };
  }, []);

  useEffect(() => {
    // Hide widget on checkout page, show elsewhere
    if (currentPage === 'checkout') {
      window.Ferndesk('hide');
    } else {
      window.Ferndesk('show');
    }
  }, [currentPage]);

  return (
    <div>
      {/* Your page content */}
    </div>
  );
}

Events

Subscribe to widget events to react to user actions on your site using the Ferndesk('on', event, handler) method. Subscriptions can be queued before the widget is initialized and always return an unsubscribe function.

On

Subscribe to a widget event.

const unsubscribe = Ferndesk('on', 'quickLinkClick', (event) => {
  console.log('Link clicked:', event.label);
});

Parameters:

event (string, required): The event name to subscribe to.
handler (function, required): The callback function to run when the event fires.

Returns: An unsubscribe function. Calling it removes the listener. If the SDK has not loaded yet, the function queues an off call that runs automatically once the SDK is ready.

You can call Ferndesk('on', ...) before init() completes. The SDK replays queued commands in order after it loads.

QuickLinkClick

Fires when a visitor clicks a quick link in the widget home view.

Ferndesk('on', 'quickLinkClick', (event) => {
  if (event.id === 'custom-route') {
    event.preventDefault();
    history.pushState(null, '', event.url);
  }
});

Payload:

id (string): The link ID.
label (string): The link label.
url (string, optional): The link destination.
preventDefault() (function): Call this to stop the widget from navigating to the link URL. Use this when you want to handle the navigation yourself.
defaultPrevented (boolean, read-only): true if any handler called preventDefault().

Behavior: If preventDefault() is not called, the widget follows its normal link behavior (same tab or new tab depending on the link's Open in new tab setting). Modified clicks such as Ctrl-click, Shift-click, and middle-click always follow the browser's default behavior.

ChangelogStatus

Fires when changelog availability or unseen state changes.

Ferndesk('on', 'changelogStatus', ({ available, unseen }) => console.log(available, unseen))

Payload:

available (boolean): Whether a changelog is visible to the current visitor.
unseen (boolean): Whether an announced entry is newer than the visitor's seen state.

Behavior: Fires after the widget boots and whenever the status changes; identical status values are not re-emitted.

ChangelogOpen

Fires when the changelog view is opened.

Ferndesk('on', 'changelogOpen', ({ shortId }) => console.log(shortId))

Payload:

shortId (string or null): The opened changelog's short ID.

What's next

Learn how to embed the Self-Service Widget on your site.
Review the Self-Service Widget Overview for feature details.

Was this helpful?

Ferndesk SDK Reference

Getting started

Installation

Initialization

Core methods

Init

Hide

Show

Open

OpenHome

OpenAssistant

OpenContact

Close

Destroy

SetLocale

Identify

Prefill

Content navigation methods

OpenArticle

OpenCollection

Search

Changelog methods

OpenChangelog

GetChangelogStatus

Data attributes for inline triggers

data-ferndesk-article

data-ferndesk-article-modal

data-ferndesk-article-sidebar

data-ferndesk-article-inline

data-ferndesk-changelog

Error handling and logging

Content Security Policy (CSP) compliance

Performance considerations

Examples

Basic setup

Open article on button click

Search on user input

Context-aware help in a React app

Events

On

QuickLinkClick

ChangelogStatus

ChangelogOpen

What's next