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.

Web Calling is a voice widget you embed on your website. Visitors click it, their browser connects to PolyAI over WebRTC, and they’re in a call with your agent. No phone number, no app install, no callback queue. You configure it from Configure > Web Calling in Agent Studio.
Web Calling launcher in the bottom-right of a website

​
Embed it

The install is a single script tag, generated for you under Configure > Web Calling > Embed. Paste it just before </body> on your site:
<script src="https://messaging.poly.ai/widget/YOUR_UNIQUE_CODE.js"></script>
The launcher shows up bottom-right on any page that loads the script. Styling, content, and agent changes take effect on the next page load; no re-embed needed.
No website yet? Use the shareable page instead. It’s a hosted URL on PolyAI’s domain that anyone can call without logging in.
For Tag Manager, HTTPS, and the rest of the deployment details, see Install on your site. For styling, language, and consent options, see Configure.

​
The agent’s voice

Web Calling uses whichever voice you’ve set under Configure > Agent voice. The same voice plays whether someone reaches you through the embedded widget or a shareable page link.

​
Web Calling in the channel mix

Web Calling is a voice channel, just like a phone number. The only thing that changes between them is how the audio gets to PolyAI.
Web CallingNumbers (telephony)Chat (webchat)Voice (TTS settings)
What customers doClick a button on your siteDial a phone numberType in a widget on your site(configures how your agent sounds)
ModalityVoiceVoiceTextShared by all voice channels
Where you set it upConfigure > Web CallingChannels > NumbersConfigure > Web CallingChannels > Voice
DocsThis sectionNumbersWebchatVoice
Web Calling and Numbers are two ways into the same voice agent. They share the agent’s spoken voice (set once, under Channels > Voice) and the same conversation logic. Switching a visitor between them doesn’t require a separate flow.

​
What the widget does

A consent step before the mic opens. Mute and end-call controls. The usual connecting / in-call / ended / error states. Only one call active per visitor across tabs. You can lock the widget to specific domains, run multiple variants per brand or region, and surface whichever languages your agent speaks.

​
Compliance

Privacy and consent controls are off by default. Turn them on under Widget configuration.
You’re responsible for meeting transparency, disclosure, and consent requirements in every jurisdiction you operate in, particularly EU customers and some US states. Review your obligations carefully.

​
Before you embed

NeedNotes
An Agent Studio project with a published variantSandbox is fine for testing; promote to Live for real traffic.
The domain(s) the widget will load onUsed for the domain allow-list.
Access to your site’s HTML or tag managerOne script tag goes just before </body>.
HTTPS on the host pageBrowsers block mic access on insecure origins.
Phone and Chat widgets share a single Studio surface, which is why both live under Configure > Web Calling. Pick Phone or Chat when you create one.

​
Reference pages

Widget

Create, style, and configure a Web Calling widget in Agent Studio.

Installation

Embed the script tag on your website with HTML or Tag Manager.

Test widget

Walk through a real call from the editor preview link.

Troubleshooting

Mic permissions, ICE failures, cross-tab lock, and more.

​
Technical details

Web Calling is loaded by a single <script> tag on your site. The script injects an iframe pinned to the bottom-right of the page. When a visitor clicks the launcher, the widget requests microphone access, opens a WebSocket to PolyAI’s WebRTC gateway, and starts an Opus 48 kHz audio call with your agent.Two endpoints are involved:
  • HTTPS to PolyAI’s widget script endpoint, which loads the widget JS.
  • WSS to the WebRTC gateway, which carries signaling and Opus audio to your agent.
Only one Web Calling call can be active per browser at a time. The widget enforces this with a cross-tab lock so a visitor with multiple tabs open cannot start parallel calls.
Web CallingTelephony
TransportWebRTC over the browserPhone network (PSTN / SIP)
Visitor seesA widget on your websiteA phone number to dial
Latency / qualityOpus 48 kHz over WebRTCCarrier-dependent
SetupEmbed a script tagProvision a number, configure SIP
Best forWeb-first journeys, support deflectionInbound call centers, omnichannel routing
You can run both: Web Calling for visitors already on your site, telephony for callers from anywhere else. Both connect to the same agent.
The widget script also exposes a window.PolyphoneAPI object that lets your page drive the call programmatically, useful when you want to trigger Web Calling from a custom button, an in-app event, or an existing chat experience.
// Open the widget and start a call in one step.
window.PolyphoneAPI.connectAndCall();

// Pass context to the agent mid-call.
window.PolyphoneAPI.sendInfo("user_signed_in", { userId: "abc123" });

// React to lifecycle events.
window.PolyphoneAPI.onConnected(() => console.log("Call connected"));
window.PolyphoneAPI.onEnded(() => console.log("Call ended"));

// Remove a handler when you're done.
window.PolyphoneAPI.off("connected", myHandler);
Available commands: connect, disconnect, startCall, endCall, connectAndCall, mute, unmute, sendInfo, isConnected, getCurrentSession, destroy. Event registration uses dedicated methods: onReady, onConnecting, onConnected, onDisconnected, onRegistered, onUnregistered, onRinging, onAnswered, onEnded, onFailed, onMuted, onUnmuted, onCaptureAudio, onAudioEnded, onInfoSent, onInfoReceived, onTranscription, onError. Use off(eventName, handler) to remove a registered handler.
Web Calling uses standard WebRTC primitives. Verified browsers:
BrowserMinimum version
Chrome / Chromium72
Firefox60
Safari (macOS)14.1
Safari (iOS)16
Edge79
Visitors on unsupported browsers see a disabled call button with a brief explanation. Mobile-browser and in-app-webview behavior can vary, so test in your intended deployment environment before launch.
  • Voice, the agent’s TTS voice, shared by Web Calling and telephony
  • Numbers (telephony), the phone-network route into the same voice agent
  • Webchat, the text channel that uses the same widget framework
  • Variant management, per-domain or per-region widget configuration
Last modified on May 18, 2026