Embed script and TarsConfig

This reference covers the script embed method: the tag itself, the window.TarsConfig object, and what the widget receives from the host page.

The script tag

Copy the snippet from Distribute → Widget Embed on the agent, under the HTML tab. Paste it before the closing </body> tag.

<script
  src="https://YOUR_WIDGET_HOST/embed.js"
  data-convid="YOUR_AGENT_ID"
  data-region="YOUR_REGION"
  defer
></script>

The widget host is not the API base URL. One host serves the widget for every region, and the region travels in data-region. The HTTP APIs use a per-region base URL instead, listed in API authentication.

Attribute	Description
`src`	The `embed.js` URL, exactly as generated by the dashboard
`data-convid`	The agent’s public ID. Required, unless `TarsConfig.convId` is set
`data-region`	The region code: `us` for the United States, `eu` for the European Union, `in` for India, or `qa` for Qatar. Without it, the widget uses the default region. An unknown code stops the widget from loading and logs an error in the browser console
`data-initial-view`	`conversations` opens the panel on the conversations list. Wins over `TarsConfig.initialView`
`defer`	Loads the script without blocking page rendering

The script adds a floating launcher in a shadow DOM, so host-page CSS cannot break it. The widget iframe is preloaded when the page goes idle, or on first hover of the launcher, whichever comes first.

window.TarsConfig

Set window.TarsConfig before the script tag runs to pass options and data about the end user.

<script>
  window.TarsConfig = {
    convId: "YOUR_AGENT_ID",
    lang: "en",
    name: "Ada Point",
    email: "ada@example.com",
    phone: "+15551234567",
    attributes: { plan: "premium", account_id: "ACC_123" },
    identity: { kid: "YOUR_KEY_ID", payload: "BASE64_PAYLOAD", sig: "BASE64_SIGNATURE" }
  };
</script>

Field	Type	Description
`convId`	string	Agent public ID. `data-convid` on the script tag wins when both are set
`initialView`	string	`"conversations"` opens the panel on the conversations list instead of the chat
`region`	string	The region code, for embeds with no script tag attributes, such as the GTM snippet
`lang`	string	Preferred conversation locale
`name`	string	The end user’s display name
`email`	string	The end user’s email
`phone`	string	The end user’s phone
`attributes`	object	Custom attributes attached to the conversation
`customData`	object	Legacy alias for `attributes`. When both are set, `attributes` wins
`identity`	object	Signed identity `{ kid, payload, sig }`, see Identity signing

Values from TarsConfig are unverified browser data. They personalize the conversation but never overwrite a verified identity.

Locale resolution

The widget locale resolves in this order, using the first value present.

TarsConfig.lang
The host page’s ?lang= URL parameter
The browser’s navigator.language

Only the primary language code is used, so en-US resolves to en. The script collects context and passes it to the iframe as a base64url ctx parameter, at the moment the iframe is built.

TarsConfig fields and page context combining into a base64url ctx value that is either sent to the iframe or trimmed when it exceeds the 6000 character cap

Context	Contents
Page	The page URL, the referrer, and the document title
URL parameters	Every query parameter on the host page URL
End-user data	`name`, `email`, `phone` from `TarsConfig`
Attributes	`attributes` (or the `customData` alias)
Identity	The signed identity, when present

The encoded context is capped at 6000 characters. Over the cap, attributes is dropped first. If the remainder still exceeds the cap, no context is sent.

Appearance is fetched per page load

The launcher and widget appearance load live from Tars on every page load, with a 2-second timeout per attempt. A server error is retried twice before the launcher falls back to defaults. Design changes made in the dashboard apply without re-embedding. The callout message, delay, and optional attention chime use the saved Design → Launcher settings. They are not fields in TarsConfig. Selecting the callout message opens the panel, while Dismiss closes only the callout. The sound is on by default and waits for interaction with the host page. See Design the widget for its 24-hour limit and testing steps.

Welcome

Core concepts

Guides

Developer

Embed script and TarsConfig

The script tag

window.TarsConfig

Locale resolution

Context passed to the widget

Appearance is fetched per page load

​The script tag

​window.TarsConfig

​Locale resolution

​Context passed to the widget

​Appearance is fetched per page load

​Related pages

The script tag

window.TarsConfig

Locale resolution

Context passed to the widget

Appearance is fetched per page load

Related pages