Methods

JavaScript methods available on the <saytv-chat> element. Grab a reference to the element and call them directly.

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

Most configuration is done with attributes rather than methods — reach for these only when you need to drive the widget imperatively.

Member	Description
`setUsername(name)`	Rename the signed-in user. Returns a `Promise<User>`.
`translations` (setter)	Supply translation catalogs keyed by locale. See Localization.
`icons` (setter)	Override built-in icons with your own SVG strings or image URLs. See Custom Icons.

<saytv-chat-bubble> exposes setUsername() and translations too, alongside its own launcher controls — see the Bubble API.

Using React or Vue? The same operations are on the useSayTVChat() hook — see React or Vue.

setUsername()

Renames the signed-in user.

try {
  const user = await chat.setUsername('new-name');
  console.log('Renamed to', user.username);
} catch (err) {
  // err.errors.username explains why: taken, too short, or blocked by moderation
  console.error(err.errors?.username?.[0] ?? err.message);
}

When you need it

If you authenticate with an external JWT, the username claim is applied when the account is first created, and re-authenticating with a changed claim syncs it automatically. So for most hosts, renaming is already handled — just issue a new token.

Use this method when:

your app lets users rename themselves mid-session and you don't want to re-issue a JWT
you want to handle the rejection reason yourself instead of letting the claim sync silently skip a name that's taken

Rules

A username must be at least 3 characters, unique across the tenant, and pass moderation. A name held by a deleted account is released and can be claimed again.

On rejection the promise rejects with an ApiError carrying status and a field-keyed errors object:

{ status: 422, errors: { username: ['The username has already been taken.'] } }

WARNING

Guests cannot rename themselves — the call rejects with a 403. Check the user's role before offering a rename control in a guest session. See Guest Mode.

Checking a name before submitting

There is no browser-callable "is this name free" endpoint — availability checks require a tenant API key and must run from your own server (POST /users/check-username, which returns allowed, available and usable). In the browser, submit and handle the 422.

translations

A property setter, not a method — assign a map of locale → catalog:

chat.translations = {
  fr: { 'chat.input.placeholder': 'Écrivez un message…' },
};

Anything you don't translate falls back to English. Set it before or after mount; assigning it early is safe because the element reflects a value set prior to upgrade. For a hosted catalog use the translations-url attribute instead — no JavaScript needed. See Localization.

icons

A property setter that replaces built-in icons with your own:

chat.icons = {
  send: '<svg viewBox="0 0 24 24">…</svg>',
  profile: 'https://example.com/profile.png',
};

Accepts an inline SVG string or an image URL per icon. Inline SVGs using currentColor are recolored to match their context. See Custom Icons for the full list of overridable names.

Methods ​

setUsername() ​

When you need it ​

Rules ​

Checking a name before submitting ​

translations ​