Integration Guide

What you can embed

• Text chat — Visitors type questions; answers can use your knowledge base when one is attached to the agent.
• Voice chat — Real-time spoken conversation with the same agent persona.
• Animated avatar — Lip-synced face while the agent speaks (Maya, Lina, Tom, Alan, and other catalog avatars).

Each workspace gets API keys and domain allowlists so the widget only runs on sites you authorize. You choose which interaction modes appear on each agent (see Widget modes below). Plan limits apply to daily chat and voice usage — see Pricing for details.

Before you embed

1. Create a free account and sign in to the tenant portal.
2. Open My Agents → create an agent (prompt, avatar, voice, allowed domains, and widget modes).
3. Open API Keys → create a key and copy it immediately (shown once).
4. On the agent page, add every website hostname where the widget will appear (see Allowed domains below).
5. Optional: attach a Knowledge Base so answers use your uploaded documents.

Signed-in workspace owners and admins can copy a ready-made snippet from any agent's detail page under Embed snippet.

Embed code

Paste one <script> tag on your page. Replace YOUR_AGENT_ID with the agent ID from the portal and YOUR_API_KEY with your API key. The script loads widget styling automatically.

Inline (default)

The widget appears where you place the script — ideal for a dedicated support or chat section.

<script
  src="https://avatar-api.acmplatforms.ai/embed/platform-widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://avatar-api.acmplatforms.ai"
  data-voice-url="https://avatar-voice.acmplatforms.ai"
  async
></script>

Floating bubble

Add data-display="float" for a fixed corner bubble on every page. Use data-position="bottom-left" to move it to the lower-left.

<script
  src="https://avatar-api.acmplatforms.ai/embed/platform-widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://avatar-api.acmplatforms.ai"
  data-voice-url="https://avatar-voice.acmplatforms.ai"
  data-display="float"
  async
></script>

<script
  src="https://avatar-api.acmplatforms.ai/embed/platform-widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://avatar-api.acmplatforms.ai"
  data-voice-url="https://avatar-voice.acmplatforms.ai"
  data-display="float"
  data-position="bottom-left"
  async
></script>

Mount inside a container

Add a <div id="…"> and set data-target to that element's id:

<div id="my-agent-widget"></div>
<script
  src="https://avatar-api.acmplatforms.ai/embed/platform-widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://avatar-api.acmplatforms.ai"
  data-voice-url="https://avatar-voice.acmplatforms.ai"
  data-target="my-agent-widget"
  async
></script>

Script attributes

Widget modes

On the agent create or edit page, use Widget modes to control which tabs visitors see in the embed. All three are enabled by default.

• Text — Typed chat in the widget. Uses your knowledge base when one is linked.
• Voice — Spoken conversation using the visitor's microphone.
• Avatar — Lip-synced face while the agent speaks. Requires Voice to be enabled.

You may disable up to two modes, but at least one must stay on so the widget can function. Common setups:

• Text only — FAQ or support pages where visitors prefer typing (no mic prompt).
• Voice only — Hands-free or phone-style interaction without a text composer.
• Voice + Avatar — Full talking-head experience without a text tab.
• All three — Default; visitors pick the mode that fits them.

Mode settings are saved on the agent and applied automatically when the widget loads — no changes to your embed snippet are required.

Allowed domains

For security, each agent only loads on hostnames you list under Allowed domains on the agent edit page. Add one hostname per line (or comma-separated). Examples:

• www.example.com — exact host only
• *.example.com — any subdomain of example.com

Include every origin visitors use (with or without www). Local testing: add localhost while developing on your machine.

Enhance your agent

Knowledge bases

Upload markdown documents under Knowledge Bases, then link a base to your agent. Text and voice answers can then use your content. Document limits depend on your subscription plan.

URL fetch (Standard & Pro plans)

On eligible plans, enable URL fetch on the agent to let text chat read HTTPS pages from domains you allowlist (separate from widget embed domains). Useful for product docs or help pages you host.

After go-live

• Dashboard — Monitor chat, voice, and knowledge-base usage. Click any metric tile for daily history (last 30 days or by month). In Usage by agent, click Chart on a row for per-agent trends with toggles for each metric.
• API keys — Rotate keys by creating a new key, updating your site, then deleting the old key.

Troubleshooting

• Widget does not appear — Confirm the script URL loads (browser Network tab), the API key is correct, and the page hostname is in allowed domains.
• Voice or avatar unavailable — Confirm the mode is enabled under Widget modes on the agent; check daily voice limits on your plan; ensure the agent status is Active.
• A tab is missing in the widget — That mode was disabled for the agent. Edit the agent and re-enable Text, Voice, or Avatar as needed (at least one must remain on).
• CORS or blocked requests — Usually means the site hostname is missing from allowed domains.

Visitor privacy

When you embed the widget, your site visitors interact with an agent you configure. You are responsible for your privacy notice and consent. Shared cloud plans do not include long-term conversation storage or configurable retention; Self-Hosted and Managed Dedicated Hosting do — see Pricing and our Privacy Policy.

Questions? Contact support@acmplatforms.com.