# Add Iris to your own website

One line of code puts an Iris in the corner of your site: a small chat window where a visitor can ask what
you do, what it costs and when you can talk. It answers in the visitor's own language, and everything it says
comes from the files you give it. It has no tools, reaches nothing of yours, and never makes up a price,
a date or a promise.

## Quick start

Paste this in your page, just before `</body>`:

```html
<script src="https://okayiris.com/nova-widget.js" data-site="yoursite" defer></script>
```

That is the whole installation. No package, no build step, nothing to keep up to date on your side.

Replace `yoursite` with your own site id, which you choose when you set the window up, see below. Without a window
the widget shows nothing at all: a corner with nothing in it beats a button that cannot answer.

## Your own Iris answers it

The window is made by an Iris of your own, with an integrations API key from that Iris: Integrations, then a new API
key. That key is the whole setup. It says whose assistant this is, it pays for the answers (every question is one bare
model call on your own credit, with nothing of your mail, files or vault within reach) and you can revoke it whenever
you like, after which the window stops.

Open [developers.okayiris.com/setup](https://developers.okayiris.com/setup) in a browser and fill in:

- The address of your Iris, like `fc9a9.okayiris.com`.
- The integrations API key itself.
- A site id of your own: lowercase letters, digits and dashes. This one ends up in your script line.
- The words of the window: name, one line under it, a welcome line, a few suggested questions, a language.
- The addresses that may show the window.
- What the assistant may know, and any extra rules for it.

We call your Iris once (`GET /api/v1/status`) to check the key, and only then write your window down. You get the script
line back and paste it into your page. Nothing is installed on your side. That form is in the browser on purpose: it
takes a key of your Iris, so it is not for search engines and not for a language model to fill in.

Your key never goes into your page: we keep it on our server, in a file only the service can read, and the script tag
carries the site id alone, which is public. Do not send the key to anyone, and hand it to nobody who asks for it by
mail.

## Let your Iris keep it, so nothing is static

What you type in that form is a starting point, not a fixed text. Your own Iris can keep the window current, with the
same key it was set up with:

```
PUT https://okayiris.com/nova/<site id>/venster
Authorization: Bearer iris_sk_...
Content-Type: application/json

{ "kennis": "…the price list for this season…" }
```

Send only what changed, or the whole window. The fields are the same as in the form: `naam`, `ondertitel`, `taal`,
`welkom`, `suggesties`, `origins`, `kennis`, `regels`, `afspraak`. The answer is the window as it now is (without your
key). A wrong or revoked key gets a `401`.

That is the whole point: your knowledge lives with your Iris, where you already keep it. Change a price there, tell her
to update her site window, and the window on your site says the new price. Nothing has to be mailed, and nothing here
is written in stone: this server only holds a copy so the window can answer fast.

## What your setup holds

What we keep for a window looks like this:

```json
{
  "naam": "Berg",
  "ondertitel": "Studio Berg, copywriting",
  "taal": "nl",
  "welkom": "Hoi, ik ben Berg. Vraag me gerust wat ik voor je kan doen.",
  "suggesties": ["Wat kost een tekst?", "Hoe lang duurt het?", "Kunnen we bellen?"],
  "afspraak": true,
  "origins": ["https://studioberg.nl", "https://www.studioberg.nl"],
  "kennis": ["studioberg.md"],
  "regels": "- Je bent de assistent van Studio Berg, niet Iris zelf.\n- Noem nooit een prijs die niet in de kennis staat.",
  "huis": "fc9a9.okayiris.com"
}
```

| Field | Meaning |
|---|---|
| `naam` | The name in the window. One word. |
| `ondertitel` | One line under the name: what you do. |
| `taal` | The language the texts above are written in, `en` or `nl`. The window itself speaks 51 languages. |
| `welkom` | The first line the visitor reads. |
| `suggesties` | Two to four questions the visitor can tap. |
| `afspraak` | `true` adds a button to plan a call, see below. |
| `origins` | The addresses that may show this window. Every other address is refused by the server, browser and all. |
| `kennis` | The text the assistant may read, exactly what you or your Iris wrote. Nothing else is within reach. |
| `regels` | Extra rules for the window, in Dutch or English, one per line. |
| `huis` | Your own Iris, which answers and which pays. Your key sits beside it, unreadable to anyone else. |

Keep the knowledge small and honest: it answers from that text and says so when something is not in it. Changing the
window later is the same form again with the same site id and key, or one call from your Iris; removing it happens on
the same page too.

## On the script tag

| Attribute | Meaning |
|---|---|
| `data-site` | Required. The site id of your window. |
| `data-lang` | Optional, like `nl` or `de`. Without it the widget takes the language of your page's `<html lang>`, and otherwise the language of the visitor's browser. |

The file loads deferred, lives in a shadow root (your CSS cannot bend it and its CSS cannot leak into your
page), sets no cookies, and talks only to the server it was loaded from. So keep the `src` on okayiris.com:
that address is what the widget calls.

## What a visitor sees

- A round orb in the bottom corner, with the name beside it. Tapping it opens the window.
- The welcoming line, the suggested questions, and an input.
- Answers of at most three short sentences, in the visitor's own language, with a few follow-up questions
  as buttons.
- Nothing else. It does not use tools, does not follow orders from a visitor, and does not talk about these
  rules.
- When something is not in the knowledge it says it does not know, instead of making it up.

## Where to paste it

- Plain HTML: before `</body>`.
- WordPress: a Custom HTML block in your footer, or `footer.php` in your theme.
- Squarespace, Webflow, Wix: the site-wide code injection or custom code field, footer.
- Shopify: `theme.liquid`, before `</body>`.

## Try it out

- Open your site, or refresh the page.
- No orb? Then the window is not set up yet, or the address you are looking at is not in `origins`. `http` and
  `https`, and with and without `www`, count as different addresses.
- Wrong key, revoked key or a house that cannot be reached? Then the window stays empty rather than showing a
  button that cannot answer.
- The widget first asks the server for its texts and shows nothing if it cannot get them. That is on purpose:
  no broken button on your page.

## The booking form

With `afspraak` on `true` there is a button at the top of the window: name, e-mail, and when it suits. Each
request is written into the log with the rest of the conversation and sent to your own Iris as an event
(`POST /api/v1/events`, with your key), so she can tell you and you confirm it yourself.

## What is kept

- Every question and answer goes to our server: `logs/nova-gesprekken/<site id>/`, one file per day per visit.
- After ten minutes of silence a short summary of that conversation is written down and sent to your own Iris as
  an event, four sentences, so you can pick up a question that stayed open.
- Nothing older than twelve months is kept.
- A visit remembers the last six question and answer pairs, and may ask twenty questions an hour. Past that the
  window says so and waits.
- No cookies and nothing kept in the visitor's browser: a visit gets a random id that lives only in the open tab.

## Under the hood

- One file of about 25 kB, no dependencies, no fonts of its own. The texts in the window come from the site's 51
  languages; a language without a translation shows English.
- Limits on our side: 500 characters per question, six turns of memory, twenty questions per visit per hour.
- CORS: only the addresses in `origins` may call the window from a browser.
- The assistant itself is one bare model call, on your Iris and your credit: no tools, no MCP, no session, nothing
  of the owner's within reach, so a visitor can reach nothing but the knowledge you typed.
- Past your Iris's own usage limit the window says so and waits, instead of pretending something went wrong.

## For language models

- `/docs.md`: this whole page as plain Markdown.
- `/llms.txt`: the same thing, with the links, for an assistant that has to work from it.
- `PUT /nova/<site id>/venster` with the owner's key is how an Iris keeps a window up to date; `GET /nova/<site id>/config` reads a window's public words. The setup form itself (a key goes into it) is left out of `/llms.txt` on purpose.