> ## Documentation Index > Fetch the complete documentation index at: https://docs.poly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configure widget > Brand your widget, write the copy, set up consent. One editor for Phone and Chat.
Build a Web Calling widget that matches your brand and ship it from **Configure > Web Calling** in Agent Studio. Three tabs: **Styling**, **Content**, **Embed**. The right rail has a live preview that updates as you type. ## Create the widget From **Configure > Web Calling**, click **Add widget** to open the dialog. Fill in: Identifies this widget. Example: "Main website" or "Support page". The domain where this widget will load. The widget only renders on this origin; embed attempts from other domains are ignored. The agent variant this widget connects to. Sandbox or Live. You can promote between them without re-embedding. Click **Add** to create the widget. You'll land in the editor. ## Styling Match the widget to your brand. Widget editor Styling tab showing Agent name field, Color theme toggle, and a live preview of the widget Display name for the agent (defaults to the variant's agent). Used in the call card. 1 to 50 characters. Example: "Emily". Choose between **Dark** or **Light**. This controls the widget background, animation, and buttons. Stored as `theme_color` on the configuration. The launcher is a 60 px circle on desktop, 44 px on mobile. Check contrast against its white iconography to keep the call button legible. ## Content Write the copy your visitor sees when they open the widget: welcome line, CTA labels, and your disclaimer. Widget editor Content tab showing disclaimer message, company policies, and a live preview with consent button Shown on the call-start screen. Defaults to "Hi I'm \[agent name], how can I help today?". Up to 100 characters. Primary CTA the visitor clicks to begin a call. Defaults to "Start call". Up to 100 characters. Label on the in-call hang-up button. Defaults to "End call". Up to 100 characters. Transient call-state strings ("Connecting…", "In call", "Mute", "Unmute", "Call ended", "Start new call", and the generic error message) aren't editable in v1. Submit a feature request if you need to localize them. ### Disclaimer and consent Privacy disclaimer and consent controls are off by default and easy to switch on when you need them. Review your transparency, disclosure, and consent requirements carefully before launch. Meeting those requirements in every jurisdiction you operate in is your responsibility, particularly for EU customers and some US states. Render the disclaimer. When enabled, both policy URLs below become required. Shown to visitors before they start a call. Up to 500 characters. Supports the inline link variables `\{{privacyPolicyUrl}}` and `\{{termsUrl}}`, replaced with the URLs you configure under **Company policies**. Default: *"By starting this call, you agree to our Privacy Policy and Terms."* Required when the disclaimer is enabled. Must be `https://`. Example: `https://example.com/privacy`. Required when the disclaimer is enabled. Must be `https://`. Example: `https://example.com/terms`. ## Embed When you're happy with the widget, the **Embed** tab gives you a copyable script tag. Paste it before `` on your site and you're live. See [Install on your site](/widgets/install). Embed tab showing the copyable script tag and publish status The Embed tab shows: * **Status**: Live, Draft, or Archived. * **Script tag**: paste before `` on your site. * **Last published**: timestamp of the most recent publish to this environment. * **Snippet changed** banner: appears when the published script tag differs from the current draft (your dev team needs to re-embed). ## Save and publish The publish button lives in the top-right of the editor: 1. Edits save locally as you type and reflect in the live preview. 2. Click **Save and publish** to deploy to the selected environment. 3. A confirmation modal asks you to confirm. 4. A bottom-right toast confirms "Widget published". If you change the script tag (for example by switching variants), the Embed tab shows a snippet-changed warning so you can hand the new tag to your dev team. ## Multiple widgets You can run more than one widget per project. Each gets its own branding and policies. Common patterns: * **Per domain** : different branding for `example.com` and `support.example.com`. * **Per region** : a UK widget on a UK variant, a US widget on a US variant. * **Per environment** : isolate a Sandbox widget for QA from your Live widget. ## Next steps Embed the script via direct HTML or Tag Manager. Hosted preview for stakeholder review.
Build a widget that matches your brand and ship it from a single editor in Agent Studio. The editor is the same whether you're configuring a Phone or Chat widget. Differences are called out inline. ## Creating a widget From **Configure > Web Calling**, click **Add widget** to open the **Add widget** dialog. (When no widgets exist yet, the page shows an empty state with the same button.) The dialog asks you to pick a **Widget type** first (**Phone** for Web Calling, **Chat** for Webchat), then fill in: A name to identify this widget (e.g., "Main website", "Support landing page"). The domain where this widget will load. The widget only renders on this origin. Embed attempts from other domains are ignored. The [variant](/variant-management/introduction) this widget connects to. Use variants for location-specific or A/B-tested deployments. Sandbox, Pre-release, or Live. You can promote a widget through environments without re-embedding. Click **Add** to create the widget. You'll land in the editor. The **Chat** widget type is disabled until you've completed [Chat configuration](/webchat/chat-configuration). **Phone** widgets are available out of the box, no chat agent required. ## Widget editor The editor has three tabs: **Styling**, **Content**, and **Embed**. A live preview panel on the right updates as you type. ### Header controls * **Widget selector**: switch between widgets in this project. * **Widget type indicator**: shows whether you're editing a Phone or Chat widget. Set at creation, can't be changed later. * **Save and publish**: deploy changes to the selected environment. * **Unpublished changes** indicator: appears when the widget has unsaved or unpublished edits. ## Styling tab Match the widget to your brand. Some controls are shared, others are type-specific. The editor only shows the fields that apply to the widget you're editing. Widget editor Styling tab with agent name and color theme controls ### Shared Display name for the agent (defaults to the variant's agent). Used in both the call card (Phone) and the chat header / message rows (Chat). 1 to 50 characters. Example: "Emily". The launcher is a 60 px circle on desktop, 44 px on mobile. Check contrast against its white iconography to keep the call/chat button legible. ### Phone-only Choose between **Dark** or **Light**. This controls the widget background, animation, and buttons. Stored as `theme_color` (`"dark"` or `"light"`) on the Web Calling configuration. Custom hex values aren't supported in v1. ### Chat-only These fields appear only when the widget type is **Chat**: Accent color for suggestion bubbles, the widget button, header, and user chat bubbles. Enter a hex code. Example: `#c3da28`. Stored as `color` on the Webchat configuration. The title shown in the chat header. Use your brand or product name. Example: "Acme Support". Optional. Logo or wordmark for the chat header. JPEG / JPG / PNG up to 2 MB. Min. 400 × 100 px (recommended 800 × 200 px). Choose a fit option of **Fit** (preserve aspect ratio) or **Fill** (crop to frame). Optional. Avatar shown alongside agent messages. JPEG / JPG / PNG / static GIF up to 1 MB. Min. 128 × 128 px (recommended 256 × 256 px). Same Fit / Fill options. Phone widgets don't render a header logo or agent avatar. The call card is intentionally minimal so the focus stays on the live audio. Use the agent name and primary color to brand it. ## Content tab Write the copy your visitor sees when they open the widget: welcome message, CTAs, and your disclaimer. Widget editor Content tab showing disclaimer message, company policies, and live consent preview ### Welcome message Shown on the widget's start screen. Phone widgets default to "Hi I'm \[agent name], how can I help today?". For Chat, the conversation greeting comes from the agent's [chat configuration](/webchat/chat-configuration), not the widget. Up to 100 characters. ### Phone-only: call-to-action labels Primary CTA the visitor clicks to begin a call. Defaults to "Start call". Up to 100 characters. Label on the in-call hang-up button. Defaults to "End call". Up to 100 characters. For Phone widgets, transient call-state strings ("Connecting…", "In call", "Mute", "Unmute", "Call ended", "Start new call", and the generic error message) are not editable in v1. Submit a feature request if you need to localize them. ### Disclaimer and consent PolyAI gives you optional controls for privacy disclaimer and consent. They're off by default and easy to switch on when you need them. Review your transparency, disclosure, and consent requirements carefully before launch. Meeting those requirements in every jurisdiction you operate in is your responsibility, particularly for EU customers and some US states. Toggle to render the disclaimer. When enabled, both policy URLs below become required. Shown to visitors before they start. Up to 500 characters. Supports the inline link variables `\{{privacyPolicyUrl}}` and `\{{termsUrl}}`, which are replaced with the URLs you configure under **Company policies**. Phone default: *"By starting this call, you agree to our Privacy Policy and Terms."*\ Chat default: *"This is an AI-powered system and responses should be verified. All chats are recorded in order to respond to your query and for training and quality control purposes."* **Chat widgets only.** When enabled, users must click "I consent and start chat" before the conversation begins. ### Company policies Required when the disclaimer is enabled. Must be `https://`. Example: `https://example.com/privacy`. Required when the disclaimer is enabled. Must be `https://`. Example: `https://example.com/terms`. ### Chat-only: launcher and behavior Chat widgets expose extra runtime controls that don't apply to Phone: | Control | Where it's set | Effect | | -------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Render mode | Editor + `data-render-mode` script attribute | `default` (floating launcher + panel) or `fullscreen` (chat fills the viewport, launcher hidden). | | Auto-open | `data-auto-open="true"` on the script tag | Opens the chat as soon as the widget initializes. Useful for dedicated chat pages. | | Show / hide launcher | `data-show-icon="false"` on the script tag, plus `WebchatAPI.showIcon()` / `hideIcon()` at runtime | Use to hook up a custom trigger button on your site. | | Header visibility | `data-show-header` on the script tag, plus per-element flags in `visibilityConfig` | Show or hide the header, minimize button, close button, privacy link, terms link, and "Start new chat" button. | | Prompt bubble | Default text + background color in the editor; runtime calls via `WebchatAPI.showBubble({...})` | Shows a speech bubble next to the launcher to draw attention or run a campaign. | | Launcher animation | `WebchatAPI.animateIcon({ type, durationMs })` | One of `bounce`, `grow`, `pulse`. | | iOS WebView | `data-platform="ios"` on the script tag | Forces fullscreen and hides the header so the chat looks native inside `WKWebView`. | Phone widgets don't have these knobs. The launcher renders with a fixed size, the call card is fullscreen on mobile only, and behavior is driven by call state rather than host-page config. See [Install on your site](/widgets/install) for the full script-tag attribute reference. ## Embed tab When you're happy with the widget, the **Embed** tab gives you a copyable script tag plus deployment guidance. Paste it into your site and you're live. Embed tab showing the copyable script tag and publish status The Embed tab shows: * **Status**: Live, Draft, or Archived. * **Script tag**: paste before `` on your site. See [Install on your site](/widgets/install). * **Last published**: timestamp of the most recent publish to this environment. * **Snippet changed** banner: appears when the published script tag differs from the current draft (your dev team needs to re-embed). ## Saving and publishing The publish button lives in the top-right of the editor. Widgets follow a draft → published lifecycle: 1. Edits are saved locally as you type and reflected in the live preview immediately. 2. Click **Save and publish** to deploy to the selected environment. 3. A confirmation modal asks you to confirm. Click **Publish**. 4. A bottom-right toast confirms "Widget published". 5. The **Unpublished changes** indicator clears. If you change the script tag (for example by switching variants), the Embed tab shows a snippet-changed warning so you can hand the new script to your dev team. Permissions are scoped per widget type. Publishing a Phone widget requires write access on `polyphone_configurations`; publishing a Chat widget requires write access on `webchat_configurations`. Read access on the same resources controls whether the **Widget** entry appears in the sidebar. Ask your admin if you can't see the page. ## Live preview The right rail shows a live iframe preview that updates as you edit. Confirm copy length, brand-color contrast, and disclaimer placement before publishing without leaving the editor. For Phone widgets, click **Test widget** to open a hosted preview page in a new tab where you can place a real call. See [Test your widget](/widgets/test). ## Managing multiple widgets Spin up separate widgets for different domains, variants, or environments. Each gets its own branding and policies. Use the widget selector in the header to switch between them. Common patterns: * **Per domain**: different branding for `example.com` and `support.example.com`. * **Per region**: a UK widget on a UK variant, a US widget on a US variant. * **Per environment**: isolate a Sandbox widget for QA from your Live widget. * **Per type**: a Phone widget on high-intent conversion pages, a Chat widget elsewhere. This is how multi-brand and multi-site teams ship: one editor, many widget variants, no duplicated configuration. ## Next steps Embed the script via direct HTML or Tag Manager. Hosted preview for stakeholder review. Mic, network, CSP, and rendering fixes.