> ## Documentation Index > Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Embed script and TarsConfig > The embed.js script tag, the window.TarsConfig object, locale resolution, and page-context passing. export const img = { activity: { activityTimeline: "/docs/guides/activity/images/activity-timeline.png", capturedVariablesPanel: "/docs/guides/activity/images/captured-variables-panel.png", dataViewCards: "/docs/guides/activity/images/data-view-cards.png", exportDataDialog: "/docs/guides/activity/images/export-data-dialog.png", tasksPanelExportReady: "/docs/guides/activity/images/tasks-panel-export-ready.png" }, analytics: { analyticsOverview: "/docs/guides/analytics/images/analytics-overview.png", exploreGallery: "/docs/guides/analytics/images/explore-gallery.png", exploreTab: "/docs/guides/analytics/images/explore-tab.png", goalForm: "/docs/guides/analytics/images/goal-form.png", goalsTab: "/docs/guides/analytics/images/goals-tab.png", improveDiagnostics: "/docs/guides/analytics/images/improve-diagnostics.png", improveTab: "/docs/guides/analytics/images/improve-tab.png", teamTab: "/docs/guides/analytics/images/team-tab.png" }, billing: { billingOverview: "/docs/guides/billing/images/billing-overview.png", buyConversationsDialog: "/docs/guides/billing/images/buy-conversations-dialog.png", buySeatsDialog: "/docs/guides/billing/images/buy-seats-dialog.png", livechatSeatsTab: "/docs/guides/billing/images/livechat-seats-tab.png", organizationDeletionLifecycle: "/docs/guides/billing/images/organization-deletion-lifecycle.svg", organizationSwitcher: "/docs/guides/billing/images/organization-switcher.png", rolesAndAccessMatrix: "/docs/guides/billing/images/roles-and-access-matrix.png" }, building: { agentBehaviorGuardrails: "/docs/guides/building/images/agent-behavior-guardrails.png", agentCardMenu: "/docs/guides/building/images/agent-card-menu.png", agentConfigure: "/docs/guides/building/images/agent-configure.png", agentExitRoutesDialog: "/docs/guides/building/images/agent-exit-routes-dialog.png", agentLibrary: "/docs/guides/building/images/agent-library.png", agentModelParameters: "/docs/guides/building/images/agent-model-parameters.png", aiAgentGambitLoop: "/docs/guides/building/images/ai-agent-gambit-loop.svg", builderBasics: "/docs/guides/building/images/builder-basics.png", builderConnectHandlePanel: "/docs/guides/building/images/builder-connect-handle-panel.png", builtInToolsDialog: "/docs/guides/building/images/built-in-tools-dialog.png", configureDebugTab: "/docs/guides/building/images/configure-debug-tab.png", configureLanguage: "/docs/guides/building/images/configure-language.png", configureNotifications: "/docs/guides/building/images/configure-notifications.png", createAgentDialog: "/docs/guides/building/images/create-agent-dialog.png", draftPublishRollbackPinning: "/docs/guides/building/images/draft-publish-rollback-pinning.svg", draftSwitcherChip: "/docs/guides/building/images/draft-switcher-chip.png", duplicateAgentDialog: "/docs/guides/building/images/duplicate-agent-dialog.png", flowConditions: "/docs/guides/building/images/flow-conditions.png", gambitPalette: "/docs/guides/building/images/gambit-palette.png", gambits: { gambitAiAgent: "/docs/guides/building/gambits/images/gambit-ai-agent.png", gambitApiCall: "/docs/guides/building/gambits/images/gambit-api-call.png", gambitAutoSuggestion: "/docs/guides/building/gambits/images/gambit-auto-suggestion.png", gambitButton: "/docs/guides/building/gambits/images/gambit-button.png", gambitCard: "/docs/guides/building/gambits/images/gambit-card.png", gambitChannel: "/docs/guides/building/gambits/images/gambit-channel.png", gambitCustomCode: "/docs/guides/building/gambits/images/gambit-custom-code.png", gambitDateTime: "/docs/guides/building/gambits/images/gambit-date-time.png", gambitGeoLocation: "/docs/guides/building/gambits/images/gambit-geo-location.png", gambitLanguage: "/docs/guides/building/gambits/images/gambit-language.png", gambitLiveChat: "/docs/guides/building/gambits/images/gambit-live-chat.png", gambitMediaUpload: "/docs/guides/building/gambits/images/gambit-media-upload.png", gambitNoInput: "/docs/guides/building/gambits/images/gambit-no-input.png", gambitRedirect: "/docs/guides/building/gambits/images/gambit-redirect.png", gambitStarRating: "/docs/guides/building/gambits/images/gambit-star-rating.png", gambitStartAndEnd: "/docs/guides/building/gambits/images/gambit-start-and-end.png", gambitText: "/docs/guides/building/gambits/images/gambit-text.png", gambitTrigger: "/docs/guides/building/gambits/images/gambit-trigger.png" }, languagesTranslateGambit: "/docs/guides/building/images/languages-translate-gambit.png", languageSystemMessages: "/docs/guides/building/images/language-system-messages.png", newDraftDialog: "/docs/guides/building/images/new-draft-dialog.png", outputComponentsGrid: "/docs/guides/building/images/output-components-grid.png", publishDialog: "/docs/guides/building/images/publish-dialog.png", systemPromptDialog: "/docs/guides/building/images/system-prompt-dialog.png", testModeEventLog: "/docs/guides/building/images/test-mode-event-log.png", testModePanel: "/docs/guides/building/images/test-mode-panel.png", validationProblemsPanel: "/docs/guides/building/images/validation-problems-panel.png", variablePickerPanel: "/docs/guides/building/images/variable-picker-panel.png", variablePillInserted: "/docs/guides/building/images/variable-pill-inserted.png", versionsDraftsPanel: "/docs/guides/building/images/versions-drafts-panel.png" }, campaigns: { campaignFlavorsTriggers: "/docs/guides/campaigns/images/campaign-flavors-triggers.svg", campaignReplyRouting: "/docs/guides/campaigns/images/campaign-reply-routing.svg", campaignSendAnatomy: "/docs/guides/campaigns/images/campaign-send-anatomy.svg", createACampaign: "/docs/guides/campaigns/images/create-a-campaign.png", walletReserveSettleRefund: "/docs/guides/campaigns/images/wallet-reserve-settle-refund.svg", webhookCampaignContractLocking: "/docs/guides/campaigns/images/webhook-campaign-contract-locking.svg", webhookCampaignLifecycleStates: "/docs/guides/campaigns/images/webhook-campaign-lifecycle-states.svg", webhookCampaignOneCallOneDelivery: "/docs/guides/campaigns/images/webhook-campaign-one-call-one-delivery.svg" }, channels: { distributeWhatsappConnect: "/docs/guides/channels/images/distribute-whatsapp-connect.png", whatsappConnectDialogWaiting: "/docs/guides/channels/images/whatsapp-connect-dialog-waiting.png", whatsappEmptyState: "/docs/guides/channels/images/whatsapp-empty-state.png" }, deploy: { bridgeEventGambitSection: "/docs/guides/deploy/images/bridge-event-gambit-section.png", deploymentSurfacesAndChannels: "/docs/guides/deploy/images/deployment-surfaces-and-channels.svg", designAgentTab: "/docs/guides/deploy/images/design-agent-tab.png", designLauncherTab: "/docs/guides/deploy/images/design-launcher-tab.png", embedIframeTab: "/docs/guides/deploy/images/embed-iframe-tab.png", embedTheWidget: "/docs/guides/deploy/images/embed-the-widget.png", mobileAppIntegration: "/docs/guides/deploy/images/mobile-app-integration.png", onYourDomain: "/docs/guides/deploy/images/on-your-domain.png", shareYourAgentLink: "/docs/guides/deploy/images/share-your-agent-link.png" }, developer: { api: { channelSendTemplateVsMessage: "/docs/developer/api/images/channel-send-template-vs-message.svg", endUsers: { endUsersListCursorPagination: "/docs/developer/api/end-users/images/end-users-list-cursor-pagination.svg" }, triggerCallConversationLifecycle: "/docs/developer/api/images/trigger-call-conversation-lifecycle.svg" }, developerSurfacesMap: "/docs/developer/images/developer-surfaces-map.svg", embed: { embedConfigToWidgetContext: "/docs/developer/embed/images/embed-config-to-widget-context.svg", hostPageBridgeFlow: "/docs/developer/embed/images/host-page-bridge-flow.svg", identitySigningFlow: "/docs/developer/embed/images/identity-signing-flow.svg", scriptVsIframeEmbed: "/docs/developer/embed/images/script-vs-iframe-embed.svg" }, mobile: { bridgeMessageProtocol: "/docs/developer/mobile/images/bridge-message-protocol.svg", webviewBridgeArchitecture: "/docs/developer/mobile/images/webview-bridge-architecture.svg" } }, endUsers: { anonymousToIdentifiedProfile: "/docs/guides/end-users/images/anonymous-to-identified-profile.svg", bulkActionBar: "/docs/guides/end-users/images/bulk-action-bar.png", campaignConsentGate: "/docs/guides/end-users/images/campaign-consent-gate.svg", consentPerChannelStates: "/docs/guides/end-users/images/consent-per-channel-states.svg", dynamicVsStaticSegments: "/docs/guides/end-users/images/dynamic-vs-static-segments.svg", endUserDirectory: "/docs/guides/end-users/images/end-user-directory.png", endUserProfileAcrossChannels: "/docs/guides/end-users/images/end-user-profile-across-channels.svg", endUserProfilePanes: "/docs/guides/end-users/images/end-user-profile-panes.png", profileMergeAndTakeoverProtection: "/docs/guides/end-users/images/profile-merge-and-takeover-protection.svg", segmentBuilder: "/docs/guides/end-users/images/segment-builder.png", segmentsPage: "/docs/guides/end-users/images/segments-page.png" }, getStarted: { agentStates: "/docs/get-started/images/agent-states.svg", buildToLivePath: "/docs/get-started/images/build-to-live-path.svg", dashboardSidebarMap: "/docs/get-started/images/dashboard-sidebar-map.png", organizationOwnershipAndRoles: "/docs/get-started/images/organization-ownership-and-roles.svg", quickstart: { step1CreateYourAccount: "/docs/get-started/images/quickstart/step-1-create-your-account.png", step3ConnectTheAiAgent: "/docs/get-started/images/quickstart/step-3-connect-the-ai-agent.png", step4TestMode: "/docs/get-started/images/quickstart/step-4-test-mode.png" }, quickstartCanvas: "/docs/get-started/images/quickstart-canvas.png" }, knowledge: { addASource: "/docs/guides/knowledge/images/add-a-source.png", addRetrieverPicker: "/docs/guides/knowledge/images/add-retriever-picker.png", attachKnowledgeGambit: "/docs/guides/knowledge/images/attach-knowledge-gambit.png", configureARetriever: "/docs/guides/knowledge/images/configure-a-retriever.png", createKnowledgeBaseDialog: "/docs/guides/knowledge/images/create-knowledge-base-dialog.png", customRetrieverDialog: "/docs/guides/knowledge/images/custom-retriever-dialog.png", datasetTab: "/docs/guides/knowledge/images/dataset-tab.png", documentChangeReindexLifecycle: "/docs/guides/knowledge/images/document-change-reindex-lifecycle.svg", documentsTabPreview: "/docs/guides/knowledge/images/documents-tab-preview.png", importAWebsite: "/docs/guides/knowledge/images/import-a-website.png", kbList: "/docs/guides/knowledge/images/kb-list.png", retrieverIndexStates: "/docs/guides/knowledge/images/retriever-index-states.svg", retrieverQueryPipeline: "/docs/guides/knowledge/images/retriever-query-pipeline.svg", standardVsParentChildChunking: "/docs/guides/knowledge/images/standard-vs-parent-child-chunking.svg", syncManagement: "/docs/guides/knowledge/images/sync-management.png", testRetriever: "/docs/guides/knowledge/images/test-retriever.png" }, liveChat: { agentWorkspace: "/docs/guides/live-chat/images/agent-workspace.png", assignedAgentPicker: "/docs/guides/live-chat/images/assigned-agent-picker.png", automaticAssignmentRouting: "/docs/guides/live-chat/images/automatic-assignment-routing.svg", availabilityDropdown: "/docs/guides/live-chat/images/availability-dropdown.png", cannedResponses: "/docs/guides/live-chat/images/canned-responses.png", composerPreferences: "/docs/guides/live-chat/images/composer-preferences.png", copilotPanel: "/docs/guides/live-chat/images/copilot-panel.png", filterConversationsDialog: "/docs/guides/live-chat/images/filter-conversations-dialog.png", inboxAnalyticsTab: "/docs/guides/live-chat/images/inbox-analytics-tab.png", inboxAvailabilityTab: "/docs/guides/live-chat/images/inbox-availability-tab.png", inboxesSettings: "/docs/guides/live-chat/images/inboxes-settings.png", inboxRoutingTab: "/docs/guides/live-chat/images/inbox-routing-tab.png", labelsSettings: "/docs/guides/live-chat/images/labels-settings.png", newAttributeDialog: "/docs/guides/live-chat/images/new-attribute-dialog.png", newCannedResponseDialog: "/docs/guides/live-chat/images/new-canned-response-dialog.png", notificationPreferences: "/docs/guides/live-chat/images/notification-preferences.png", notificationsPage: "/docs/guides/live-chat/images/notifications-page.png", pickupTargetCard: "/docs/guides/live-chat/images/pickup-target-card.png", resolveMenu: "/docs/guides/live-chat/images/resolve-menu.png", searchDialog: "/docs/guides/live-chat/images/search-dialog.png", seatGateConversation: "/docs/guides/live-chat/images/seat-gate-conversation.png", seatsSettings: "/docs/guides/live-chat/images/seats-settings.png", workTheInbox: "/docs/guides/live-chat/images/work-the-inbox.png" }, security: { addOpenRouterKeyDialog: "/docs/guides/security/images/add-open-router-key-dialog.png", auditChainVerified: "/docs/guides/security/images/audit-chain-verified.png", auditEventDrawer: "/docs/guides/security/images/audit-event-drawer.png", auditExportDialog: "/docs/guides/security/images/audit-export-dialog.png", auditLogViewer: "/docs/guides/security/images/audit-log-viewer.png", auditRecordLifecycle: "/docs/guides/security/images/audit-record-lifecycle.svg", logPrivacyRedactionEnabled: "/docs/guides/security/images/log-privacy-redaction-enabled.png", modelProviderEmptyState: "/docs/guides/security/images/model-provider-empty-state.png", privacySettings: "/docs/guides/security/images/privacy-settings.png", siemConnectWizard: "/docs/guides/security/images/siem-connect-wizard.png", supportActorMasking: "/docs/guides/security/images/support-actor-masking.svg" }, tools: { addToolModal: "/docs/guides/tools/images/add-tool-modal.png", addToolsPanel: "/docs/guides/tools/images/add-tools-panel.png", codekitActionEditor: "/docs/guides/tools/images/codekit-action-editor.png", codekitConnectToolkitsDialog: "/docs/guides/tools/images/codekit-connect-toolkits-dialog.png", codekitSchemaDialog: "/docs/guides/tools/images/codekit-schema-dialog.png", codekitToolkit: "/docs/guides/tools/images/codekit-toolkit.png", codekitToolkitAnatomy: "/docs/guides/tools/images/codekit-toolkit-anatomy.svg", createActionDialog: "/docs/guides/tools/images/create-action-dialog.png", createCodekitDialog: "/docs/guides/tools/images/create-codekit-dialog.png", responseFilteringDialog: "/docs/guides/tools/images/response-filtering-dialog.png", toolGambitEditorAgentMode: "/docs/guides/tools/images/tool-gambit-editor-agent-mode.png", toolGambitEditorWorkflowMode: "/docs/guides/tools/images/tool-gambit-editor-workflow-mode.png", toolkitDetail: "/docs/guides/tools/images/toolkit-detail.png", toolsConnected: "/docs/guides/tools/images/tools-connected.png", toolsDirectory: "/docs/guides/tools/images/tools-directory.png", viewActionsModal: "/docs/guides/tools/images/view-actions-modal.png", workflowModeResponse: "/docs/guides/tools/images/workflow-mode-response.png" } }; 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 `` tag. ```html theme={null} ``` 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](/docs/developer/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. ```html theme={null} ``` | 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](/docs/developer/embed/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. 1. `TarsConfig.lang` 2. The host page's `?lang=` URL parameter 3. The browser's `navigator.language` Only the primary language code is used, so `en-US` resolves to `en`. ## Context passed to the widget 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. ## Related pages * [Widget JS API](/docs/developer/embed/widget-js-api) * [Host page events](/docs/developer/embed/host-page-events) * [Identity signing](/docs/developer/embed/identity-signing) * [Embed the widget](/docs/guides/deploy/embed-the-widget)