> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget

> Prepare widget appearance, access, and browser acceptance checks before installing a supported production embed.

A widget gives visitors an agent interface inside your website. You can review its saved configuration now; a production installation also needs a released embed asset and a working conversation runtime.

<Note>
  A supported production script URL and end-to-end widget session are not established by the current release. The dashboard preview is not an installation contract. Do not copy a development script or expose a workspace API key in page code.
</Note>

## Prepare the configuration

<Steps>
  <Step title="Choose the agent and audience">
    Record the workspace, agent, intended branch, and pages where the interface should appear. Review [authentication](/agents-platform/configure/authentication/overview), including public access and allowed origins, before planning an anonymous visitor experience.
  </Step>

  <Step title="Review the saved appearance">
    Inspect `platform_settings.widget` in the saved agent configuration. It includes placement, colors, avatar, labels, transcript visibility, and feedback options. Check text contrast and use labels that describe the action clearly.

    A saved option describes the desired interface. Verify that the released widget implements it before relying on it in your site.
  </Step>

  <Step title="Choose an installation location">
    Reserve space for the expanded interface and a fallback contact link. On sites with client-side navigation, plan one widget instance and cleanup when its owner unmounts. For builders, use the [no-code guides](/agents-platform/guides/no-code/overview).
  </Step>
</Steps>

The separate [Get agent widget configuration](/api-reference/agents-platform/get-agent-widget-configuration) route requires a valid, unexpired `conversation_signature`; a workspace API key alone does not authorize that read. Signature issuance remains tied to the gated session path, so this route is not a general configuration-read shortcut.

## Before a public launch

| Check | Evidence to collect |
| - | - |
| Release | Authoritative asset URL, version, installation instructions, and supported browsers. |
| Session access | Successful authorized start, expiry handling, and rejection of access outside the intended scope. |
| Visitor controls | Keyboard access, visible focus, readable errors, and a clear end action. |
| Audio | Permission denial, absent microphone, interruption, and resource cleanup on end. |
| Navigation | No duplicate widget, lingering audio, or stale session after changing pages. |

Browser microphone access requires a secure context and user permission. Embedded contexts also need the correct permission policy; a rendered iframe alone does not prove microphone access. See [the browser microphone reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why does the widget endpoint return 401 with an API key?" id="widget-faq-config">The route requires a valid conversation\_signature. An API key does not replace that signature, and the read does not return a production embed script.</Accordion>
  <Accordion title="Can I enable text mode to bypass the runtime requirement?" id="widget-faq-text">No. A text interface still needs a supported session and message transport. A saved text-mode setting does not create that transport.</Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.