Skip to main content
A web widget embeds one of your Anyreach agents as a chat-and-voice bubble on your website. End users open the bubble and talk to the agent by text or by voice, in the same widget, without leaving your page. Each widget is a saved record that binds an agent to a published version, scopes it to a set of allowed domains, and carries a configuration object for appearance, branding, quick actions, forms, and feedback.

​
What a widget binds together

A widget record holds these fields:
FieldTypeDefaultDescription
idUUIDgeneratedWidget identifier. Used in the embed snippet and in public endpoints.
organization_idstringfrom tokenThe organization that owns the widget. Set from your auth token at creation.
agent_idUUIDrequiredThe agent the widget serves.
agent_version_idUUIDrequiredThe specific agent version end users talk to. Pin this to a published version.
domainstext[][]Allowed domains the widget may load on.
publishedbooleanfalseWhether the widget is live. Must be true for the widget to serve.
configobject{}Appearance, branding, quick actions, forms, and feedback, versioned under v1.
created_attimestampnowWhen the widget was created.
updated_attimestampnowWhen the widget was last changed.
The config object is namespaced under a v1 key so its shape can evolve without breaking existing embeds. Appearance, text and voice options, quick actions, forms, and feedback all live inside config.v1.

​
Requirements to go live

Two gates must both be satisfied before a widget serves traffic:
1

The agent has a published version

The widget’s agent_version_id should point at a published version of the agent. Publish the agent version you want end users to reach before pointing a widget at it.
2

The widget itself is published

The widget’s own published flag must be true. A widget with published set to false exists but does not go live.
Pinning the widget to a specific agent_version_id means published changes to other versions do not silently alter what end users experience. Update the widget’s version when you want to roll a new version out.

​
How conversations work

End users talk to the agent over LiveKit WebRTC. The same widget handles both text chat and voice on the webrtc channel, so switching between typing and speaking happens inside one session. 
Browser page
   |
   |  loads embed snippet (gated by allowed domains)
   v
Web widget  ──binds──>  agent + published agent version
   |
   |  opens a conversation over LiveKit WebRTC
   v
Agent  <── text and voice in the same session ──>  End user
When an end user opens a conversation, the widget creates it on the webrtc channel and joins a LiveKit room. The widget can resume an existing conversation by id, reconnecting the user to the agent in a fresh room.

​
Allowed domains and security

The domains list is the allowlist of sites the widget may run on. The public embed snippet reads a widget’s allowed domains and enforces them, so a widget cannot be loaded from a site you have not listed. Keep this list tight and add only the origins you control.

​
Next steps

Create a widget

Bind an agent and published version, set allowed domains, and publish.

Install the snippet

Drop the embed snippet onto your site and verify it loads.

Appearance and branding

Theme the bubble, set avatars, and apply your brand.

Text, voice, and quick actions

Tune chat and voice behavior and suggested questions.

Forms and feedback

Collect input mid-conversation and gather post-conversation feedback.

Allowed domains and security

Lock the widget to the domains you control.