Your First 15 Minutes With Hiroi

Most "get started in five minutes" guides are written by someone who already knows where every button is. This one is written the other way round: it is the genuine happy path, in order, with the two or three places people actually get stuck called out where they happen.

Fifteen minutes is realistic if you have a website you can paste a script tag into. Here is roughly where the time goes.

1. Sign in

There are no passwords. The sign-in page offers Microsoft, Google and Apple, a passkey if you have registered one, and a one-time email link. Pick whichever you already use.

Signing in for the first time is the sign-up — there is no separate registration step, and no card is required to start. New accounts arrive with a small starting credit balance so you can talk to your assistant before you decide anything about billing.

One thing worth knowing now: if you later sign in with a different provider using the same verified email address, you land on the same account rather than a duplicate.

2. Create the assistant

Open Assistants in the sidebar and click Create Assistant. On a brand-new account the page shows a short onboarding panel instead, with a Create Your First Assistant button — same dialog either way.

Five fields:

The Domain you type here does double duty: it is saved on the assistant, and it is added to the assistant's allowed-domains list. That is why step 4 is usually already done for you.

If you want a starting draft rather than a blank box, click AI Generate next to Instructions. It becomes available once you have entered a name or a domain, and it writes a short first pass from those. Treat it as a draft, not an answer.

Click Create. Hiroi saves the assistant and drops you into its editor.

3. Write the instructions and set a goal

You land on the General tab. Two fields here matter more than everything else on the page combined.

Instructions, under AI Behavior, is the brief. It holds up to 10,000 characters and a live counter under the box tells you where you are. Be specific about who the assistant is, who it is talking to, and what it should refuse:

You are the front-desk assistant for Bayside Dental, a family practice in Portland. You talk to patients and prospective patients about appointments, opening hours and what to bring to a first visit. Keep answers under 60 words. Do not quote prices, discuss insurance coverage, or give medical advice — for any of those, offer to take a message.

That takes two minutes and it is the difference between an assistant that sounds like your business and one that sounds like a demo. If you want the longer version of this thinking, Assistant Persona and Tone Setup walks through the same field in detail.

Goal, under Outcomes, is the one people skip and regret. It is a plain-English sentence describing what success looks like — "You succeed when the visitor books a consultation or leaves an email address." Setting it does two things: it steers the assistant toward that outcome on every turn, and it switches on resolution grading, which is what fills in the outcome numbers in Analytics.

Grading is not retroactive. Conversations that ended before you wrote a goal are never graded. Thirty seconds now saves you a blind first week.

Click Save, or press ⌘S / Ctrl+S. Save is greyed out until something has changed, and an Unsaved changes marker sits in the header while you have edits outstanding.

4. Allow your domain

Open the Deploy tab.

Leave Authentication Mode on Allowed Websites. In that mode no secret goes into the browser at all — the page sends only your site ID, and the server checks the request's origin against your list.

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

The single most common launch failure lives right here: matching is exact, and there are no wildcards. example.com does not cover www.example.com, and it does not cover shop.example.com. Add every host you actually embed on as its own entry, including your staging site. An entry with a port (localhost:5566) matches that host and port only; an entry without a port matches that host on any port.

5. Copy the embed code and paste it

Still on Deploy, find the Embed Code block and copy it. It looks like this, with your own site ID:

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

Paste it just before the closing </body> tag on every page where you want the assistant, and publish.

The site ID is not a secret — it is safe in version control and safe in view-source. The origin check is what actually protects you. If you are on Squarespace, WordPress, Wix or Shopify, the Platform Guides accordion under the code block tells you exactly which settings screen to paste it into. For a framework app, How to Add an AI Agent to Any Website in 60 Seconds covers the same ground.

You do not need to touch this tag again. Colours, greeting, voice, knowledge — all of it is fetched from Hiroi on each page load, so a save in the dashboard takes effect on the next refresh.

6. Test it

Two ways, and you want both.

Test Widget, on the Deploy tab, opens a Hiroi-hosted page with your assistant already on it. Nothing has to be embedded anywhere for this to work, so it is the fastest way to try a few questions.

Your own page is the real test — it is the one that proves the domain safelist, the script placement and your site's CSS all agree with each other.

Both the preview and the test page load the last saved version. If you changed something and did not save, you will not see it.

Ask five questions you already know the answers to. One easy, one specific, one you expect it to refuse, one phrased badly, and one it has no business answering. Then go back to Instructions and add one line that would have fixed the worst of the five answers.

If nothing appears

Work down this list — it is almost always one of these:

1. The page you loaded genuinely contains the script tag, before </body>.
2. The script's src really points at /static/va-wave-widget.js. The bundle finds itself by looking for its own filename, so a renamed or proxied copy loads and then silently does nothing.
3. The host in your address bar is in Allowed Domains, exactly — including www.
4. The editor header badge reads Live, not Off.
5. The page is served over HTTPS. In production, requests from a plain HTTP origin are rejected.

What to do next

You now have a working assistant that answers from its instructions. The next three things worth your time, in order: upload the documents it should answer from, decide what happens when it cannot help, and read what people actually asked it.

When you are ready to put it in front of real traffic, the Go-Live Checklist is the short version of everything that tends to be missed.

Start at hiroi.ai whenever you have fifteen minutes free.