arizuko › howto › Chat link on your site

chat link

A chat link is a URL of the form https://<host>/chat/<token>/. In a browser, it opens a small chat page that talks to the agent of one folder. No login exists: anyone with the URL can talk to the agent.

Webhooks use the same mechanism. Route tokens explains it. The steps below put one URL on one website.

Every chat URL accepts any valid route token. The JID kind is information for the agent and does not limit the URL. issue_chat_link always returns a /chat/<token>/ URL.

A website gets a chat button without accounts

A tenant runs acme.com and wants a "Chat with us" link on the website that talks to the acme agent. The visitor needs no account and no Slack invite. The visitor clicks the link and types, and the agent replies in the page.

The CLI or the agent makes the token

From the CLI, on the instance demo:

arizuko token -i demo issue chat acme
# jid:   web:acme
# token: Yp3v...Q2

The CLI shows the token only once. The URL is https://<host>/chat/<token>/. Put it behind the "Chat with us" button on the website. The token is in the URL, so the whole URL is a bearer credential that anyone can use.

An agent in the folder can make its own link:

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

A link can carry instructions for the agent

Both ways take an optional context. The context tells the agent how to process the messages that come through this link:

issue_chat_link(context="bug reports from the acme site; triage and file, don't chat back")

arizuko token -i demo issue chat acme --context "bug reports; triage, don't chat"

Each message that comes through the link brings the text into the prompt as a <link-context> block. The agent reads the block as the rule for the link, not as a message to answer. Two links to the same folder can carry two different rules. The context is fixed when you make the link. To change it, make a new link and revoke the old one.

The visitor sees a chat page with live replies

GET /chat/<token>/ returns a small HTML chat page that webd contains. The visitor types, and the page posts the text to the same URL. The page opens an SSE stream at /chat/stream for the current topic and displays replies as they arrive.

After a lost connection, the page reconnects to the topic stream. The page works without an account, a cookie or a sign-in.

A suffix splits one folder across pages

Add a suffix to put two URLs of the same folder on different pages and tell them apart in the routing:

arizuko token -i demo issue chat acme support
# jid:   web:acme/support

arizuko token -i demo issue chat acme sales
# jid:   web:acme/sales

Both URLs reach the same acme agent. The JID lets route rules act differently, for example with a different persona, a different topic or a different escalation. A suffix is a path segment, not a query parameter. Pick names that are easy to read in the route table.

Signed-in chat is a different surface

/chat/<token>/ is the anonymous bearer URL. Signed-in chat is a private panel of a team member for a folder, behind the OAuth gate of proxyd. webd serves it, and this page does not cover it.

Revoke a link by its JID

arizuko token -i demo revoke web:acme/support

After the revoke, the URL returns 404 at once. Issue a token with the same suffix to get a new URL with the same JID, and replace the URL on the website. No rotation in place exists, because the URL is the credential.

Four pages give the details

route tokens: The bearer model and the JID encoding.
webhooks: The /hook/ URL for machine input.
token reference: The full HTTP surface, the POST and SSE shapes and the env vars.
webd: The daemon that serves /chat/*.