Skip to main content

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.

Embedding Web Calling is one script tag, generated for you in Agent Studio.

​
Step 1: Get your script tag

  1. Open your Web Calling widget under Configure > Web Calling in Agent Studio.
  2. Make sure Styling and Content are how you want them.
  3. Click Save and publish.
  4. Open the Embed tab.
  5. Copy the 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
The tag is bound to the widget’s domain, variant, and environment. If any of those change, re-publish and re-embed.

​
Step 2: Paste it on your site

Pick one route. Most sites use the direct HTML embed.

​
Option A: Direct HTML embed

  1. Open the HTML template that loads on every page (often your global layout or index.html).
  2. Paste the script tag just before </body>.
  3. 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 embed the script once. Updates to styling, content, or the agent itself take effect on the next page load. No re-embed needed.
The script must be served over HTTPS. The host page also needs to be in a secure context because browsers block microphone access on insecure origins. The call button stays disabled on http:// pages.

​
Option B: Tag Manager

  1. Open your tag manager (Google Tag Manager or similar) and create a new Custom HTML tag.
  2. Paste the script tag.
  3. Set the trigger to All Pages (or restrict to the pages where you want the widget).
  4. Publish the container.
The widget appears on the next page load.
Always copy the actual script tag from Configure > Web Calling > Embed in Agent Studio. The one in this guide is illustrative.

​
Step 3: Verify

1

Widget appears

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

Widget opens

Click the launcher; the call panel opens.
3

Place a call

Click Start call. The browser asks for microphone permission. Allow → the widget shows Connecting… then In call when the agent answers.
A few quick verification tips:
  • Open your site in a private/incognito window so you’re not running on a cached script.
  • Hard-refresh (Ctrl+Shift+R / Cmd+Shift+R).
  • Test on a desktop browser (Chrome or Edge) and a mobile device (iOS Safari or Android Chrome).
If something looks off, see Troubleshooting.

​
Cross-tab behavior

If a visitor opens your site in multiple tabs, only one call can be active at a time. The widget writes a heartbeat to localStorage; 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. Automatic, no config.

​
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 when that happens. Hand the new tag to your dev team or update your tag manager config.You do not re-embed when you change branding, CTA copy, disclaimer text, policy links, or the agent/variant. Those propagate on the next page load.
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.

​
Step 1: Generate a widget tag

  1. Go to Configure > Web Calling in Agent Studio and open your widget.
  2. Configure Styling and Content.
  3. Click Save and publish.
  4. Open the Embed tab.
  5. 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
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

  1. Open the HTML template that loads on every page (often called your global layout, base template, or index.html).
  2. Paste the script tag just before the closing </body> tag.
  3. 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.
The script must be served over HTTPS. For Phone widgets, the host page must also be in a secure context. Browsers block microphone access on insecure origins, so the call button is disabled on http:// pages.

​
Option B: Tag Manager

  1. Open your tag manager (e.g., Google Tag Manager) and create a new Custom HTML tag.
  2. Paste the script tag.
  3. Set the trigger to All Pages (or restrict to the pages where you want the widget).
  4. Publish the container.
The widget appears on the next page load.
Always retrieve your actual script tag from Configure > Web Calling > Embed in Agent Studio. The tag in this guide is illustrative only.

​
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>
AttributeValuesDefaultEffect
data-platformweb, ioswebUse ios inside WKWebView. Automatically applies fullscreen and hides the header.
data-render-modedefault, fullscreendefaultfullscreen makes the chat fill the viewport, useful for dedicated chat pages or native app screens.
data-auto-opentrue, falsefalseOpens the chat as soon as the widget initializes.
data-show-icontrue, falsetrueShow or hide the floating launcher. Combine with a custom button calling WebchatAPI.openWidget() for a bespoke trigger.
data-show-headertrue, falsetrueShow or hide the chat header. Defaults to false when data-platform="ios".

​
Widget positioning (Chat widgets)

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.

​
Widget icon sizes

DeviceIcon size
Desktop60px × 60px
Mobile44px × 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

1

Widget appears

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

Widget opens

Clicking the launcher opens the widget panel.
3

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.
4

Chat: send a message

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

​
Quick verification tips

  1. Open your website in a private/incognito window.
  2. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R) to bypass cached scripts.
  3. 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.

​
Next steps

Test your widget

Walk through a real call from the editor preview link (Phone widgets).

Troubleshooting

Common installation issues and fixes.
Last modified on May 18, 2026