API Reference

Overview

The Thoughtbase widget exposes a JavaScript API that you can use to initialize the widget and identify users. This reference documents all available functions and their parameters.

Functions

initWidget(config)

Initializes the widget on your page. This function must be called before using any other widget functions.

Parameters

• config (object, required): Configuration object
  • organizationId (string, required): Your Thoughtbase organization ID
  • selector (string, optional): CSS selector for a custom trigger button. If provided, the default floating button will be hidden.
  • thoughtbaseBranding (boolean, optional): Set to false to remove the “Powered by Thoughtbase” branding from the widget footer. Only available on the Pro and Business plans.

Returns

undefined

Example

window.thoughtbase.initWidget({
  organizationId: 'org-123',
  selector: '#my-button'
});

// Remove Thoughtbase branding
window.thoughtbase.initWidget({
  organizationId: 'org-123',
  thoughtbaseBranding: false
});

Notes

• This function should be called once per page load
• If called multiple times, subsequent calls are ignored
• The widget creates a Shadow DOM container to isolate styles
• The widget script must be loaded before calling this function

thoughtbase.identify(token)

Identifies a user in the widget using an SSO token. This allows you to track which users submitted feedback and maintain user context.

Parameters

• token (string, required): JWT token signed with your SSO secret. The token should contain:
  • userId: User ID from your system
  • email: User’s email address
  • organizationId: Your Thoughtbase organization ID

Returns

undefined

Example

window.thoughtbase.identify('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

Notes

• The widget must be initialized before calling this function
• The token should be generated server-side using your SSO secret
• Tokens expire after the time specified during generation
• Call this function after a user logs into your application

Error Handling

If the widget is not initialized, this function will log an error to the console:

console.error("Feedback Widget: Initialize widget before calling identify");

Global Objects

window.thoughtbase.initWidget

The initialization function is available on the window object after the widget script loads.

window.thoughtbase.identify

An object containing widget functions, available after initialization:

• identify(token): Identify a user with an SSO token

Widget Behavior

Initialization

When initWidget is called:

1. A container element is created in the document body
2. A Shadow DOM is attached to the container
3. The widget React component is rendered inside the Shadow DOM
4. Event listeners are set up for the trigger button

Custom Selector

If a selector is provided:

• The default floating button is not rendered
• Click events on elements matching the selector open the widget
• Multiple elements can match the selector (all will trigger the widget)

SSO Token Storage

SSO tokens are stored in memory (not in localStorage or cookies) for security:

• Tokens are passed to API requests when creating ideas
• Tokens are included in URLs when linking to idea pages
• Tokens are cleared when the page is refreshed

Error Handling

The widget handles errors gracefully:

• Initialization errors: Logged to console, widget may not appear
• API errors: Logged to console, user sees generic error message
• SSO errors: Logged to console, widget continues to work without SSO

Browser Compatibility

The widget requires:

• Modern browsers with Shadow DOM support
• JavaScript enabled
• No Content Security Policy restrictions on inline scripts

Examples

Basic Integration

<script src="https://app.thoughtbase.app/widget.js"></script>
<script>
  window.thoughtbase.initWidget({
    organizationId: 'your-org-id'
  });
</script>

With Custom Button

<button id="feedback-btn">Give Feedback</button>
<script src="https://app.thoughtbase.app/widget.js"></script>
<script>
  window.thoughtbase.initWidget({
    organizationId: 'your-org-id',
    selector: '#feedback-btn'
  });
</script>

With SSO

<script src="https://app.thoughtbase.app/widget.js"></script>
<script>
  window.thoughtbase.initWidget({
    organizationId: 'your-org-id'
  });
  
  // After user login
  async function onLogin(userId) {
    const token = await getSSOToken(userId);
    window.thoughtbase.identify(token);
  }
</script>

Troubleshooting

Widget Not Initializing

• Check browser console for errors
• Verify the script loaded successfully
• Ensure organizationId is correct
• Check for JavaScript errors blocking execution

Identify Not Working

• Verify widget is initialized first
• Check token format and expiration
• Ensure SSO secret matches
• Check browser console for errors

Support

For additional help:

• Check the Getting Started Guide
• Review the SSO Integration Guide
• Contact support through your Thoughtbase dashboard