API Reference

Overview

The Thoughtbase widget exposes a JavaScript API that you can use to initialize the widget and pass SSO via the ssoToken config option. 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
  • organizationSlug (string, required): Your Thoughtbase organization slug
  • convexUrl (string, required): Your Convex deployment URL
  • ssoToken (string, optional): JWT signed with your SSO secret to log the user into the widget.
  • 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.

Returns

undefined

Example

window.thoughtbase.initWidget({
  organizationSlug: 'your-org-slug',
  convexUrl: 'https://your-project.convex.cloud',
  selector: '#my-button'
});

// With SSO: pass ssoToken so the widget knows who the user is
window.thoughtbase.initWidget({
  organizationSlug: 'your-org-slug',
  convexUrl: 'https://your-project.convex.cloud',
  ssoToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
});

// Remove Thoughtbase branding
window.thoughtbase.initWidget({
  organizationSlug: 'your-org-slug',
  convexUrl: 'https://your-project.convex.cloud',
  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

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

Global Objects

window.thoughtbase.initWidget

The initialization function is available on the window object after the widget script loads. Pass ssoToken in the config to identify the user.

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({
    organizationSlug: 'your-org-slug',
    convexUrl: 'https://your-project.convex.cloud'
  });
</script>

With Custom Button

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

With SSO

Pass ssoToken in the config when you have the token (e.g. from your session or after fetching it):

<script src="https://app.thoughtbase.app/widget.js"></script>
<script>
  window.thoughtbase.initWidget({
    organizationSlug: 'your-org-slug',
    convexUrl: 'https://your-project.convex.cloud',
    ssoToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'  // from your backend/session
  });
</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

SSO / ssoToken Not Working

• Pass ssoToken in the initWidget config when you have the token
• Verify 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