Attributes Reference

All configuration for the <saytv-chat> web component is done through HTML attributes.

Configuration Attributes

Attribute	Type	Default	Description
app-id	string	-	App identifier. Used to resolve the API URL automatically.
env	'production' | 'staging'	'production'	API environment. Used with app-id to resolve the correct API URL.
apiurl	string	-	Direct API base URL. Overrides app-id and env resolution.
auth-token	string	-	JWT access token for external authentication. When set, the SDK exchanges it for a SayTV session token.
built-in-auth	'true' | 'false'	'true'	Whether to show the built-in login/register UI. Set to 'false' when using external auth.
fanzone	'true' | 'false'	'false'	Enable the Fanzone feature.
height	number	850	Widget height in pixels.
width	string	'450px'	Widget width. Accepts any CSS value (e.g., '100%', '500px').
mode	'page-chat'	-	Enables page chat mode. The SDK auto-creates an episode tied to the current page.
page-id	string	window.location.href	Unique identifier for a page chat. Pages with the same page-id share the same chat. Only used when mode="page-chat".
page-name	string	document.title	Display name shown in the chat header for page chat. Only used when mode="page-chat".
theme	'light' | 'dark'	'light'	Color theme.
custom-tab-url	string	-	URL to load in a custom iframe tab. The tab only appears when this attribute is set.
custom-tab-label	string	'Custom'	Label text for the custom tab in the footer.
custom-tab-icon	string	Globe icon	Icon for the custom tab. Accepts a predefined name (home, chat, heart, trophy, search, flag, users, hash, info, lightbulb, mail, fanzone) or an SVG URL (https://...).

Connecting to the API

You have two options for configuring the API connection:

Option 1: App ID (Recommended)

<saytv-chat app-id="your-app-id"></saytv-chat>

The SDK resolves the API URL from the app-id and env attributes. This is the recommended approach.

For staging:

<saytv-chat app-id="your-app-id" env="staging"></saytv-chat>

Option 2: Direct URL

<saytv-chat apiurl="https://your-api.example.com/api/v3"></saytv-chat>

The apiurl attribute takes precedence over app-id/env.

Custom Tab

Add a custom tab to the footer that loads an external URL in an iframe:

<saytv-chat
  app-id="your-app-id"
  custom-tab-url="https://example.com/shop"
  custom-tab-label="Shop"
  custom-tab-icon="trophy"
></saytv-chat>

The tab appears in the footer before the Profile tab. If custom-tab-url is not set, no tab is shown.

Icon options

Use a predefined icon name:

<saytv-chat custom-tab-url="..." custom-tab-icon="trophy"></saytv-chat>

Available names: home, chat, heart, trophy, search, flag, users, hash, info, lightbulb, mail, fanzone.

Or use a custom SVG URL:

<saytv-chat custom-tab-url="..." custom-tab-icon="https://cdn.example.com/icon.svg"></saytv-chat>

If omitted, a default globe icon is used.

Reactive Updates

All observed attributes are reactive. Changing an attribute at runtime updates the widget immediately:

const chat = document.querySelector('saytv-chat');

// Switch to dark mode
chat.setAttribute('theme', 'dark');

// Update the auth token
chat.setAttribute('auth-token', newToken);

// Resize the widget
chat.setAttribute('height', '600');
chat.setAttribute('width', '100%');

Debounced Attributes

Rapid changes to auth-token are handled efficiently to prevent unnecessary re-authentication.

Observed Attributes

All attributes listed in the Configuration Attributes table are observed. Changing any of them at runtime updates the widget immediately.