Documentation

Quickstart

This is the shortest path from an empty account to a working assistant on a real website. It takes one form, one paragraph of instructions, and one line of code.

1. Create the assistant

Open Assistants in the sidebar and click Create Assistant. On a new account the page shows a welcome panel instead — click Create Your First Assistant.

Fill in the modal:

Field What to enter
Name Required. What you call this assistant internally, for example My Website Chat.
Domain Required. The site you will embed on, without http:// — for example example.com.
Welcome message The first line the assistant shows a visitor. Optional.
Instructions How the assistant should behave. Optional — leave it blank for a friendly default.
Enabled Leave on. Off means visitors cannot use the assistant.

If you would rather start from a draft, click AI Generate next to Instructions. It writes a starting set of instructions from the name and domain you entered, and becomes available once one of those two fields has a value.

Click Create. Hiroi saves the assistant and opens its editor. The domain you typed is added to the assistant's allowed-domains list automatically, so step 3 is usually already done for you.

2. Write the instructions

The editor opens on the General tab. The Instructions box under AI Behavior is what defines the assistant's behaviour — tone, style, and the topics it should stay on. It holds up to 10,000 characters, and the counter under the box shows how much you have used.

Be specific. "You are the support assistant for Example Co, a bookkeeping service for small builders. Answer questions about pricing and onboarding. If someone asks about payroll, say we do not handle it and offer to take their email." works better than "be helpful".

The AI button in the section header opens a panel where you describe the assistant in one line and Hiroi drafts the instructions for you.

Click Save (or press Ctrl-S / ⌘S). Save is greyed out until you have unsaved changes, and an Unsaved changes marker appears in the header while you have them.

3. Allow your domain

Open the Deploy tab.

The Deploy tab showing Authentication Mode, the Allowed Domains list and the embed script tag

Under Authentication Mode, leave Allowed Websites selected. In that mode the widget carries no secret: the browser sends only your site ID, and Hiroi checks the request's origin against the domains you list.

Check the Allowed Domains list. The domain from step 1 should already be there. To add another, type it in the box and click Add Domain.

Warning

Matching is exact. example.com and www.example.com are different entries — add both if you serve both. For local testing, add the host and port you actually browse, such as localhost:5566.

4. Copy the embed code

Still on Deploy, find Embed Code → Script Tag (Site ID only — no secrets) and use the copy button on the code block. The snippet looks like this, with your own site ID filled in:

<script src="https://hiroi.ai/static/va-wave-widget.js"
    data-site-id="YOUR_SITE_ID"></script>

Paste it into your site's HTML just before the closing </body> tag, on every page where you want the assistant to appear.

The Deploy tab also carries step-by-step guides for Squarespace, WordPress, Wix and Shopify under Platform Guides — expand the one you use.

5. Test it

Two ways to check your work:

  • Test Widget on the Deploy tab opens a Hiroi-hosted page with your assistant on it, so you can talk to it before touching your own site.
  • Load your own page and look for the assistant in the corner. Open it and ask something you know the answer to.

The assistant's chat window open on a page, showing a greeting and the message box

Note

Preview and Test Widget both open the last saved version of the assistant. If you changed something and did not save, you will not see it there — click Save first.

If nothing appears on your own page, check these first:

  • The page you loaded actually contains the script tag, before </body>.
  • The domain in your browser's address bar is in Allowed Domains, exactly, including www and any port.
  • The header badge on the editor says Live, not Off.

Next steps