Embedding the Numbers Station Widget¶

Introduction¶

You can now embed Numbers Station into your application to interact with data and analytics. The widget allows you to visualize data, generate insights, and explore your datasets directly within your existing workflows.

To embed the widget, include the following script in the app head:

<script
  src="https://widget.numbersstation.ai/loader.js"
  data-account="YOUR_ACCOUNT_NAME"
></script>

Replace YOUR_ACCOUNT_NAME with your account name. You can find your account name in your workspace URL on app.numbersstation.ai. For example, if your workspace URL is app.numbersstation.ai/acme/chats, your account name is acme.

The widget should now appear in the bottom-right of the screen.

Authentication¶

By default, the widget lets users login with the same username and password they use on app.numbersstation.ai.

For a more seamless experience, you can customize this behavior by using API keys to automatically authenticate users that are already logged in to your application. For more details, see the authentication guide. Or, simply follow the steps described below.

1. Create an API key¶

Within app.numbersstation.ai, visit the account settings page and create a new API key. If there is already an API key for your account, you can delete it and create a new one.

2. Use the API key in your backend¶

In your backend, you will use this newly created API key to create a bearer token for users that are already logged in to your application.

PythonNode.js

import requests

# Check that the user is logged in to your application. This code is
# application specific and will likely change based on your application.
current_user = get_currently_logged_in_user()

# Create a bearer token for the current user.
params = { "account_name": "YOUR_ACCOUNT_NAME", "email": current_user.email }
headers = { "x-api-key": "YOUR_API_KEY" }
url = "https://api.numbersstation.ai/api/v1/login/access-token/api-key"
res = requests.post(url, params=params, headers=headers)
res.raise_for_status()
token = res.json()["access_token"]

# Send this token to your frontend where the widget is embedded.
return token

// Check that the user is logged in to your application. This code is
// application specific and will likely change based on your application.
currentUser = await getCurrentlyLoggedInUser()

// Create a bearer token for the current user.
url = 'https://api.numbersstation.ai/api/v1/login/access-token/api-key'
res = await fetch(`${url}?account_name=${YOUR_ACCOUNT_NAME}&email=${currentUser.email}`, {
  method: 'POST',
  headers: { 'x-api-key': 'YOUR_API_KEY' },
})
token = await res.json()['access_token']

// Send this token to your frontend where the widget is embedded.
return token

Your backend will then send the generated bearer token to your application's frontend where the widget is embedded. In your frontend code, you will then need to pass that bearer token to the widget using the setBearerToken API:

<script
  src="https://widget.numbersstation.ai/loader.js"
  data-account="YOUR_ACCOUNT_NAME"
></script>
<script>
  widgetApi().then((api) => {
    // Where `token` is the generated access token from your backend.
    api.setBearerToken(token);
  });
</script>

API¶

The Numbers Station widget exposes some API methods and configuration options you can use to customize its behavior.

Methods¶

In your frontend code, you can use the API like so:

widgetApi().then((api) => {
  api.setBearerToken("pr3t3ndth15is@s3cur3b3Ar3rt0k3n");
  api.setChatId("chatID");
  api.setButtonColor("red");
});

The following methods are available to be used:

Method	Description
`expand()`	Maximizes the widget into fullscreen mode.
`hide()`	Hides the widget.
`setBearerToken(token: string)`	Sets the bearer token.
`setButtonColor(value: string)`	Sets the widget button color.
`setChatId(chatId: string)`	Navigates to the chat with the provided chat ID. Only chats belonging to the account can be passed in.
`setChatInput(value: string)`	Sets the widget chat input content.
`setShowOpenInFullButton(value: boolean)`	Sets whether the 'Open full app' button in the sidebar is shown.
`show()`	Shows the chat in full screen or in the smaller widget screen.
`toggle()`	Toggles the widget visibility between hidden or shown based on full screen or the smaller chat screen.
`toggleSidebar()`	Toggles the widget sidebar.

Attributes¶

Attributes can be passed into the script tag like so:

<script
  src="${PUBLIC_WIDGET_URL}/loader.js"
  data-account="${ACCOUNT_NAME}"
  data-show-open-in-full-button="true"
  data-button-color="#171717"
></script>

The following attributes can be passed into the script tag to customize the widget:

Attribute	Description	Type	Required
`data-account`	Sets the account name. Should be your account name on app.numbersstation.ai.	`string`	Yes
`data-show-open-in-full-button`	Sets whether the 'Open full app' button in the sidebar is shown.	`"true"` or `"false"`	No
`data-button-color`	Sets the widget button color.	`string`	No
`data-show-border`	Sets whether to show the border around the widget frame.	`"true"` or `"false"`	No
`data-show-shadow`	Sets whether to show the shadow around the widget frame.	`"true"` or `"false"`	No
`data-border-radius`	Sets the border radius of the widget frame.	`string`	No
`data-show-minimize-button`	Sets whether to show the minimize button.	`"true"` or `"false"`	No
`data-show-expand-button`	Sets whether to show the expand button.	`"true"` or `"false"`	No
`data-expanded`	Sets whether the widget is expanded by default.	`"true"` or `"false"`	No
`data-parent-element-id`	Sets the parent element ID where to append the widget. If set, then a button to open widget will not be shown.	`string`	No