Install on your site

Once your widget is configured, getting it live is a single script tag. Paste it on your site, publish, and your visitors can start using it. The install flow is identical for Phone and Chat widgets.

Installation methods

Pick one route:

Option A: Direct HTML embed, recommended for most sites.
Option B: Tag Manager, when your organization manages scripts through Google Tag Manager or similar.

Not sure which route to take? Start with Option A. It’s the fastest path to live.

Go to Widgets in Agent Studio and open your widget.
Configure Styling and Content.
Click Save and publish.
Open the Embed tab.
Copy the unique script tag. It looks like this:

<script src="https://messaging.poly.ai/widget/YOUR_UNIQUE_CODE.js"></script>

Embed tab with the widget script tag ready to copy — Embed tab with the widget script tag

The tag is bound to the widget’s domain, variant, and environment. If any of those change, re-publish and re-embed.

Option A: Direct HTML embed

Open the HTML template that loads on every page (often called your global layout, base template, or index.html).
Paste the script tag just before the closing </body> tag.
Publish your website changes.

<!DOCTYPE html>
<html>
  <head>
    <!-- Your existing head content -->
  </head>
  <body>
    <!-- Your page content -->

    <!-- Paste the PolyAI widget script here, just before </body> -->
    <script src="https://messaging.poly.ai/widget/YOUR_UNIQUE_CODE.js"></script>
  </body>
</html>

You only need to embed the script once. Updates to styling, content, or the agent take effect on the next page load. No re-embed required.

Serve the host page over HTTPS. Browsers block microphone access on http://, so Phone widget call buttons stay disabled there.

Option B: Tag Manager

Open your tag manager (e.g., Google Tag Manager) and create a new Custom HTML tag.
Paste the script tag.
Set the trigger to All Pages (or restrict to the pages where you want the widget).
Publish the container.

The widget appears on the next page load.

Copy your actual script tag from Widgets > Embed. The snippet here is illustrative.

Script-tag attributes (Chat widgets)

Chat widgets accept optional data-* attributes on the <script> tag, read once at load time, no JavaScript required. Phone widgets don’t use these. Their behavior is configured entirely in the editor and driven by call state.

<script
  src="https://messaging.poly.ai/widget/YOUR_UNIQUE_CODE.js"
  data-platform="web"
  data-render-mode="default"
  data-auto-open="false"
  data-show-icon="true"
  data-show-header="true"
></script>

Attribute	Values	Default	Effect
`data-platform`	`web`, `ios`, `android`	`web`	Use `ios` or `android` inside a native WebView (`WKWebView` on iOS, `WebView` on Android). `ios` automatically applies fullscreen and hides the header. Sessions are reported as `ios-web` or `android-web` to distinguish them from native SDK sessions.
`data-render-mode`	`default`, `fullscreen`	`default`	`fullscreen` makes the chat fill the viewport, useful for dedicated chat pages or native app screens.
`data-auto-open`	`true`, `false`	`false`	Opens the chat as soon as the widget initializes.
`data-show-icon`	`true`, `false`	`true`	Show or hide the floating launcher. Combine with a custom button calling `WebchatAPI.openWidget()` for a bespoke trigger.
`data-show-header`	`true`, `false`	`true`	Show or hide the chat header. Defaults to `false` when `data-platform="ios"`.

After installing a Chat widget, you can control its position with CSS. The widget renders inside a #poly-ai-chat element. Add a <style> block in the <body> of your page:

<style>
  #poly-ai-chat {
    bottom: 1rem;
    right: 1rem;
  }
</style>

Adjust bottom and right to avoid overlap with cookie banners, navigation bars, or other fixed UI.

Device	Icon size
Desktop	60px × 60px
Mobile	44px × 44px

Account for these dimensions when positioning the widget.

Re-embedding

You only need to re-embed when the script tag itself changes. The Embed tab in Agent Studio shows a Snippet changed banner if the published script differs from the version your team has on the site. Hand the new tag to your dev team or update your tag manager configuration. You do not need to re-embed when you change:

Branding (header text, logo, agent name, primary color).
CTA copy or disclaimer.
Policy links.
The agent or variant the widget connects to (within the same widget configuration).

Verifying the install

Widget appears

The launcher renders in the bottom-right corner of pages where the script is embedded.

Widget opens

Clicking the launcher opens the widget panel.

Phone: place a call

Click Start call. The browser asks for microphone permission. Allow → the widget shows Connecting… then In call when your agent answers.

Chat: send a message

Type a message. The agent should respond with the configured greeting and answer subsequent messages.

Quick verification tips

Open your website in a private/incognito window.
Hard refresh (Ctrl+Shift+R or Cmd+Shift+R) to bypass cached scripts.
Test on a desktop browser (Chrome or Edge) and a mobile device (iOS Safari or Android Chrome).

If anything looks off, see Troubleshooting.

Cross-tab behavior (Phone widgets)

When a visitor opens your site in multiple tabs, Web Calling keeps things clean: one active call per browser. The widget writes a heartbeat to localStorage while a call is live, and other tabs show the call button disabled with a “Call active in another tab” message. Closing the active tab releases the lock within ~10 seconds. It’s automatic. No configuration needed.

Get started

Studio Assistant

Analytics

Conversations

Custom Dashboards

Behavior

Knowledge

Flows

Tools

Extend with code

Testing

Real-time config

Voice

Messaging

Integrations

Deployments

Widgets

Account

Installation methods

Step 1: Generate a widget tag

Option A: Direct HTML embed

Option B: Tag Manager

Script-tag attributes (Chat widgets)

Widget positioning (Chat widgets)

Widget icon sizes

Re-embedding

Verifying the install

Quick verification tips

Cross-tab behavior (Phone widgets)

Next steps

Test your widget

Troubleshooting

​Installation methods

​Step 1: Generate a widget tag

​Option A: Direct HTML embed

​Option B: Tag Manager

​Script-tag attributes (Chat widgets)

​Widget positioning (Chat widgets)

​Widget icon sizes

​Re-embedding

​Verifying the install

​Quick verification tips

​Cross-tab behavior (Phone widgets)

​Next steps

Test your widget

Troubleshooting

Installation methods

Step 1: Generate a widget tag

Option A: Direct HTML embed

Option B: Tag Manager

Script-tag attributes (Chat widgets)

Widget positioning (Chat widgets)

Widget icon sizes

Re-embedding

Verifying the install

Quick verification tips

Cross-tab behavior (Phone widgets)

Next steps