Skip to main content
A voice widget lets visitors on your website talk to a voice agent from their browser. You manage widgets with an API key. The two runtime endpoints that a visitor’s browser calls are intentionally unauthenticated so a configured widget can load.

Managing widgets

Widgets belong to a voice agent, so every management call takes the agent’s id as agent_id.
Getting one widget returns an embed object with the snippet to paste into your site.

Images

Upload the agent’s avatar, the widget’s avatar or its launcher image with POST /api/v1/public/files, as multipart form data with a file field. Pass purpose (agent_avatar, widget_avatar or widget_launcher) and agent_id (and widget_id for widget images) as query parameters. Avatar uploads also take a kind form field. The image is applied right away and the updated agent or widget comes back. To remove the launcher image, update the widget with "launcher_media": null.

Security model

  • Treat the widget public ID as public, not as an API secret.
  • Keep API keys out of browser JavaScript.
  • Configure allowed origins before embedding.
  • Never expose private agent configuration or webhook secrets in widget responses.

Runtime endpoints

The runtime call endpoint starts a two-way WebRTC browser call with the widget’s voice agent. For step-by-step setup, the generated embed code, and a custom browser client example, see WebRTC browser calls.

Embed checklist

  1. Select a published voice agent.
  2. Create a widget and configure its origin allowlist.
  3. Get the widget (GET /agent-resources?type=widget&agent_id=...&id=...) and copy its embed snippet.
  4. Test from an allowed origin.
  5. Confirm calls, rate limits, and failures before production rollout.