arizuko

arizuko › howto › Chat link on your site

put a chat link on your site

A chat link is a URL like https://<host>/chat/<token>/. Open it in a browser and you get a small chat page wired up to one folder's agent. No login. Anyone with the URL can talk.

The primitive is the same one webhooks use — see route tokens for the full story. This page covers the operator-side recipe for getting one URL onto one website.

/chat/<token>/ accepts only web: tokens; presenting a hook: webhook token there returns 404. issue_chat_link always returns a /chat/<token>/ URL.

use case

A tenant runs acme.com and wants a “Chat with us” link on the marketing site, against the acme agent. No account creation, no Slack invite — visitors click the link, type, the agent replies in the page.

issue the URL

From the CLI:

arizuko token issue acme chat
# https://acme.fiu.wtf/chat/Yp3v...Q2/

The CLI prints the URL once. Paste it where the “Chat with us” button lives on the website. The token is in the URL — treat the whole URL as a shareable bearer credential.

An agent inside the folder can mint its own:

issue_chat_link()
  → {
    "token": "...",
    "url":   "https://acme.fiu.wtf/chat/.../",
    "jid":   "web:acme"
  }

what the visitor sees

GET /chat/<token>/ serves a minimal HTML chat page baked into webd. The visitor types, the page POSTs to the same URL, the response carries a turn_id, and an SSE stream at /chat/<token>/<turn_id>/sse delivers the agent's reply frames as the turn runs.

Dropped connections reconnect with Last-Event-Id; the server replays missed frames and resumes live. The page works in any modern browser without any account, cookie, or sign-in step.

splitting one folder across pages

Pass a jid_suffix to put two URLs from the same folder on different pages and tell them apart in routing: 

arizuko token issue acme chat --suffix support
  → web:acme/support  (https://.../chat/Sup1.../)

arizuko token issue acme chat --suffix sales
  → web:acme/sales    (https://.../chat/Sal2.../)

Both URLs reach the same acme agent, but the JID prefix lets route rules behave differently — e.g. a different persona, a different topic, or a different scheduled escalation. Suffixes are folder segments, not query params; pick names that read well in the route table.

authenticated chat is a different surface

/chat/<token>/ is the anonymous bearer URL. Signed-in chat (a teammate's private pane against their own folder, OAuth-gated through proxyd) is a separate surface served by webd and not covered here.

revocation

arizuko token revoke web:acme/support

The next visitor lands on a 401. Reissue with the same suffix to get a new URL with the same JID and swap it on the site. There is no in-place rotation — the URL is the credential.

go deeper

Edit this page · updated