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.
Validate the call experience before embedding anywhere. Test widget opens a hosted preview that runs your widget against the selected environment: same agent, same audio path, same call experience as production. Good for internal demos, customer testing, or stakeholder sign-off.
Once granted, the browser remembers the permission for that origin until it’s changed.
Open the test widget
- Open your widget under Configure > Web Calling in Agent Studio.
- In the right-hand preview panel, click Test widget ↗.
- A new tab opens with a blank page hosting only your widget.
Walk through a call
Click the launcher
The launcher renders in the bottom-right of the test page. Click to open the widget.
Review the call-start screen
Your welcome message, the disclaimer (if enabled), and a primary Start call button using your brand color.
Connecting
The widget shows Connecting… while it opens a WebSocket to PolyAI’s WebRTC gateway and negotiates audio.
In call
Your agent answers and the widget switches to In call. A timer starts and the Mute button appears. Speak normally to test the conversation flow.
What to check
- Branding. Agent name and primary color match.
- Welcome and CTA copy. Read out loud to check tone.
- Disclaimer placement. Disclaimer appears above Start call, with policy links rendered as inline hyperlinks.
- Audio quality. Speak and listen for latency, dropouts, or distortion. Web Calling uses Opus 48 kHz stereo.
- Mute / unmute. Mute mid-call, confirm the agent can’t hear you, then unmute.
- Call recovery. Let the call end, then click Start new call to confirm clean reconnection.
Microphone permission
The first time someone clicks Start call on a given origin, the browser prompts for mic access:| Action | What happens |
|---|---|
| Allow | Call connects normally. |
| Block | The widget shows a Mic blocked state with steps to re-enable and a Try again button. |
| Dismiss | The widget returns to the call-start screen so the visitor can try again. |
Share the preview link
The preview URL is shareable. Send it to colleagues, customers, or your wider team to validate the experience together; no embed required.A few things to know about how the link behaves:- The token is valid for 1 hour. Generate a fresh one from the editor when you need to extend a session.
- Anyone with the link can place a call against the configured environment, so use Sandbox for share-outs unless you specifically want stakeholders on production.
- Calls placed via the preview count against your usage just like production calls.
If the test fails
See Troubleshooting. The most common issues:- Browser blocks microphone. Check the address-bar lock icon and re-allow.
- HTTPS required. The preview is always HTTPS, but if you embed the widget on an
http://site the launcher is disabled. - Stuck on Connecting… Usually a network/firewall issue blocking WebRTC.
- No audio after connect. Check OS-level mic and speaker permissions.
Next steps
Install on your site
Embed the script on your live site once the test passes.
Troubleshooting
Mic, network, and call-quality issues.
Validate the call experience before embedding anywhere. Test widget opens a hosted preview that runs your widget against the selected environment: same agent, same audio path, same call experience as production. Use it for internal testing, customer demos, or stakeholder sign-off.
Once granted, the browser remembers the permission for that origin until the visitor changes it.
Test widget is currently a Phone widget feature. Chat widgets use the in-editor live preview to validate styling and copy before publishing.
Opening the test widget
- Open your Phone widget in Configure > Web Calling.
- In the right-hand preview panel, click Test widget ↗.
- A new tab opens with a blank page hosting only your widget.
Walking through a call
Click the launcher
The launcher renders in the bottom-right of the test page. Click it to open the widget.
Review the call-start screen
The widget shows your welcome message, the disclaimer (if enabled), and a primary Start call button using your brand color.
Connecting
The widget shows Connecting… while it opens a WebSocket to PolyAI’s WebRTC gateway and negotiates audio.
In call
Your agent answers and the widget switches to In call. A timer starts and the Mute button appears. Speak normally to test the conversation flow.
What to verify
- Branding. Header text, logo, agent name, and primary color match your brand.
- Welcome and CTA copy. Read out loud to check tone.
- Disclaimer placement. Disclaimer appears above Start call, with policy links rendered as inline hyperlinks.
- Audio quality. Speak and listen for latency, dropouts, or distortion. Web Calling uses Opus 48 kHz stereo.
- Mute / unmute. Mute mid-call, confirm the agent can’t hear you, then unmute.
- Call recovery. Let the call end, then click Start new call to confirm clean reconnection.
Microphone permission
The first time a visitor clicks Start call on a given origin, the browser prompts for microphone access. Web Calling handles three outcomes:| Visitor action | Widget behavior |
|---|---|
| Allow | Call connects normally. |
| Block | Widget shows a Mic blocked state with steps to re-enable mic permissions and a Try again button. |
| Dismiss | Widget returns to the call-start screen so the visitor can try again. |
Sharing a preview
The preview URL is shareable. Send it to stakeholders, customers, or your wider team to validate the experience together, no embed required. Best for internal testing, customer demos, early stakeholder review, and fast validation before website deployment.A few things to know about how the link behaves:- The token is valid for 1 hour. Generate a fresh one from the editor when you need to extend a session.
- Anyone with the link can place a call against the configured environment, so use Sandbox or Pre-release for share-outs unless you specifically want stakeholders on production.
- Calls placed via the preview count against your usage just like production calls.
Troubleshooting the test
If the test fails, see Troubleshooting. The most common issues:- Browser blocks microphone. Check the address-bar lock icon and re-allow.
- HTTPS required. The preview is always HTTPS, but if you embed the widget on an
http://site the launcher is disabled. - Stuck on Connecting… Usually a network/firewall issue blocking WebRTC.
- No audio after connect. Check OS-level mic and speaker permissions.
Next steps
Install on your site
Embed the script on your live site once the test passes.
Troubleshooting
Mic, network, and call-quality issues.