Widget reference

Script attributes

The embed script reads four data-* attributes:

Attribute	Required	Description
`data-site-id`	Yes	Your site ID from the dashboard. Identifies your site (not a secret).
`data-api`	No	Advanced: override the API base URL. Defaults to `https://app.yamidoo.ai` unless the script is served from `yamidoo.ai`, a `*.yamidoo.ai` subdomain, or `localhost`, in which case it uses that origin.
`data-mount`	No	A CSS selector. Renders the chat inline inside that element instead of as a floating bubble.
`data-inline`	No	`"true"` for inline mode without a selector — this is what the `/embed` iframe uses.
`data-placement`	No	A label for this install (≤40 chars), e.g. `contact`. Saved on each new conversation and shown in Analytics → Where chats start. For the iframe, use `/embed/YOUR_SITE_ID?placement=contact`.

<script
  src="https://app.yamidoo.ai/widget.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

If a page optimizer strips data-* attributes from scripts, set window.yamidooSiteId before the script tag instead — the widget falls back to it. (The WordPress plugin sets both.)

<script>window.yamidooSiteId = 'YOUR_SITE_ID';</script>
<script async src="https://app.yamidoo.ai/widget.js" data-site-id="YOUR_SITE_ID"></script>

Appearance and behavior are not set via attributes — they’re configured in the dashboard (see below).

Dashboard configuration

These options are set in the dashboard and fetched by the widget at runtime:

Option	Values / default
Color	Any hex color. Default `#000000`.
Title	Panel header text. Default “Ask us anything”.
Welcome message	First message shown when the widget opens. Default “Hi! I’m here to help. Ask me anything about this site.”
Position	`bottom-right` (default) or `bottom-left`.
Avatar	Optional image URL, shown in the header and beside human replies.
AI avatar	Glyph for the assistant: `orb` (default), `sparkle`, `bot`, or `twinkle`.
Launcher icon	One of 13 icons. Default Outline. See Customizing the widget.
Launcher label	Text next to the launcher, ≤30 chars (`launcherLabel`), shown when `launcherShowLabel` is on.
Suggested questions	List of strings, shown in list order; 3 per visit, a random selection rotating when there are more.
Floating messages	Off by default. Up to 5 messages, ≤200 chars each; delay 3 s; frequency once per visit / every page / only once; show on mobile (on); only while an agent is online (off); when clicked: send as a question (default) or put in the message box.
Contact capture	Ask name / email, and the timing of the prompt.
Satisfaction ratings	Per-answer thumbs rating. Off by default.
Conversation rating	`none` (default), `stars` (5 stars), or `emojis` (5 emojis).
Rating asked	`agent` (default): after an agent closes the chat. `all`: after every chat ends, including AI-only chats.
“Did that answer your question?”	On by default. Shown once per chat after 2 minutes of quiet following an AI answer; Yes, thanks ends the chat.
Close idle chats after	Default 30 minutes without a message; 0 = never. Chats waiting for a team reply are skipped.
Human handoff	On by default.
Require agent online	Off by default.
AI handoff	On by default — the assistant can escalate on its own.
Email transcript	On by default — visitors can email themselves the chat.
Hide “Powered by Yamidoo”	Pro plan.
Attachments	Visitor file uploads. Paid plans.
Idle minutes	Default 10. Only affects how the Live monitor labels visitors.

Visitor-side features

Things visitors get in the chat without any configuration on your side:

Recent chats — past conversations that had a human reply can be reopened from the chat menu.
End chat — asks “Do you want to end this chat?”, then closes the conversation (and shows the rating when it’s set to ask after every chat).
Ended chats — once a chat ends (the visitor ended it, an agent closed it, or it closed for inactivity) the message box is replaced by “Your chat has ended” and a Start a new chat button. The transcript stays readable.
Send transcript — emails the conversation to the visitor (asks for an address if none is on file). Controlled by the Email transcript option.
File uploads — on paid plans; up to 10 MB per file, 20 files per hour.
Typing indicator — visitors see when an agent is writing.

JavaScript API

The widget registers a global yamidoo() function. Call it with a command name and optional arguments:

yamidoo('open');
yamidoo('ask', 'Do you offer refunds?');
yamidoo('identify', { name: 'Jane Doe', email: 'jane@example.com' });

Command	Description
`yamidoo('open')`	Open the chat window.
`yamidoo('close')`	Close the chat window.
`yamidoo('toggle')`	Toggle open/closed.
`yamidoo('show')`	Show the launcher bubble.
`yamidoo('hide')`	Hide the widget entirely.
`yamidoo('hideLauncher')`	Hide only the launcher bubble. The chat still opens from `open`, `ask`, HTML triggers and floating messages, and closing it leaves the bubble hidden — for pages that open the chat from a button of their own.
`yamidoo('showLauncher')`	Bring the launcher bubble back.
`yamidoo('reset')`	Clear the conversation and show the welcome message again. Keeps the visitor session and any captured contact.
`yamidoo('logout')`	Like `reset`, but also rotates the session and forgets the contact details.
`yamidoo('ask', question)`	Open the widget and send `question`.
`yamidoo('prefill', text)`	Open the widget with `text` in the message box, not sent, cursor at the end, so the visitor can finish the question.
`yamidoo('identify', traits)`	Attach `{ name, email, avatarUrl, signature, ...metadata }` to the user. `avatarUrl` is shown in the inbox; `signature` proves the login for customer data.
`yamidoo('on', event, cb)`	Subscribe to an event.
`yamidoo('once', event, cb)`	Subscribe for a single event.
`yamidoo('off', event, cb?)`	Unsubscribe (omit `cb` to remove all).

Events

Subscribe with yamidoo('on', event, callback). The callback receives one argument with the payload shown (or nothing).

Event	Fires when…	Payload
`open`	The widget opens.	—
`close`	The widget closes.	—
`message`	A message is sent or received.	`{ role: 'visitor' \| 'ai' \| 'agent', content }`
`handoff`	The visitor asks for a human, or the AI escalates one.	`{ source: 'ai' }` when the AI initiated it; otherwise —
`conversation_rating`	The visitor rates a conversation after it ends.	`{ rating: 1–5 }`

yamidoo('on', 'handoff', (e) => {
  analytics.track('chat_handoff', { source: e?.source ?? 'visitor' });
});

widget.js loads asynchronously, so a call made early — say, identify() in your page’s <head> — would hit an undefined yamidoo. Add this queue stub before the script tag; calls are buffered and replayed as soon as the widget mounts:

<script>
  window.yamidoo = window.yamidoo || function () {
    (window.yamidoo.q = window.yamidoo.q || []).push(arguments);
  };
</script>
<script async src="https://app.yamidoo.ai/widget.js" data-site-id="YOUR_SITE_ID"></script>
<script>
  yamidoo('identify', { name: 'Jane Doe', email: 'jane@example.com' });
</script>

Every command works through the stub, including on/once subscriptions.

Once mounted, the widget adds two classes to <html>: yamidoo-ready, and yamidoo-api-N for the command set it understands (yamidoo-api-2 is the first with hideLauncher). Use them to show controls only when the chat is present, or to pick a command that older builds lack:

if (document.documentElement.classList.contains('yamidoo-api-2')) {
  yamidoo('hideLauncher');
} else {
  yamidoo('hide');
}

widget.js loads asynchronously, so make that check once it has booted — a MutationObserver on the class attribute of <html> works — rather than at page load, when neither class is there yet.

HTML triggers

Any element with a data-yamidoo attribute drives the widget on click — no JavaScript required:

<button data-yamidoo="open">Chat with us</button>

Supported values: open, close, toggle.