Developer overview
Hiroi is configured in the dashboard, not through an API. This section covers the parts you write code for: putting the widget on your site, authenticating it, driving it from your own page, and receiving signed requests on your own server.
There is no public REST API
Hiroi has no general-purpose public REST API today. Every dashboard endpoint — assistants, conversations, analytics, contacts, billing — requires a signed-in browser session, and every write additionally requires a CSRF token that is issued to the dashboard page itself. Code running outside a logged-in browser cannot obtain either, so those endpoints are not usable as an integration surface. Do not build against them.
Exactly two surfaces are meant to be called from your code:
| Surface | Direction | Authentication |
|---|---|---|
| Widget session tokens | Your backend calls Hiroi | X-Server-Key: ss_… header |
| Actions | Hiroi calls your endpoint | HMAC signature that you verify |
Everything else — creating assistants, editing prompts, uploading knowledge, reading transcripts — happens in the dashboard.
Widget session tokens
Only needed if your widget uses Session Signed authentication. Your backend sends a request to
Hiroi with the X-Server-Key header, using the server secret you generate on the assistant's
Deploy tab (it starts with ss_). Hiroi returns a short-lived token — 15 minutes by default,
60 minutes maximum — which you render into the embed snippet as data-session-token. The server
secret stays on your server and is never sent to the browser.
Session Signed is a paid feature. Add credits to your account to unlock it. Full request and response details are in Widget authentication.
Actions
An Action is an outbound HTTPS request that Hiroi signs and sends to a URL you own. There are three
triggers: a platform event such as a conversation ending, the assistant deciding to call your
endpoint mid-conversation, and a visitor submitting a form panel in the widget. Every request
carries an X-Hiroi-Signature header containing an HMAC-SHA256 signature you verify with the
action's secret.
This is how data leaves Hiroi in real time. You never poll Hiroi for it. See Actions.
There are no account API keys
Settings used to carry an API Keys tab. It has been withdrawn: the keys it minted authenticated no endpoint, so building against one was never possible. Any key created while it was visible is inert.
The two credentials that do work are the ones above — the ss_ server secret for widget session
tokens, and the per-Action signing secret. Both are issued where they are used, not in Settings.
The developer pages
| Page | What it covers | Who needs it |
|---|---|---|
| Embedding the widget | The script tag, where to put it, and the two widget presentations | Anyone adding Hiroi to a website |
| Widget authentication | Domain Safelist vs Session Signed, allowed domains, and minting session tokens from your backend | Everyone deploying a widget; Session Signed if visitors are already signed in to your app |
| JavaScript API | The window.VAWaveWidget object your page can call to control the widget and push page context to it |
Front-end developers who want the widget to react to what the visitor is doing |
| Page tools | Registering functions on your page that the assistant is allowed to call | Teams that want the assistant to act on the page, not just answer questions |
| Theming and custom CSS | Matching the widget to your brand beyond the Appearance tab | Front-end developers |
| Actions | Signed outbound requests, the event catalog, delivery logs, and signature verification code | Backend developers receiving Hiroi data |
If you are setting up a widget rather than writing code against it, start with Deploying your assistant in the main guide.