FAQs

Short answers to the questions we get most often. Each one links to the page that covers the topic in full.

Getting started

Do I need a subscription?

No. There are no plans to choose between. Every account starts free, and buying credits is what unlocks the paid features.

A new account starts with a credit balance (50 credits by default) so you can test text and voice chat before spending anything. Free accounts get 1 assistant, no knowledge base, and are pinned to the Azure text-to-speech provider.

The moment you buy credits, your account becomes paid — permanently. Spending the balance back down to zero does not take the features away.

What is the difference between free and paid?

Full numbers are in Limits and quotas.

How do I tell whether the assistant is actually doing its job?

Set a Goal on the assistant's General tab — a plain-English description of what success looks like, for example "You succeed when the customer books a demo or shares their email."

Once a goal is set, every conversation is graded against it when it ends, and Analytics → Quality shows the Resolution rate. Until then nothing is graded, so the Resolution card shows Turn on resolution grading instead of a number. That is the only reason Resolution appears unmeasured — it is not a bug and it is not a data delay.

See Analytics.

Billing and credits

What spends credits?

Credits are consumed by the work the assistant does: each chat turn the AI answers, speech-to-text on voice input, and text-to-speech on spoken replies. Text-only conversations are the cheapest; voice costs more because it adds transcription and speech synthesis on top of the same AI turn.

See Billing and credits.

What happens when my credits run out?

The assistant stops answering. Visitors see a message that the assistant is unavailable, the session ends, and further attempts are refused until the balance is topped up — the widget shows "No credits remaining. Please contact the site owner." Your settings, conversations and documents are untouched, and the assistant starts answering again once credits are added.

How do I avoid running out?

Turn on Auto top-up on the Billing page. Choose a balance threshold, an amount to buy, and a saved card; when the balance falls below the threshold, Hiroi charges the card and adds the credits automatically.

If I buy credits once, do I keep the paid features?

Yes. Paid status is based on having ever purchased credits and does not expire. If your balance runs to zero, the assistant stops answering until you top up, but the feature unlocks stay.

The widget

Why is my widget not appearing?

Work through these in order — one of them is nearly always the cause.

1. The script URL is wrong. The loader finds itself by looking for a script tag whose src contains va-wave-widget. Any other path loads nothing and fails silently. The embed must be:

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

2. No data-site-id or data-session-token. One of the two is required.

3. The page's domain is not on the safelist. Add the exact host to Allowed Domains on the Deploy tab.
4. The assistant is disabled. Check Assistant Status on the General tab — it must read Active.
5. The page is served over HTTP. In production, requests from a non-HTTPS origin are rejected (localhost and private network addresses are exempt).

To see the widget's own diagnostics, set window.__VA_DEBUG = true before the embed script — its log lines are suppressed otherwise. Rejected requests also show in the browser's Network tab as a 401 on the calls to /api/widget/..., with the reason in the response body ("Origin not in allowed domains", "Site has no allowed domains configured", "Widget site is disabled").

Does adding example.com cover www.example.com and subdomains?

No. Domain matching is an exact host match with no wildcards. List every host the widget loads on, including www. and each subdomain, as separate entries.

An entry with a port (localhost:5566) must match host and port exactly. An entry without a port matches that host on any port.

Is there a REST API I can call?

No. Hiroi has no public REST API today. Every dashboard endpoint requires a logged-in browser session, and writes additionally require a CSRF token that only the dashboard can read — an external script cannot obtain either.

Two surfaces are callable from your own code:

• POST /api/widget/session/create, a server-to-server call that mints a widget session token for Session Signed authentication. See Widget authentication.
• Actions — Hiroi makes a signed HTTPS request to your endpoint when an event fires, when the AI decides to call your tool, or when a visitor submits a form. The traffic goes outbound from Hiroi to you, not the other way round.

There is no API keys tab in Settings. It was withdrawn because the keys it issued authenticated no endpoint.

Do I need to re-paste the embed code after changing settings?

No. The script tag carries only the site ID (or session token) and optional overrides. Everything else — name, colours, greeting, voice, knowledge — is fetched from Hiroi each time the widget loads, so a save in the dashboard takes effect on the next page load.

Can I remove the "Powered by" line?

Yes, on a paid account. Turn on Hide Branding under Powered By on the Appearance tab.

Voice

Do I need any telephony set up for voice chat?

No. Voice in the widget runs in the visitor's browser over their microphone — the audio never touches a phone line, so there is nothing to provision and nothing to register.

Why is there no voice option in my widget?

Check Enable Voice Input on the Voice tab — it controls whether visitors can speak instead of typing. If you also want the assistant to speak its replies, turn on Enable Text-to-Speech in the same tab; the two are separate switches.

If the option is there but nothing happens when a visitor taps it, the browser has almost certainly denied microphone permission for your site, or the page is not served over HTTPS.

Which voices can I use?

Azure Neural voices are available on every account and are the default. Paid accounts can also select ElevenLabs where it is enabled; free accounts are pinned to Azure. Preview any voice from the Voice tab before saving.

Knowledge base

What files can I upload?

PDF, DOCX, TXT, MD and HTML, up to 10 MB each. Uploads are checked against their actual content, not just the file extension, so a renamed file is rejected.

How many documents can I add?

The knowledge base is a paid feature — add credits to your account to unlock it. Each assistant can then hold 20 documents (a beta limit). See Knowledge and capabilities.

Privacy and data

Is my conversation data used to train AI models?

No. Hiroi does not train AI models on your contact data or conversation content, does not sell personal information, and does not use it for advertising profiles.

Conversation content is sent to the AI providers that generate the responses (OpenAI, Anthropic) and to Microsoft Azure, which hosts the platform and provides speech, content safety and telephony. The full list is in the Privacy Policy.

How long is my data kept?

Chat conversation data is kept for 1 year by default. You can change the window under Settings → Privacy → Data retention; anything older than the period you choose is deleted automatically. IP addresses are anonymised after 90 days.

Can I export or delete my data?

Yes. Settings → Privacy → Data export downloads a copy of your data straight to your browser (GDPR Article 20); no copy is kept on our servers. Delete account is on the Settings → Account tab.

Exporting conversations and analytics as CSV or JSON from the Analytics page is a paid feature.