Previewing and Integrating Widgets

Learn how to preview, authenticate, and embed Fastn widgets into your apps using iframe or React, with options for custom auth, filtering, and connector overrides.

Previewing Widgets

• On the Widgets page, click the Integrate button.

• Click Preview.

• The Preview button opens the widget preview in a new browser tab. You can change the default tenantId by updating the query parameters in the URL.

  ⚠️ The preview page always shows the DRAFT version of the widget. Use the env query parameter if you want to preview a widget that has been deployed to another environment.

Setting up Custom Authentication

• A custom authentication flow can be created to validate user tokens whenever the widget is loaded.

  To enable custom authentication:

  1. On the Widgets page, click Integrate.

  2. Go to the Settings tab.

  3. Enable Custom Authentication and click Save.

• Once saved, a flow called fastnCustomAuth is automatically imported into your workspace and can be customized as needed.

By default, this flow uses a Fastn user token, but you can update it with your own logic or API calls to validate the token.

✅ When custom authentication is enabled, the customAuth=true parameter must be included in the widget URL. This applies to both preview and iframe integration and ignores any apiKey passed in the URL.

If authentication succeeds, the widget loads normally. If it fails, an error message is displayed.

Integrating Widgets in Your App

Iframe Integration

• In the Widgets page, click Integrate.

• Select Iframe to generate the React or HTML code snippet.

• Copy and paste the code into your React application.

Update the configuration values in the snippet:

projectId: "<PROJECT_ID>", // Workspace ID where the widget is configured
tenantId: "<TENANT_ID>",   // Tenant/end user identifier
authToken: "<AUTH_TOKEN>"  // Token used in the custom auth flow

You can customize the default widget styling by clicking the Styling tab, making changes, and pressing Save.

Headless React Package

The iframe approach uses Fastn’s UI and offers limited flexibility. For full customization, Fastn provides a headless React package that exposes the APIs and lets you build your own UI.

• Package: https://www.npmjs.com/package/@fastn-ai/react-core

• Example App: https://github.com/fastnai/react-core-client

• Live Demo: https://react-core-client.pages.dev

Overriding Widget Connector Auth Attributes

• You can override the default auth attributes used by a widget’s dependency connector.

Steps

1. On the Widgets page, click the widget name to open its configuration.

1. Under Dependency Connectors, click Auth Attributes for the connector you want to override.

1. Enter the auth attribute overrides as JSON.

Example (Slack)

{
  "clientId": "<CLIENT_ID>",
  "clientSecret": "<CLIENT_SECRET>",
  "params": {
    "scope": "app_mentions:read,channels:history,channels:join,channels:manage,channels:read,chat:write.customize,chat:write.public,chat:write,files:read,files:write,groups:history,groups:read,groups:write,im:history,im:read,im:write,links:read,links:write,mpim:history,mpim:read,mpim:write,pins:read,pins:write,reactions:read,reactions:write,reminders:read,reminders:write,team:read,usergroups:read,usergroups:write,users:read,users:write,users.profile:read,users:read.email"
  }
}

Click Done, then Update to save.

From this point forward, the override credentials will be used every time a tenant uses the Slack widget.

Filtering Widgets

Fastn allows you to dynamically show or hide widgets or actions based on tenant-specific logic.

To enable filtering:

1. Go to Integrate → Settings.

2. Enable Widgets Filter.

This will import a flow called fastnWidgetsFilter into your workspace.

Every time the widget page loads, the widget list is sent to this flow for processing.

Example Input

"widgets": [
  {
    "id": "_knexa_c9085d88-85d0-4436-82c6-4e42d6aba4c6",
    "name": "Slack",
    "hidden": false,
    "disable": false,
    "subscribed": true,
    "hideActions": [],
    "disableMessage": "",
    "subscriptionUrl": "",
    "hideActionsByName": []
  }
]

You can then update these configurations in the flow to reflect business logic (e.g., hide widgets for specific tenants).

Example Output

"widgets": [
  {
    "id": "_knexa_c9085d88-85d0-4436-82c6-4e42d6aba4c6",
    "name": "Slack",
    "hidden": true,
    "disable": false,
    "subscribed": false,
    "hideActions": [],
    "disableMessage": "",
    "subscriptionUrl": "",
    "hideActionsByName": []
  }
]