Skip to content
Hyponema Hyponema Docs

Web widget

Use the Web widget flow when you want Users to talk to an agent from a website. Configure it from the agent Distribute tab, then open Web widget.

The hosted widget script is still rolling out. If the dashboard snippet shows the “coming soon” notice instead of a script tag, use the API channel for production traffic or contact support before embedding the widget.

Section titled “Recommended flow”
  1. Configure and test the agent.
  2. Open Distribute on that agent.
  3. Select Web widget.
  4. Copy the current dashboard snippet and configuration values.
  5. Generate the session id, session token, WebRTC URL, WebRTC ICE servers, and messages URL from your backend, not from browser code.
  6. Verify the widget on a staging page before production.

Security boundary

Section titled “Security boundary”

The browser should never receive a workspace API key. Your backend should own any call that creates a session or exchanges privileged credentials. The widget should receive only the browser-safe session id, short-lived session token, token-free WebRTC signaling URL, WebRTC ICE servers from session creation, and token-free HTTP/SSE messages URL.

What to configure

Section titled “What to configure”

Use the dashboard to select the agent, mode, allowed origins, and any channel-specific behavior. Do not reuse screenshots or snippets from old docs; copy fresh values from the current Web widget tab. Voice mode uses WebRTC signaling with the webrtc_ice_servers returned by session creation; text mode sends HTTP/SSE message turns with the session token header. Allowed origins are enforced by the browser session endpoints and do not require adding customer domains to global API CORS configuration.

Text-only widget messages count toward text chat messages. Widget audio counts toward voice minutes. Dashboard previews and test runs use separate fair-use limits, so staging the agent in the dashboard does not spend production text or voice allowances.

Troubleshooting

Section titled “Troubleshooting”
  • If the widget cannot start, check that the agent has been configured and distributed through the correct workspace.
  • If voice fails, check provider credentials and browser microphone permissions.
  • If an origin is rejected, verify the dashboard allowlist and the exact site origin.
  • If the widget loads but has no useful answer, revisit the agent prompt, knowledge attachments, and tests.