Managing widgets
Widgets belong to a voice agent, so every management call takes the agent’s id asagent_id.
embed object with the snippet to paste into your site.
Images
Upload the agent’s avatar, the widget’s avatar or its launcher image withPOST /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
Embed checklist
- Select a published voice agent.
- Create a widget and configure its origin allowlist.
- Get the widget (
GET /agent-resources?type=widget&agent_id=...&id=...) and copy itsembedsnippet. - Test from an allowed origin.
- Confirm calls, rate limits, and failures before production rollout.