Web widget

The Hyponema widget is a self-contained browser bundle. Your backend creates a session, then the page passes the signed session URL to the widget.

Backend flow

Create the session from your server so the workspace API key never reaches the browser.

curl -X POST "https://api.hyponema.ai/sessions" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "user_id": "user_123",
    "modality": "voice+text"
  }'

Return the ws_url or chat_url to your frontend.

Browser embed

<hyponema-widget
  data-ws-url="wss://api.hyponema.ai/v1/sessions/SESSION_ID/ws?token=TOKEN"
  data-mode="voice+text"
  data-position="bottom-right"
  data-button-label="Talk to us"
  data-primary-color="#0369a1"
></hyponema-widget>
<script src="https://cdn.hyponema.ai/widget.js" async></script>

Common attributes

Attribute	Description
data-ws-url	Voice WebSocket URL returned by POST /sessions.
data-chat-url	Chat WebSocket URL returned by POST /sessions.
data-mode	voice-only, voice+text, or text-only. The widget exposes the -only suffixes; the underlying session API takes voice, voice+text, or text (drop the suffix when calling POST /sessions).
data-position	bottom-right, bottom-left, top-right, or top-left.
data-button-label	Floating button label.
data-opening-prompt	Greeting line shown before the session starts.
data-primary-color	Brand color for widget controls.
data-transcript-enabled	Whether to show the transcript panel.
data-mute-enabled	Whether to show the mute toggle in voice mode.
data-dismiss-enabled	Whether to show the close control.

Production checklist

• Create signed session URLs on your backend.
• Use stable user IDs.
• Add your site origin to the agent allowlist when origin checks are enabled.
• Test microphone permissions in Safari, Chrome, and mobile browsers.
• Review traces for the first beta sessions.