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').
hide-header	'true' | 'false'	'false'	Hide the top title bar on every page. A floating back button appears automatically whenever there is somewhere to go back to. See Sizing & Layout.
hide-footer	'true' | 'false'	'false'	Hide the bottom tab-bar navigation. See Sizing & Layout. When hidden, an avatar button appears in the chat header — or floats beside the back button if the header is hidden too — so signed-in users can still change their avatar.
hide-avatar	'true' | 'false'	'false'	Hide every entry point to the built-in avatar picker. Use it when your site owns the user's avatar: without it a user can pick one in-app, which the widget then keeps in place of the avatar-url you supply.
hide-guest-notice	'true' | 'false'	'false'	Hide the read-only bar shown to guests in place of the composer ("You're browsing as a guest…"). Use it when your own UI already explains how to sign in.
hide-badges	'true' | 'false'	'false'	Hide the Badges card on the profile screen and its page. Use it if you have not launched badges (achievements) to your audience.
hide-leaderboard	'true' | 'false'	'false'	Hide the Leaderboard card on the profile screen and its page.
hide-emoji-store	'true' | 'false'	'false'	Hide the Emojis card on the profile screen and the emoji store page. The emoji picker in the composer is unaffected.
hide-avatar-store	'true' | 'false'	'false'	Hide the Avatars card on the profile screen and the avatar store page. Users can still change their avatar from their own profile unless you also set hide-avatar.
hide-user-profiles	'true' | 'false'	'false'	Stop message authors and member-list names linking to that person's profile. Names and avatars still show — they just stop being tappable. The signed-in user's own profile is unaffected.
avatar-url	string	-	Image URL to use as the signed-in user's avatar. Applied once the user is authenticated, and skipped if the user has already chosen an avatar in-app. Ideal when your site already has the user's photo.
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.
locale	string	'en'	BCP-47 language tag for the UI (e.g. 'ar', 'pt-BR'). RTL languages lay out automatically. See Localization.
translations-url	string	-	URL of a hosted flat JSON catalog to fetch and apply for the active locale. See Localization.
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.